# 监控

> 了解 ServerBee 的实时监控、指标类型、历史数据和数据保留策略。

URL: https://docs.serverbee.app/zh/docs/monitoring

ServerBee 通过统一的 Web 面板实时监控所有已接入的服务器。指标经 WebSocket 流式推送，无需轮询即可即时更新，同时支持历史数据查询和趋势分析。

## 仪表盘概览 [#仪表盘概览]

登录管理面板后，仪表盘页面会一目了然地展示所有已注册服务器的实时状态：

* **顶部统计卡片** -- 在线 / 离线 / 总数、CPU 平均使用率、内存平均使用率、总带宽
* **在线/离线状态** -- 带颜色指示器
* **环形图表网格** -- 每张卡片包含四个环形图（CPU、内存、磁盘、月度**流量配额**使用率）。未配置配额时流量环退化为显示累计传输字节；若设置了计费周期，底部还会显示剩余天数提示
* **磁盘 I/O 吞吐** -- 按设备聚合后的读/写速率，与网络速率并列实时显示
* **网络吞吐** -- 上行 / 下行速率
* **负载趋势** -- `load5 · load15` 紧邻 `load1`，以及 uptime / swap / 进程数 / TCP / UDP 汇总行
* **地区和国旗** -- 启用 GeoIP 时显示

所有数据通过 WebSocket 驱动，无需手动刷新即可实时更新。服务器按分组组织并依据权重排序。你可以在此视图中筛选、搜索和批量操作服务器。

如需创建面向不同场景的运维视图，可以使用 [仪表盘与组件](/zh/docs/dashboards) 创建额外仪表盘布局，包含图表、地图、服务状态、Markdown 说明和可用性时间线等组件。

### GeoIP 显示 [#geoip-显示]

地区/国家标签和 Server Map 组件需要 GeoIP 数据。你可以通过 `geoip.mmdb_path` 配置自定义 MaxMind 兼容 MMDB 文件，也可以在 **Settings → GeoIP Database** 下载 DB-IP Lite 数据库。状态查询端点为 `GET /api/geoip/status`，管理员可通过 `POST /api/geoip/download` 触发下载。

## 实时指标推送 [#实时指标推送]

浏览器端通过 `/api/ws/servers` 连接 WebSocket 后，会收到以下消息：

| 消息类型            | 时机        | 说明           |
| --------------- | --------- | ------------ |
| `FullSync`      | 连接建立时     | 推送所有服务器的当前状态 |
| `Update`        | Agent 上报时 | 推送变更的服务器状态   |
| `ServerOnline`  | Agent 上线时 | 通知某台服务器上线    |
| `ServerOffline` | Agent 离线时 | 通知某台服务器离线    |

因此仪表盘会实时更新，无需刷新页面或设置轮询间隔。

## 指标类型 [#指标类型]

Agent 每 3 秒采集并上报以下指标。Server 在 `Welcome` 消息中下发这一固定的 `report_interval`：

### 系统资源 [#系统资源]

| 指标       | 单位    | 说明                |
| -------- | ----- | ----------------- |
| CPU 使用率  | %     | 所有核心的整体使用率（0-100） |
| 内存使用量    | bytes | 已使用的物理内存          |
| Swap 使用量 | bytes | 已使用的交换空间          |
| 磁盘使用量    | bytes | 所有磁盘的总使用量         |

### 网络指标 [#网络指标]

| 指标     | 单位      | 说明                  |
| ------ | ------- | ------------------- |
| 入站速率   | bytes/s | 当前网络下载速率            |
| 出站速率   | bytes/s | 当前网络上传速率            |
| 入站累计流量 | bytes   | Agent 启动以来累计接收的总字节数 |
| 出站累计流量 | bytes   | Agent 启动以来累计发送的总字节数 |

### 系统负载 [#系统负载]

| 指标      | 说明               |
| ------- | ---------------- |
| 1 分钟负载  | 最近 1 分钟的系统负载平均值  |
| 5 分钟负载  | 最近 5 分钟的系统负载平均值  |
| 15 分钟负载 | 最近 15 分钟的系统负载平均值 |

### 连接和进程 [#连接和进程]

| 指标      | 说明             |
| ------- | -------------- |
| TCP 连接数 | 当前活跃的 TCP 连接数量 |
| UDP 连接数 | 当前活跃的 UDP 连接数量 |
| 进程数     | 当前运行的进程总数      |

### 环境指标 [#环境指标]

| 指标   | 说明             |
| ---- | -------------- |
| 温度   | CPU 温度（摄氏度，可选） |
| 运行时长 | 系统运行时长（秒）      |

### 磁盘 I/O 指标 [#磁盘-io-指标]

Agent 在所有主要平台上采集磁盘读写吞吐量：

| 指标   | 单位      | 说明         |
| ---- | ------- | ---------- |
| 读取速率 | bytes/s | 每块磁盘的读取吞吐量 |
| 写入速率 | bytes/s | 每块磁盘的写入吞吐量 |

**Linux**：直接读取 `/proc/diskstats`。仅跟踪物理块设备（如 `sda`、`nvme0n1`），排除虚拟设备（`loop*`、`dm-*`、`ram*`、`sr*`）和分区。DiskIo.name 为块设备名。

**macOS / Windows**：使用 sysinfo `Disk::usage()` API，以挂载点路径（如 `/`、`/home`、`C:\`）作为 key。提供 per-mount-path 语义而非 per-physical-disk。已知限制：macOS APFS 下共享同一物理磁盘的多个卷可能报告重叠的 I/O 计数。

Agent 启动后的首次采样建立基线并上报空列表，后续采样基于增量计算速率。

磁盘 I/O 数据以 JSON 列（`disk_io_json`）存储在 `records` 和 `records_hourly` 表中。小时聚合器按设备计算平均读写速率。

### GPU 指标（可选） [#gpu-指标可选]

启用 GPU 监控（`enable_gpu = true`）后，每块 GPU 独立采集以下指标：

| 指标      | 说明             |
| ------- | -------------- |
| 设备名称    | GPU 型号名称       |
| GPU 利用率 | GPU 计算核心使用率百分比 |
| 显存使用量   | 已使用的显存（bytes）  |
| 显存总量    | 显存总大小（bytes）   |
| GPU 温度  | 设备温度（摄氏度）      |

## 服务器信息 [#服务器信息]

除了周期性指标外，每个 Agent 在首次连接时还会上报静态系统信息：

* CPU 名称、核心数和架构
* 操作系统和内核版本
* 内存、Swap 和磁盘总容量
* IPv4 和 IPv6 地址
* 虚拟化类型（KVM、Xen、Docker 等）
* Agent 版本

这些信息显示在服务器详情页并存储到数据库中。

## 历史数据和图表 [#历史数据和图表]

ServerBee 以两种粒度存储指标记录：

### 分钟级原始记录 [#分钟级原始记录]

* 由 RecordWriter 后台任务每 60 秒写入一次
* 默认保留 **7 天**（可通过 `retention.records_days` 配置）
* 每条记录捕获某一时间点的全部指标值

### 小时级聚合记录 [#小时级聚合记录]

* 由 Aggregator 后台任务计算
* 取每小时内所有原始记录的平均值
* 默认保留 **90 天**（可通过 `retention.records_hourly_days` 配置）
* 用于长期趋势可视化

仪表盘图表会根据所选时间范围自动在原始记录和小时记录之间切换。

### GPU 记录 [#gpu-记录]

GPU 指标按设备粒度单独存储在专用表中。每条记录包含设备索引、名称、显存、利用率和温度，默认保留 **7 天**（可通过 `retention.gpu_records_days` 配置）。

### 数据查询策略 [#数据查询策略]

历史指标通过 REST API 查询：

```
GET /api/servers/:id/records?from=2026-03-13T00:00:00Z&to=2026-03-14T00:00:00Z&interval=auto
```

`interval` 参数控制数据粒度：

| 参数值      | 说明                                           |
| -------- | -------------------------------------------- |
| `raw`    | 返回分钟级原始记录                                    |
| `hourly` | 返回小时级聚合记录                                    |
| `auto`   | 自动选择：时间范围在 24 小时以内用 `raw`，超过 24 小时用 `hourly` |

### 数据存储层级 [#数据存储层级]

```
Agent 上报 (每 3 秒)
  --> 内存缓存: 仅保留每台服务器最新一份（实时推送用）
  --> 每 1 分钟: 写入 records 表（分钟级记录）
  --> 每 1 小时: 聚合写入 records_hourly 表（平均值）
```

## 服务器详情 [#服务器详情]

每台服务器都有一个详情页，展示以下内容：

* **基本信息** -- 操作系统、CPU 型号、内存总量、IP 地址、地区、Agent 版本
* **实时流式图表**（默认模式） -- 展示 WebSocket 推送的实时指标
* **历史趋势图表** -- 切换到 1h / 6h / 24h / 7d / 30d 查询数据库中的历史记录
* **磁盘 I/O 图表** -- 合并和分盘两种视图（全平台、历史模式）
* **90 天可用性时间线** -- 按天展示可用性状况的彩色条形图
* **GPU 面板** -- 如果该服务器上报了 GPU 数据，显示各 GPU 的利用率和显存图表（仅历史模式）
* **流量统计** -- 网络累计流量的统计信息
* **服务器元数据** -- 分组、标签、备注、定价
* **操作** -- 终端访问、编辑、删除

### 实时图表模式 [#实时图表模式]

服务器详情页默认为**实时模式**，图表展示 WebSocket 推送的实时数据流：

* **数据来源**：通过实时服务器目录订阅 `BrowserMessage::Update` 事件，自动累积数据点
* **更新频率**：约 3 秒一次（与 Agent 上报间隔一致）
* **缓冲区大小**：增长到 250 个数据点后，裁剪为最新的 200 个点
* **去重机制**：基于服务端 `last_active` 时间戳过滤重复事件
* **可用图表**：CPU、内存、磁盘、网络入/出、负载（1 分钟）
* **时间轴格式**：第一个刻度显示 `HH:mm:ss`，后续刻度显示 `mm:ss`

实时模式目前不提供温度、GPU 和磁盘 I/O 图表。WebSocket 的 `BrowserMessage::Update` 消息已在 `LiveMetrics` 中携带磁盘读写汇总速率，但详情页实时图表模型尚未映射这些字段。切换到历史视图可查看温度、GPU 和分盘 I/O 数据。

### 磁盘 I/O 图表 [#磁盘-io-图表]

当存在历史磁盘 I/O 数据时，服务器详情页会显示磁盘 I/O 图表，支持两种视图：

* **合并视图 (Merged)** -- 所有物理磁盘的读写吞吐量汇总
* **分盘视图 (Per Disk)** -- 每块物理磁盘的独立图表（如 `sda`、`nvme0n1`）

两种视图均以面积图展示读取速率（蓝色）和写入速率（绿色）。缺失的数据点会自动补零，保持时间轴连续。

### 可用性时间线 [#可用性时间线]

服务器详情页包含一个可用性卡片，展示 90 天的可用性时间线。每天显示为一根彩色条：

* **绿色** -- 100% 可用
* **黄色** -- 低于黄色阈值（可用性下降）
* **红色** -- 低于红色阈值（严重故障）
* **灰色** -- 无数据

可用性数据通过 `GET /api/servers/{server_id}/uptime-daily?days=90` 查询。端点返回每天一条 `UptimeDailyEntry`，包含 `date`、`online_minutes`、`total_minutes` 和 `uptime_percent` 字段。缺失日期会自动补零。

## 数据保留策略 [#数据保留策略]

ServerBee 自动清理过期数据，由后台任务每小时执行一次：

| 数据类型                     | 默认保留时间 | 配置项                             |
| ------------------------ | ------ | ------------------------------- |
| 分钟级指标 (records)          | 7 天    | `retention.records_days`        |
| 小时级指标 (records\_hourly)  | 90 天   | `retention.records_hourly_days` |
| GPU 指标 (gpu\_records)    | 7 天    | `retention.gpu_records_days`    |
| Ping 探测记录                | 7 天    | `retention.ping_records_days`   |
| 流量小时记录 (traffic\_hourly) | 7 天    | `retention.traffic_hourly_days` |
| 流量日记录 (traffic\_daily)   | 400 天  | `retention.traffic_daily_days`  |
| 任务执行结果 (task\_results)   | 7 天    | `retention.task_results_days`   |
| 审计日志                     | 180 天  | `retention.audit_logs_days`     |

<Callout type="info">
  聚合和清理是两个独立的每小时后台任务，没有固定先后顺序。清理任务以 60 秒偏移启动，这只会错开两者的工作。每次聚合只汇总上一个完整小时，漏掉的小时不会补算；若长期小时历史数据很重要，请监控后台任务错误。
</Callout>

修改保留策略示例：

```toml title="server.toml"
[retention]
records_days = 14          # 分钟级数据保留 14 天
records_hourly_days = 365  # 小时级数据保留 1 年
```

### 磁盘空间估算 [#磁盘空间估算]

数据库增长取决于服务器数量、启用的数据写入功能、采样间隔和保留设置。容量规划请以[存储与容量规划](/zh/docs/storage-sizing)为准，其中提供了 2026 年 4 月的实测数据、统一的 30 天基线、功能乘数和 WAL 预留建议。

## 服务器分组和管理 [#服务器分组和管理]

### 服务器分组 [#服务器分组]

你可以将服务器按用途、地区或其他维度进行分组：

* 创建分组并设置排序权重
* 将服务器分配到不同分组
* 仪表盘按分组展示服务器列表
* 排序权重控制显示顺序（权重越小位置越靠前）
* 未分组的服务器显示在默认区域

分组可以表示环境（生产、预发）、地区（US-East、EU-West）、服务商（AWS、Hetzner）或任何适合你需求的组织结构。

### 服务器标签 [#服务器标签]

除了分组外，还可以为服务器添加多个标签（Tag），用于更灵活的分类和筛选。标签是多对多关系，一台服务器可以有多个标签。

### 服务器管理操作 [#服务器管理操作]

| 操作      | 说明              |
| ------- | --------------- |
| 编辑名称和备注 | 修改服务器的显示名称和备注信息 |
| 设置分组    | 将服务器分配到指定分组     |
| 管理标签    | 添加或移除服务器标签      |
| 调整排序    | 通过权重值控制显示顺序     |
| 隐藏服务器   | 在仪表盘中隐藏指定服务器    |
| 删除服务器   | 移除服务器及其所有历史数据   |
| 批量操作    | 支持批量删除多台服务器     |

## 数据流 [#数据流]

```
Agent                  Server                    浏览器
  |                      |                         |
  |-- Report (3s) ------>|                         |
  |                      |-- 缓存到 AgentManager   |
  |                      |                         |
  |                      |-- RecordWriter (60s) -->|
  |                      |   写入 SQLite           |
  |                      |                         |
  |                      |-- Update (广播) ------->|
  |                      |                     实时 UI
  |                      |                         |
  |                      |-- Aggregator (每小时) ->|
  |                      |   小时级平均值          |
  |                      |                         |
  |                      |-- Cleanup (每小时) ---->|
  |                      |   删除过期记录          |
```

Agent 每 3 秒上报一次。Server 将最新一份上报缓存在内存中，并立即广播给已连接的浏览器。每 60 秒，所有缓存的上报会批量写入 SQLite。两个独立的每小时任务分别将原始记录聚合为小时级汇总，并根据保留策略清理过期数据。

## 网络质量视图 [#网络质量视图]

`/network` 总览页和 `/network/{server_id}` 详情页会汇总每台服务器已配置的探测目标。

* 新分配的目标会立即显示，即使首条探测结果尚未写入
* 尚无探测数据的目标会显示为空状态，而不是从汇总中消失
* 总览页搜索框会跟随当前界面语言显示占位文案

### 时间范围选择器 [#时间范围选择器]

时间范围栏提供以下选项：

| 模式            | 数据来源            | 说明            |
| ------------- | --------------- | ------------- |
| **Real-time** | WebSocket 内存缓冲区 | 实时流式数据（默认）    |
| **1h**        | REST API（原始记录）  | 最近 1 小时的数据库记录 |
| **6h**        | REST API（原始记录）  | 最近 6 小时       |
| **24h**       | REST API（原始记录）  | 最近 24 小时      |
| **7d**        | REST API（小时记录）  | 最近 7 天（聚合数据）  |
| **30d**       | REST API（小时记录）  | 最近 30 天（聚合数据） |

从实时模式切换到历史视图时，系统自动启用 REST API 查询从数据库加载数据。切换回实时模式时，立即显示已累积的缓冲区数据（即使在查看历史数据期间，实时数据也会在后台持续累积）。

## 流量统计 [#流量统计]

ServerBee 以小时和天为粒度跟踪网络流量，支持按计费周期查询用量并提供周期末预测能力。

### 工作原理 [#工作原理]

流量统计集成在现有的指标记录管道中：

1. Agent 每 3 秒上报累计网络字节数（`net_in_transfer`、`net_out_transfer`）
2. RecordWriter 计算连续上报之间的增量，累积到小时级流量记录
3. Aggregator 将小时数据汇总为日级别（通过 `scheduler.timezone` 配置感知时区）
4. Cleanup 任务根据保留策略清理过期的流量记录

### 流量 API [#流量-api]

通过 `GET /api/servers/{id}/traffic` 查询任意服务器的流量统计，返回内容包括：

* **周期总量** -- 当前计费周期的入站/出站总字节数
* **使用百分比** -- 已用流量占服务器流量限额的百分比（如已配置）
* **预测** -- 基于当前消耗速率估算的周期末总用量
* **日明细** -- 计费周期内每日流量总量
* **小时明细** -- 今日每小时流量明细

### 计费周期 [#计费周期]

流量按计费周期查询，周期由以下参数决定：

* **`billing_cycle`** -- 周期类型：`monthly`（默认）、`quarterly` 或 `yearly`
* **`billing_start_day`** -- 计费周期起始日（1-28，默认 1）

例如，`billing_start_day = 15` 且 `billing_cycle = monthly` 时，周期从每月 15 日开始到下月 14 日。

### 前端展示 [#前端展示]

服务器详情页显示可折叠的流量卡片，包含：

* **进度条** -- 可视化显示已用流量占限额的比例
* **日图表** -- 柱状图展示周期内每日入站/出站流量
* **小时图表** -- 柱状图展示今日每小时流量
* **预测** -- 预计周期末总用量

### 数据保留 [#数据保留]

| 数据类型   | 默认保留时间 | 配置项                             |
| ------ | ------ | ------------------------------- |
| 流量小时记录 | 7 天    | `retention.traffic_hourly_days` |
| 流量日记录  | 400 天  | `retention.traffic_daily_days`  |

### 调度时区 [#调度时区]

日级流量聚合遵循 `scheduler.timezone` 设置。将其设为你的计费时区（如 `Asia/Shanghai`），确保日统计与你的服务商日边界一致。

## Docker 容器监控 [#docker-容器监控]

ServerBee 支持实时 Docker 容器监控。当 Agent 能够访问 Docker daemon 时，此功能可用。需要 `docker` 能力（`CAP_DOCKER`），该能力默认关闭。能力由 Agent 拥有 —— 在 Agent 主机的 `[capabilities]` allow 列表中加入 `docker`（或 `--allow-cap docker`）并重启 Agent。见 [功能开关](/zh/docs/capabilities)。

### 概览 [#概览]

Docker 监控页面展示：

* **概览卡片** -- 运行中/已停止容器数量、总 CPU 使用率、总内存使用量、Docker 版本
* **容器列表** -- 可搜索、可过滤的表格，包含名称、镜像、状态、CPU%、内存、网络 I/O
* **事件时间线** -- 容器生命周期事件（start、stop、die、create、destroy），按时间倒序排列
* **网络弹窗** -- Docker 网络列表，包含驱动、作用域和容器数量
* **卷弹窗** -- Docker 卷列表，包含驱动、挂载点和创建时间

### 容器详情 [#容器详情]

点击任意容器行可查看：

* **容器信息** -- 镜像、状态、端口、创建时间、容器 ID
* **统计卡片** -- CPU 使用率、内存（含进度条）、网络 I/O、块 I/O
* **日志流** -- 实时日志输出：
  * stdout 白色文本，stderr 红色文本
  * Follow 开关控制自动滚动
  * Clear 按钮清空日志
  * 连接状态指示器（Connected/Disconnected）

### 工作原理 [#工作原理-1]

1. 浏览器导航到 Docker 页面时，通过 WebSocket 发送 `DockerSubscribe` 消息
2. Server 指示已连接的 Agent 启动 Docker 监控
3. Agent 使用 bollard Docker API 客户端轮询容器和统计数据
4. 更新实时广播到订阅的浏览器
5. 当所有浏览器离开 Docker 页面时，监控自动停止（基于 viewer 引用计数）

容器日志使用专用 WebSocket 端点（`/api/ws/docker/logs/{server_id}`），通过 subscribe/unsubscribe 协议实现按容器的日志流。

### 数据保留 [#数据保留-1]

| 数据类型      | 默认保留时间 | 配置项                            |
| --------- | ------ | ------------------------------ |
| Docker 事件 | 7 天    | `retention.docker_events_days` |

容器统计数据和日志不持久化存储，仅实时流式传输。

## 网络质量监控 [#网络质量监控]

ServerBee 内置了网络质量监控系统，通过各 Agent 对网络目标发起探测，可视化延迟、丢包率和异常情况。

### 预设目标 [#预设目标]

96 个预设探测目标嵌入在服务端二进制中（不存储在数据库）：

* **中国电信** -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
* **中国联通** -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
* **中国移动** -- 31 个省级节点（TCP 探测，使用 Zstatic CDN）
* **国际节点** -- Cloudflare (1.1.1.1)、Google DNS (8.8.8.8)、AWS Tokyo（ICMP 探测）

中国节点使用域名（`{省代码}-{运营商代码}-v4.ip.zstaticcdn.com:80`），DNS 自动解析到最新的 CDN 节点 IP，无需手动维护 IP 列表。

预设目标为只读，不可编辑或删除。你也可以通过设置页创建自定义目标。

### 配置 [#配置]

前往 **设置 > 网络探测** 进行配置：

* **目标管理** -- 查看所有 96 个预设目标（带锁图标和运营商标签），管理自定义目标（创建/编辑/删除）
* **全局设置** -- 探测间隔（30-600 秒，默认 60）、每轮发包数（5-20，默认 10）、新服务器默认分配的探测目标
* **单服务器目标** -- 通过网络详情页的「管理目标」弹窗，为每台服务器分配最多 20 个探测目标

### 网络总览页 [#网络总览页]

`/network` 页面为每台服务器展示一张卡片，包含：

* 目标数量和平均延迟
* 可用性百分比
* 异常数量及严重性指示

### 网络详情页 [#网络详情页]

点击服务器卡片进入 `/network/:serverId`，包含：

* **时间范围选择** -- 实时、1h、6h、24h、7d、30d
* **目标卡片** -- 每个目标的延迟和丢包率，可切换显示/隐藏
* **多线延迟图表** -- 每个目标一条彩色线，带时间戳 Tooltip
* **异常摘要表** -- 高延迟、高丢包、不可达事件
* **统计栏** -- 综合平均延迟、可用性百分比、目标数量
* **CSV 导出** -- 下载选定时间范围的探测数据

### Traceroute [#traceroute]

网络详情页可以从选中的 Agent 对目标主机或 IP 发起 Traceroute，用于排查路由变化和丢包问题。

* 需要 Agent 的 effective `CAP_PING_ICMP` 能力。
* 目标只允许字母、数字、点、连字符和冒号。
* Dialog 提供 ICMP / UDP / TCP 三种探测协议下拉选择。
* 默认跑 5 轮，每轮一次增量更新通过 WebSocket 推送到浏览器，表格实时填充：
  Hop / IP / 主机名 / ASN / 丢包率 / Best / Avg / Worst / Jitter / StdDev。
* ECMP 多路径时同一 TTL 会有多个 IP，第一行显示主 IP，悬停 `+N` chip 查看其他 IP。
* 已完成的 Traceroute 自动保存到本地 SQLite，可以在 dialog 历史区点击切换查看；
  管理员可以删除单条或一键清空。
* 触发 trace 需要管理员权限；只读用户能浏览历史，但不能发起新 trace 或删除记录。

#### 权限 [#权限]

ServerBee Agent 现在内嵌 [trippy-core](https://crates.io/crates/trippy-core) 直接发起 raw ICMP/UDP/TCP 包，
**不再依赖系统的 `traceroute` / `mtr` 二进制**。但 raw socket 仍需要操作系统级权限：

| 平台      | 要求                                                                                   |
| ------- | ------------------------------------------------------------------------------------ |
| Linux   | `CAP_NET_RAW` 或以 root 运行。一次性配置：`sudo setcap cap_net_raw+ep $(which serverbee-agent)` |
| macOS   | 以 root 运行 (sudo)，或部分场景下可走 unprivileged ICMP datagram socket                          |
| Windows | 以 Administrator 身份启动 Agent                                                           |

权限不足时 Traceroute 会立刻返回带平台对应安装提示的错误消息，不需要重启 Agent。

#### API 流程 [#api-流程]

```http
POST   /api/servers/{id}/traceroute          { target, protocol? }   → { request_id }
GET    /api/servers/{id}/traceroute/{rid}    → 最新快照（含 protocol/started_at/round/total_rounds 等完整字段）
GET    /api/servers/{id}/traceroute          → 该服务器的历史记录摘要列表，按时间倒序
DELETE /api/servers/{id}/traceroute/{rid}    → 删除单条（admin）
DELETE /api/servers/{id}/traceroute          → 清空全部（admin）
```

WebSocket 推送 `BrowserMessage::TracerouteUpdate` 携带每轮增量结果。客户端在断开重连时可通过 GET 单条接口拉取最新累计快照。

### 数据保留 [#数据保留-2]

网络探测记录采用与系统指标相同的两级存储：

* **原始记录** -- 保留 7 天（可通过 `retention.network_probe_days` 配置）
* **小时聚合** -- 保留 90 天（可通过 `retention.network_probe_hourly_days` 配置）

### 告警集成 [#告警集成]

两种告警规则类型可用于网络质量：

* `network_latency` -- 当平均延迟超过阈值时触发
* `network_packet_loss` -- 当丢包率超过阈值时触发

<Cards>
  <Card title="告警与通知" href="/zh/docs/alerts" />

  <Card title="架构设计" href="/zh/docs/architecture" />

  <Card title="配置参考" href="/zh/docs/configuration" />
</Cards>