# 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 端点

聚合展示三层数据：

```json
{
  "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` |