# Ping 监控
> 通过 ICMP、TCP 和 HTTP 探测监控网络可达性和延迟。
URL: https://docs.serverbee.app/zh/docs/ping
ServerBee 内置 Ping 监控功能，通过分布在不同服务器上的 Agent 对目标地址进行周期性探测，监测网络可达性和响应延迟。它适用于验证网络连通性、对比不同地区的延迟以及发现服务中断。
## 探测类型 [#探测类型]
ServerBee 支持三种探测类型。每种都会测量往返延迟并上报成功 / 失败状态。
| 类型 | 探测内容 | 目标格式 | 超时 | 权限要求 |
| -------- | -------------------- | -------------------------------------- | ---- | ---------------------- |
| **ICMP** | 标准 ICMP Echo 请求 / 应答 | IP 或域名（如 `1.1.1.1`、`google.com`） | 10 秒 | Linux 下需 `CAP_NET_RAW` |
| **TCP** | TCP 连接测试（握手） | `host:port`（如 `google.com:443`） | 10 秒 | 无 |
| **HTTP** | HTTP(S) GET 请求与响应时间 | 完整 URL（如 `https://example.com/health`） | 10 秒 | 无 |
## 创建 Ping 任务 [#创建-ping-任务]
在管理面板的「Ping 探测」页面创建探测任务，也可通过 API 创建。每个任务需要配置：
| 配置项 | 说明 |
| ---- | ------------------------- |
| 任务名称 | 用于标识的名称，如「Cloudflare DNS」 |
| 探测类型 | `icmp`、`tcp` 或 `http` |
| 目标地址 | 待探测的目标（格式取决于探测类型） |
| 探测间隔 | 探测频率，单位秒 |
| 执行节点 | 选择哪些 Agent 执行此探测 |
| 启用状态 | 是否启用此任务 |
### 示例：ICMP Ping [#示例icmp-ping]
监控到 Cloudflare DNS 的基本连通性：
| 配置项 | 值 |
| ---- | -------------- |
| 名称 | Cloudflare DNS |
| 探测类型 | icmp |
| 目标 | 1.1.1.1 |
| 间隔 | 60 |
### 示例：TCP 端口检查 [#示例tcp-端口检查]
验证数据库端口是否可达：
| 配置项 | 值 |
| ---- | ------------------ |
| 名称 | PostgreSQL Primary |
| 探测类型 | tcp |
| 目标 | db.internal:5432 |
| 间隔 | 30 |
### 示例：HTTP 健康检查 [#示例http-健康检查]
监控一个 Web 服务端点：
| 配置项 | 值 |
| ---- | ---------------------------------------------------------------- |
| 名称 | API Health |
| 探测类型 | http |
| 目标 | [https://api.example.com/health](https://api.example.com/health) |
| 间隔 | 60 |
## 目标格式 [#目标格式]
不同探测类型的目标格式要求：
| 探测类型 | 目标格式 | 示例 |
| ---- | --------- | --------------------------------------------------- |
| ICMP | IP 地址或域名 | `1.1.1.1`、`google.com` |
| TCP | host:port | `example.com:443`、`10.0.0.1:3306` |
| HTTP | 完整 URL | `https://example.com`、`http://10.0.0.1:8080/health` |
## 间隔设置 [#间隔设置]
探测间隔以秒为单位，建议根据目标的重要性和探测类型合理设置：
| 场景 | 建议间隔 |
| ------ | --------- |
| 关键服务监控 | 15-30 秒 |
| 常规网站监控 | 60 秒 |
| 基础设施检查 | 120-300 秒 |
过短的探测间隔会增加 Agent 的负载和网络开销，也可能被目标服务器的防火墙策略或限流拦截。建议根据实际需求合理设置。
## 任务分发同步 [#任务分发同步]
创建或更新 Ping 任务时，Server 会将其同步到对应的 Agent：
1. Server 将任务配置存入数据库
2. 向每个被分配的 Agent 发送 `PingTasksSync` 消息，包含该 Agent 的全部活跃任务
3. 各 Agent 启动（或更新）本地的探测调度器
4. 探测结果以 `PingResult` 消息回传给 Server
Server 在以下时机会向 Agent 同步探测任务：
* Agent 首次连接或重连时
* 管理员创建、修改或删除探测任务时
当某个 Agent 断开并重连后，Server 会自动重新同步其全部已分配的 Ping 任务。
## 界面反馈 [#界面反馈]
在 Web 控制台中，创建、删除、启用、禁用 Ping 任务都会根据当前语言显示对应的成功或失败提示。启用 / 禁用请求发送期间，切换按钮会暂时禁用，以减少误触的重复提交。
## 分配执行节点 [#分配执行节点]
`server_ids_json` 字段控制哪些 Agent 执行探测：
* **指定节点**：填写服务器 ID 数组，如 `["srv-1", "srv-2"]`
* **全部节点**：使用空数组 `[]`
`["*"]` 不是通配符。Server 会把它当作字面量服务器 ID，因此通常不会把任务分配给任何 Agent。需要所有服务器执行时请使用 `[]`；指定服务器时，请使用服务器列表中的真实 ID。
从多个 Agent 执行同一探测可以：
* 从不同地区同时探测同一目标，对比各地的网络质量
* 排除单点网络问题的干扰，更准确地判断目标可用性
* 当某个节点探测失败而其他节点成功时，将故障定位到探测节点一侧
## 查看结果与延迟图表 [#查看结果与延迟图表]
### 探测记录 [#探测记录]
每次探测的结果会存入数据库，包含以下信息：
| 字段 | 说明 |
| ----------- | ----------- |
| `task_id` | 关联的 Ping 任务 |
| `server_id` | 执行探测的 Agent |
| `latency` | 往返延迟，单位毫秒 |
| `success` | 探测是否成功 |
| `error` | 失败时的错误信息 |
| `time` | 探测执行时间 |
### 延迟图表 [#延迟图表]
在 Ping 任务详情页面，可以查看每个执行节点的延迟趋势图。图表支持按时间范围筛选，帮助你分析网络质量变化趋势。当多个节点探测同一目标时，结果会按节点拆分展示，并显示成功率百分比。
### API 查询 [#api-查询]
通过 REST API 查询探测记录：
```
GET /api/ping-tasks/:id/records?from=2026-03-13T00:00:00Z&to=2026-03-14T00:00:00Z&server_id=xxx
```
支持按时间范围和执行节点筛选。
## 数据保留 [#数据保留]
Ping 记录默认保留 **7 天**，可通过 `server.toml` 的 `retention.ping_records_days` 配置：
```toml
[retention]
ping_records_days = 14
```
清理任务每小时执行一次，移除超过保留期的记录。
## 与告警集成 [#与告警集成]
Ping 监控可以与告警规则结合使用。通过 `network_latency` 和 `network_packet_loss` 规则类型，可针对探测延迟或丢包配置告警，在关键目标性能下降或不可达时及时收到通知。Ping 数据与常规监控数据一并存储，可复用同一套告警基础设施。详见 [告警与通知](/zh/docs/alerts)。