PingWatch 连通性监测与企业微信告警改造设计

日期： 2026-08-03
状态： 已确认，待实现
需求编号： PINGWATCH_(可靠性监测)_001
目标能力等级： 暂按 C1 基线，待项目负责人确认

1. 目标、范围与验收

1.1 目标

将现有的批量 ICMP 连通性检测改造成可区分离线与业务故障的监测系统，并向企业微信应用可见部门发送及时、可追溯的通知。

编号	可验证需求	验收条件
`PINGWATCH_(可靠性监测)_001_01`	及时发现离线设备	每 30 秒检测一轮，每轮 3 个 ICMP 包；连续 2 轮 100% 丢包进入 `offline` 并创建/通知事件。
`PINGWATCH_(可靠性监测)_001_02`	识别影响业务的间歇性丢包	最近 5 轮（15 包）丢包率不低于 20%、但未离线时进入 `degraded` 并通知。
`PINGWATCH_(可靠性监测)_001_03`	发现设备恢复	已告警设备连续 3 轮零丢包后进入 `online`，关闭关联事件并通知恢复。
`PINGWATCH_(可靠性监测)_001_04`	通知可靠可追溯	企业微信调用失败时事件保留，按有限退避重试；每次投递结果可查询。
`PINGWATCH_(可靠性监测)_001_05`	Ubuntu/OpenResty 运行	以 `http://10.10.10.14:<port>` 提供访问；OpenResty 承载静态站点并反代 API/WebSocket。

1.2 非目标

不增加未授权网段扫描、端口扫描或资产发现。
不在首期实现按历史基线自动学习阈值。
不自建企业微信成员/部门管理，应用可见范围及接收部门由企业微信管理端控制。

1.3 数据分类与风险

设备名称、IP、位置、项目和告警记录按内部运维数据处理；企业微信密钥、JWT 密钥、数据库口令和 OAuth 凭据为敏感配置。
主要风险：网络抖动误告警、监控节点自身断网、企业微信不可用、存储膨胀、特权过大、凭据泄露。

2. 方案比较与决策

方案	优点	缺点	决策
单包连续失败阈值	简单	无法量化间歇性丢包	不采用
多包探测 + 滑动窗口状态机	规则可解释、及时且抗抖动	需要保存汇总数据	采用
自适应历史基线	对不同链路更精细	学习期、复杂度和解释成本高	后续评估

3. 架构与数据流

受管 IP → fping 批量探测 → 轮次汇总/状态机 → 事件出箱 → 企业微信应用（应用可见范围）
                              │                   │
                              ├→ PostgreSQL ←──────┤
                              └→ API/WebSocket → OpenResty → 浏览器（IP:端口）

调度器不允许检测轮次重叠；每 30 秒加载启用设备并批量执行 fping。
一轮记录每台设备的发包数、收包数、丢包率、平均 RTT 与结果有效性。命令或解析异常产生系统事件，不能被当作设备丢包。
状态机基于最新有效检测记录计算状态；状态改变时原子地写入领域事件和待投递记录。
投递 worker 从数据库读取待发送记录，向企业微信应用发送应用消息；由企业微信应用的可见范围限定接收部门。成功、失败、下次重试时间均持久化。
前端通过 API/WebSocket 展示设备当前健康度、最近丢包率、时延与事件投递结果。

4. 状态机与告警规则

现状态	条件	新状态	动作
`unknown` / `online`	连续 2 轮均 100% 丢包	`offline`	创建离线事件，进入待通知队列。
`unknown` / `online`	最近 5 轮丢包率 ≥20%，且不满足离线	`degraded`	创建业务故障事件，进入待通知队列。
`degraded`	满足离线规则	`offline`	升级现有故障事件，通知离线。
`offline` / `degraded`	连续 3 轮零丢包	`online`	关闭未恢复事件，发送恢复通知。
任意	无有效检测结果	保持原状态	创建受限频率的系统事件；不发送设备故障通知。

同一事件只在首次状态变更时通知；未恢复事件默认每 4 小时提醒一次，间隔可配置。
每个设备可覆盖全局规则：检测间隔、单轮发包数、离线轮数、故障窗口、故障丢包率、恢复轮数和提醒间隔。
上游心跳失败或单轮大面积离线时，创建“监控节点异常/批量故障”系统事件并通知；不将设备事件静默丢弃。

5. 数据、接口与页面

5.1 数据模型

扩展 ping_records：sent_count、received_count、packet_loss_percent、average_rtt_ms、is_valid、failure_reason。
扩展 devices：监测策略覆盖字段与 current_status（加入 degraded）。
扩展 alert_events：加入 degraded、状态变更前后值、关联恢复事件、通知尝试数、最后通知错误和下一次通知时间。
新增 notification_outbox：为每个待发送通知保存内容摘要、投递范围摘要、状态、尝试次数、锁定时间和投递结果。

数据库变更应使用可重复执行、可回退的迁移；保留现有数据。

5.2 API 与 UI

设备 API 返回当前状态、最新有效结果和设备级策略；创建、编辑、批量导入均校验 IPv4/IPv6、数值范围、单文件大小、字符编码及重复 IP。
告警 API 支持 offline、degraded、recovered、system 筛选，并返回持续时长、恢复关联和通知状态。
设备列表展示“在线/故障/离线/未知”、最近丢包率、时延和最近检测时间；告警页展示事件、持续时间和投递状态。

6. 企业微信与错误处理

应用使用环境变量提供的 Corp ID、Agent ID、Secret；默认向应用可见范围内的成员发送，接收部门仅在企业微信应用管理端配置。若后续需要缩小范围，可增加受控的 WECOM_TO_PARTY 环境变量，不在系统页面维护接收人。
access token 仅在进程内带有效期缓存；请求使用明确连接/读取超时。失败事件按有限次数的指数退避重试，达到上限后标记失败，保留人工处理证据。
日志只记录错误码、事件 ID、设备 ID、轮次和重试次数；不得记录 token、secret、口令或完整敏感响应。
认证/OAuth 必须校验证书与 JWT 签名；不得以 verify=False 或未验签方式绕过校验。

7. Ubuntu + OpenResty 部署

宿主机 OpenResty 监听指定 IP 端口，直接提供前端构建目录，反向代理 /api/ 和 /ws/ 至 127.0.0.1 后端端口。
Docker Compose 运行后端和 PostgreSQL；PostgreSQL 不映射宿主机端口，后端只绑定回环地址。
OpenResty 配置 WebSocket Upgrade、超时、请求体大小限制、访问日志与健康检查路由。没有域名时首期在受控内网使用 HTTP；需要 TLS 时由企业内部 CA 或含 IP SAN 的证书在 OpenResty 终止。
后端容器按最小权限运行，移除 NET_ADMIN，仅保留探测所需的 NET_RAW；所有运行密钥由受控环境文件注入，不进入 Git 或镜像。
交付运行手册，包括配置清单、备份/恢复、启动/停止、OpenResty 重载、健康检查、升级和回退。发布前执行备份与冒烟检查。

8. 测试和首批验收

单元测试：状态转移、阈值、窗口计算、防抖、事件去重、过期提醒、企业微信重试、IP/CSV/配置校验。
集成测试：异步数据库迁移、API 权限、出箱持久化、推送失败恢复、调度器不重叠。
部署测试：Compose 启动、OpenResty 反向代理、WebSocket、健康检查、PostgreSQL 不可从宿主机访问、容器能力最小化。
运行验证：使用明确授权的测试 IP 验证离线、间歇丢包、恢复、监控节点异常和部门通知。

9. 合规控制与可追溯性

分类	控制	依据/说明
规范要求（C1）	部署前完成测试并提交报告；提供版本、制品/代码关联、部署计划、操作步骤、回退及备份方案；部署后按用例验证。	`13-deployment.md` §2.2.1、§2.2.2、§2.6。
规范要求	防止将不可信输入用于拼接 SQL、命令执行或不安全文件上传。	`12-security.md` §3.6.1.1、§3.6.1.3、§3.6.2.2。
规范要求	生产变更前开启主机安全管控与防火墙，并纳入运行状态监控。	`12-security.md` §5.1（强制）。
工程建议	使用事务性事件出箱、状态机防抖、最小容器能力、依赖/密钥扫描与版本固定。	可靠性和安全工程实践，不宣称为上述规范的特定强制目录或工具。
待确认	项目最终 C 级别、企业微信部门 ID、对外端口、内网 TLS 要求、备份责任人和部署审批人。	由项目负责人/运行方确认。

需求、设计、实现、测试、制品和部署记录应通过上述需求编号建立双向关联。实现完成后补充追踪矩阵和实际证据。

8.9 KiB Raw Blame History Unescape Escape