auto-sync: 2026-06-02 22:03:37

docs/design/gateway-watchdog.md

@@ -1,144 +1,161 @@
 # Gateway Watchdog 设计文档
 
-**版本**: 1.0
+**版本**: 2.0
 **作者**: 庞统（副军师）🐦
-**日期**: 2026-05-28
+**日期**: 2026-06-02
 **状态**: 已实现
 
 ---
 
 ## 1. 问题背景
 
-zhipu GLM-5.1 在高峰期返回 **429 限流**（"该模型当前访问量过大，请您稍后再试"，errorCode=1305），导致：
+### 1.1 历史问题（v1.0 覆盖）
 
-1. Gateway 调用失败，`stopReason=error`
-2. Session 进入 stalled 状态
-3. stalled 后无法自动恢复，必须手动重启 Gateway
-4. 所有 Agent 假死，直到人工介入
+zhipu GLM-5.1 在高峰期返回 **429 限流**，导致 Gateway 假死。
 
-### 历史记录
+### 1.2 新增问题（v2.0 新增）
 
-- 2026-05-26 09:00 CST — 429 导致假死
-- 2026-05-28 ~10:00 CST — 429 导致假死，持续约 1 小时
-- 累计 9 次 session.stalled 事件
+线上观察发现两种新的致命信号，Gateway 自身无法恢复，必须重启：
 
-## 2. 双层防护
+| 信号 | 日志关键字 | 现象 |
+|------|-----------|------|
+| **所有 provider 挂了** | `lane task error` + `FailoverError` | 主模型 + fallback 全部失败，所有 Agent 无法工作 |
+| **Session 卡死** | `stalled session` + `recovery=none` | Gateway diagnostic 检测到 session 卡死但承认自己恢复不了 |
 
-### 2.1 第一层：跨 Provider Fallback（立即生效）
+### 1.3 为什么 v1.0 检测不到
 
-**配置**: `~/.openclaw/openclaw.json`
+v1.0 扫描的是 **session jsonl**（`~/.openclaw/agents/*/sessions/*.jsonl`），但这些关键字实际出现在 **Gateway 进程日志**（`/tmp/openclaw/openclaw-{日期}.log`）中。两类日志的数据格式完全不同。
 
+## 2. 检测规则（v2.0）
+
+### 2.1 数据源
+
+**Gateway 进程日志**：`/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log`
+
+- JSON lines 格式，每行一条记录
+- 关键字在 `"message"` 字段中（也在 `"1"` 字段中有副本）
+- 每天自动轮转，watchdog 只读当天文件
+
+### 2.2 三条规则
+
+| 规则 | 匹配条件 | 阈值 | 含义 | 严重度 |
+|------|---------|------|------|--------|
+| **R1** | `message` 含 `lane task error` **且** 含 `FailoverError` | ≥2 次/120s | 所有 provider 都挂了，不重启没救 | 🔴 致命 |
+| **R2** | `message` 含 `stalled session` **且** 含 `recovery=none` | ≥3 次/120s | Gateway 承认自己恢复不了 | 🟠 严重 |
+| **R3** | `message` 含 `rate_limit` **或** 含 `"429"` | ≥2 次/120s | API 限流 | 🟡 警告 |
+
+### 2.3 匹配示例
+
+**R1 匹配日志行**：
 ```json
-{
-  "model": {
-    "primary": "zhipu/glm-5.1",
-    "fallbacks": ["deepseek/deepseek-v4-pro"]
-  }
-}
+{"_meta":{"logLevelName":"ERROR"},"message":"lane task error: lane=main durationMs=93772 error=\"FailoverError: ⚠️ API rate limit reached. Please try again later.\""}
 ```
 
-- zhipu 429 时自动切 deepseek（不同 provider，不会一起死）
-- deepseek-v4-pro 也是免费的，支持 1M 上下文
-- Gateway 原生支持，无需额外代码
-
-### 2.2 第二层：Watchdog 自动重启（兜底）
-
-即使 fallback 也失败（所有 provider 同时挂），watchdog 检测到连续 429 后自动重启 Gateway。
-
-## 3. Watchdog 设计
-
-### 3.1 检测原理
-
-**数据源**: Gateway 的 session jsonl 日志
-
-```
-~/.openclaw/agents/{agent-id}/sessions/*.jsonl
-```
-
-**429 精确特征**:
+**R2 匹配日志行**：
 ```json
-{
-  "message": {
-    "stopReason": "error",
-    "errorCode": "1305",
-    "errorMessage": "429 该模型当前访问量过大，请您稍后再试"
-  }
-}
+{"_meta":{"logLevelName":"WARN"},"message":"stalled session: sessionKey=agent:main:main state=processing age=266s recovery=none"}
 ```
 
-**判定条件**（全部满足才算 429）:
-1. `stopReason === "error"`
-2. `errorMessage` 包含 `"429"` 或 `errorCode` 为 `"1305"`
+**R3 匹配日志行**：
+```json
+{"_meta":{"logLevelName":"WARN"},"message":"lane task error: ... error=\"FailoverError: ...\"","providerRuntimeFailureKind":"rate_limit"}
+```
 
-**不会误判**:
-- 正常 stop（`stop=stop`、`stop=toolUse`）不算
-- 其他 error（如 context overflow 的 errorCode 不同）不算
-- `stopReason` 不是 `"error"` 的不算
-
-### 3.2 检测流程
+### 2.4 判定逻辑
 
 ```
 每分钟执行
-    │
-    ├─ Gateway health check
-    │   ├─ 失败 → 直接重启（可能 Gateway 进程已死）
-    │   └─ 成功 → 继续
-    │
-    ├─ 遍历所有 agent session jsonl
-    │   ├─ 跳过 trajectory 文件
-    │   ├─ 跳过 120 秒内未修改的文件（性能优化）
-    │   ├─ 跳过 <100 字节的文件
-    │   └─ 统计 CHECK_WINDOW(120s) 内的 429 错误数
-    │
-    ├─ 判断
-    │   ├─ 有新 429 → consecutive++
-    │   └─ 无新 429 → consecutive=0（重置）
-    │
-    └─ consecutive >= THRESHOLD(3) → 重启 Gateway + 重置计数
+  │
+  ├─ 1. Gateway health check
+  │   └─ 失败 → 直接重启（可能 Gateway 进程已死）
+  │
+  ├─ 2. 读当天 Gateway 日志，python3 过滤最近 120 秒的行
+  │
+  ├─ 3. 三条规则分别 grep 计数
+  │
+  ├─ 4. 任一规则命中阈值
+  │   ├─ 在冷却期内 → 只 log 不重启
+  │   └─ 不在冷却期 → 重启 Gateway + 记录原因
+  │
+  └─ 5. 都没命中 → 正常
 ```
 
-### 3.3 参数
+## 3. 防重启风暴
+
+- **冷却期**：重启后 5 分钟内再次检测到问题只 log 不重启
+- **状态文件**：`/tmp/gateway-watchdog-state`（JSON）
+  ```json
+  {"last_restart_time":"2026-06-02T21:00:00+08:00","last_restart_reason":"R1","cooldown_until":1717333800}
+  ```
+
+## 4. 重启原因记录
+
+每次重启自动追加到 `/tmp/gateway-watchdog-restarts.log`（永久文件，用于统计分析）：
+
+```json
+{"time":"2026-06-02T21:00:00+0800","reason":"R1","detail":"FailoverError x3","counts":{"r1":3,"r2":0,"r3":1}}
+```
+
+字段说明：
+- `time`：重启时间（ISO 格式）
+- `reason`：触发规则（R1/R2/R3/health_fail）
+- `detail`：匹配到的关键字摘要
+- `counts`：所有三条规则的实际命中次数（无论哪条触发都记录全量）
+
+## 5. 参数
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
 | CHECK_WINDOW | 120s | 检查最近多少秒的日志 |
-| THRESHOLD | 3 | 连续检测到多少次 429 才重启 |
+| R1_THRESHOLD | 2 | FailoverError 触发阈值 |
+| R2_THRESHOLD | 3 | stalled recovery=none 触发阈值 |
+| R3_THRESHOLD | 2 | rate_limit/429 触发阈值 |
+| COOLDOWN | 300s | 重启后冷却期 |
 | 检测频率 | 60s | crontab 每分钟执行 |
 
-### 3.4 状态文件
+## 6. 文件位置
 
-`/tmp/gateway-watchdog-429-count` — 记录连续 429 检测次数，重启后重置为 0。
+| 文件 | 路径 | 说明 |
+|------|------|------|
+| 脚本 | `scripts/gateway-watchdog.sh` | watchdog 主脚本 |
+| 本文档 | `docs/design/gateway-watchdog.md` | 设计文档 |
+| 运行日志 | `/tmp/gateway-watchdog.log` | crontab 重定向输出 |
+| 状态文件 | `/tmp/gateway-watchdog-state` | 冷却期控制 |
+| 重启记录 | `/tmp/gateway-watchdog-restarts.log` | 重启原因（永久追加） |
+| 锁文件 | `/tmp/gateway-watchdog.lock` | 防并发 |
 
-### 3.5 日志
-
-`/tmp/gateway-watchdog.log` — 每次执行的检测结果。
-
-## 4. 文件位置
-
-| 文件 | 路径 |
-|------|------|
-| 脚本 | `scripts/gateway-watchdog.sh` |
-| 本文档 | `docs/design/gateway-watchdog.md` |
-| 日志输出 | `/tmp/gateway-watchdog.log` |
-| 状态文件 | `/tmp/gateway-watchdog-429-count` |
-
-## 5. 部署
+## 7. 部署
 
 ```bash
 # crontab 每分钟执行
 (crontab -l 2>/dev/null | grep -v "gateway-watchdog"; \
- echo "* * * * * /path/to/sanguo_moziplus_v2/scripts/gateway-watchdog.sh >> /tmp/gateway-watchdog.log 2>&1") \
+ echo "* * * * * /Users/chufeng/.openclaw/sanguo_projects/sanguo_moziplus_v2/scripts/gateway-watchdog.sh >> /tmp/gateway-watchdog.log 2>&1") \
  | crontab -
 ```
 
-## 6. 运维
+## 8. 运维
 
 ```bash
-# 查看日志
-tail -20 /tmp/gateway-watchdog.log
+# 查看运行日志
+tail -f /tmp/gateway-watchdog.log
 
-# 查看当前 429 计数
-cat /tmp/gateway-watchdog-429-count
+# 查看状态（冷却期等）
+cat /tmp/gateway-watchdog-state
+
+# 查看重启历史
+cat /tmp/gateway-watchdog-restarts.log | python3 -m json.tool
+
+# 统计重启原因
+grep "reason" /tmp/gateway-watchdog-restarts.log | python3 -c "
+import json, sys
+from collections import Counter
+reasons = Counter()
+for line in sys.stdin:
+    reasons[json.loads(line)['reason']] += 1
+print('重启统计:')
+for k,v in reasons.most_common():
+    print(f'  {k}: {v}次')
+"
 
 # 手动测试
 bash scripts/gateway-watchdog.sh
@@ -147,8 +164,20 @@ bash scripts/gateway-watchdog.sh
 crontab -l | grep -v "gateway-watchdog" | crontab -
 ```
 
-## 7. 已知局限
+## 9. 与 v1.0 的差异
 
-1. **事后检测** — 检测的是已发生的 429，不是预防
-2. **重启治标** — 重启 Gateway 恢复 stalled session，但不解决 zhipu 限流根因
-3. **无通知** — 重启后没有主动通知用户（可后续加飞书/邮件通知）
+| 维度 | v1.0 | v2.0 |
+|------|------|------|
+| 数据源 | session jsonl 文件 | Gateway 进程日志 |
+| 检测规则 | 仅 429（1 条） | 3 条（FailoverError / stalled / rate_limit） |
+| 重启风暴 | 无防护 | 5 分钟冷却期 |
+| 原因记录 | 无 | JSON 文件永久追加 |
+| 统计能力 | 无 | 结构化数据可分析 |
+| 配套脚本 | 独立（gateway_monitor.py 不动） | 不冲突 |
+
+## 10. 已知局限
+
+1. **事后检测** — 检测的是已发生的错误，不是预防
+2. **只读当天日志** — 跨天 0 点时日志轮转，前一分钟的日志在新文件里但文件名不同（暂不处理，影响极小）
+3. **无通知** — 重启后没有主动推送通知（可后续接入飞书/邮件）
+4. **单机** — 只能在 Gateway 所在机器上运行