170 lines
6.8 KiB
Markdown
170 lines
6.8 KiB
Markdown
# 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` |
|