AgentsMeeting/docs/HEALTH-PIPELINE.md

AgentsMeeting — 健康监控管线

版本: v1.0 | 部署目标: Linux 246

---

概述

三层监控 + 两级自修复，零人工干预。所有组件在 246 上运行，通过 crontab 调度。

                    ┌─────────────────────────────────┐
                    │        Dashboard F Tab          │
                    │   /api/monitor 聚合展示          │
                    └──────────┬──────────────────────┘
                               │ 读取报告文件
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
   ┌────▼─────┐          ┌────▼─────┐          ┌─────▼────┐
   │ Tier 1   │          │ Tier 2   │          │ 自动修复  │
   │ 每 5 分钟 │          │ 每天 8:00│          │ 双引擎    │
   └────┬─────┘          └────┬─────┘          └─────┬────┘
        │                     │                      │
   agents_health_check  agents_daily_health    auto_heal (Linux侧)
        │                     │               self_todo_executor
        │                     │                      │
   ┌────▼─────┐          ┌────▼─────┐          ┌─────▼────┐
   │ 端口+HTTP │          │ 端口+HTTP │          │ systectl │
   │ 6 个服务  │          │ +磁盘+cron│          │ restart  │
   │          │          │ +看门狗   │          │ docker   │
   └────┬─────┘          └────┬─────┘          │ restart  │
        │ 异常→TODO           │ 异常→建议        └──────────┘
   ┌────▼─────┐
   │ TODO 文件 │
   │ .jsonl   │
   └──────────┘

---

Tier 1: 快速健康检查（每 5 分钟）

脚本: gateway/scripts/agents_health_check.py 调度: crontab: */5 * * * *

检查内容:

• 6 个服务：dashboard、hermes_gateway_mohe、hermes_gateway_zhiwei、wechat_bridge、xmpp_bot_xxm、article_processor
• 检查方式：socket 端口连接 + HTTP /health 端点
• 本机服务用 127.0.0.1，远程服务用实际 IP + 更长超时
• 全正常时静默（不输出、不写日志）

异常处理:

• 写入 gateway/temp/health_todos.jsonl
• 每条 TODO 包含：服务名、失败原因、时间戳
• 写入 gateway/temp/last_health_check.json 供 Dashboard 读取

日志: gateway/logs/health_check_report.log 报告: gateway/temp/last_health_check.json

---

Tier 2: 每日全面检查（每天 08:00）

脚本: gateway/scripts/agents_daily_health.py 调度: crontab: 0 8 * * *

在 Tier 1 基础上增加:

• 磁盘空间检查（shutil.disk_usage，阈值 10G 警告 / 2G 严重）
• crontab 存活检查（验证关键定时任务是否在 crontab 中）
• 看门狗日志新鲜度（超过 1 小时未更新 → 告警）
• 生成结构化 JSON 报告 + 人类可读日志

输出:

• gateway/temp/last_daily_health.json — JSON 报告
• gateway/logs/daily_health_report.log — 人类可读日志

---

自动修复：双引擎

引擎 A: auto_heal（Linux 侧，每 5 分钟）

脚本: gateway/scripts/auto_heal.py 调度: crontab: */5 * * * *

工作原理:

1. 调用 Dashboard /api/expected 获取所有 critical 服务的期望状态
2. 对实际状态为异常且 host 为本机（is_local_host()）的服务执行修复
3. 通过 SERVICE_UNIT_MAP 查找对应的 systemd 单元并 systemctl restart
4. Docker 容器通过 DOCKER_MAP 映射后用 docker restart
5. 记录修复动作到 gateway/temp/last_auto_heal.json

可修复的服务:

服务	修复命令
hermes_gateway_mohe	systemctl restart hermes-gateway@mohe
hermes_gateway_zhiwei	systemctl restart hermes-gateway@zhiwei
dashboard	systemctl restart agentsmeeting-dashboard
wechat_bridge	docker restart wxBotWebhook

不可修复（远程服务）: xmpp_bot_xxm（Windows）、article_processor（Windows）

引擎 B: self_todo_executor（每 10 分钟）

脚本: gateway/scripts/self_todo_executor.py 调度: crontab: */10 * * * *

工作原理:

1. 读取 health_todos.jsonl 中 status=pending 的条目
2. 通过 FIX_MAP 查找对应修复命令并执行
3. 成功 → 标记 completed
4. 失败 → 标记 failed
5. "already running" 错误 → 标记 completed（服务已在运行）

与 auto_heal 的分工:

• auto_heal 从 Dashboard API 视角出发，修复本机服务（systemd/docker）
• self_todo_executor 从 Tier 1 检查视角出发，消费 TODO 文件
• 两者互补，auto_heal 负责 Linux 本机，executor 也能处理跨机场景

---

Dashboard 集成

/api/monitor 端点

聚合展示三层数据：

{
  "tasks": [
    {"name": "agents-health-check", "status": "cron_ok"},
    {"name": "agents-daily-health", "status": "cron_ok"},
    {"name": "agents-todo-executor", "status": "cron_ok"}
  ],
  "tier1": { "services": [...], "summary": {"ok": 6, "total": 6} },
  "tier2": { "services": [...], "summary": {"ok": 6, "total": 6} }
}

F Tab 展示

• Layer 1: 系统概览（服务数、异常数、T1 监控通过率）
• Layer 2: 异常服务列表（影响描述 + 状态）
• Layer 3: 全部服务按层级排列（通信层 / AI网关 / 辅助服务）
• 定时任务: 三个 crontab 任务状态（绿色=正常）
• 自动修复记录: auto_heal 最近一次修复动作

---

如何新增监控

1. 添加服务到 Tier 1 — 编辑 agents_health_check.py 的 SERVICES 列表
2. 添加服务到 Tier 2 — 编辑 agents_daily_health.py 的 SERVICES 列表
3. 添加修复命令 — 在 auto_heal.py 的 SERVICE_UNIT_MAP 和 self_todo_executor.py 的 FIX_MAP 中增加映射
4. 更新 Dashboard — 在 dashboard.py 的 /api/expected 中添加检查条目
5. 写 Spec — 在 gateway/scripts/specs/ 创建 {module}.json

---

故障排查

现象	检查
任务显示"未部署"	crontab -l | grep health 确认条目存在
Tier1 无数据	检查 gateway/temp/last_health_check.json 是否存在
TODO 堆积不减少	检查 self_todo_executor.py 是否在 crontab 中
修复失败	查看 gateway/logs/todo_executor.log
auto_heal 不工作	查看 gateway/logs/auto_heal.log