06 - 真排障手册

直接 Ctrl+F 搜你看到的真字面 (error code / log 关键词). 5 类紧急情况 + 全 degraded_reason 真表 + 真后端 trace 看法.

紧急程度 4 档

5 类紧急情况 (P0)

紧急 1: backend 完全不响应

真症状:

• 浏览器 frontend 转圈不出报告
• curl http://127.0.0.1:5000/api/v1/healthz 真返 000 (拒接) 或 hang

30 秒排查:

# 1. 看进程
pgrep -af "backend/app.py" | grep -v "bash -c"

# 0 真返 → backend 死了, 跳到"重启" 段
# 1+ 真返 → backend 在跑但 hang, 看 log
tail -50 workspace/system_monitor/logs/backend-verify.log | grep -E "Traceback|ERROR|Killed|OOM"

重启:

cd /home/kk/code/project/cs-26spring-final-project/workspace/system_monitor
OLD_PID=$(pgrep -f "backend/app.py" | grep -v "bash -c" | head -1)
[ -n "$OLD_PID" ] && kill -9 "$OLD_PID"
sleep 3

# 清 .pyc 缓存 (Phase 69.A 教训 lesson 11)
find backend/ -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null

# 重启
set -a; source .env.local; set +a
nohup ./backend/.venv/bin/python backend/app.py > logs/backend-verify.log 2>&1 &
NEW_PID=$!
sleep 6

# 验
curl -s -o /dev/null -w "HTTP %{http_code}\n" --max-time 5 http://127.0.0.1:5000/api/v1/healthz
# 期望 200 / 401 / 404

真挂仍不起:

紧急 2: ES 连不上 (degraded 大面积)

真症状:

• 所有 endpoint 真返 degraded_reason="es_query_failed" 或 "data_source_unavailable"
• 报告里全是 fallback 数据

30 秒排查:

# 1. ES 真活吗?
curl -s --max-time 5 http://10.10.1.147:9200/_cluster/health
# 期望: {"status":"green"} 或 yellow

# 2. VPN 真通吗? (跨网段时)
ping -c 3 10.10.1.147
# 0 包 = 网络断

真因 + 修法:

紧急 3: LLM 全挂 (本地 + DeepSeek 都不可达)

真症状:

• 所有 endpoint 真返 ai_reasoning.available=false, fallback_reason="model_unavailable"
• 仍出报告但全是 deterministic 文字 (没有 LLM 自然语言解释)

30 秒排查:

# 1. 本地 LLM 真活吗?
curl -s --max-time 5 "$OPENCLAW_LOCAL_URL" -X POST \
    -H "Content-Type: application/json" \
    -d '{"model":"...","messages":[{"role":"user","content":"hi"}]}'

# 2. DeepSeek 真活吗?
curl -s --max-time 10 https://api.deepseek.com/chat/completions \
    -H "Authorization: Bearer $OPENCLAW_DEEPSEEK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'

真因 + 修法:

紧急 4: 真生产数据真泄漏 (P0 安全)

真症状:

• 任何 frontend / fixture / git history 出现真域名 (e.g. deepinstinctweb)
• 真 MAC (不是 02:00:00:* 占位)
• 真 API key

真立即响应 (30 分钟内):

# 1. 截图 / 保留证据
# 2. 立即不再 push / commit
# 3. 看真泄漏范围
grep -rE "deepinstinctweb|sk-[a-zA-Z0-9]{20,}" \
    workspace/system_monitor/test_backup/ \
    docs/agent-handoff/ \
    workspace/system_monitor/logs/

# 4. 看 git history
git log --all -p 2>&1 | grep -c "<真泄漏字面>"

# 5. 若 > 0, filter-repo 洗 (Phase 68.E + R31 同款 SOP):
cat > /tmp/replacements.txt <<'EOF'
<真泄漏字面>==>anon-redacted-XXX.example.invalid
EOF
git filter-repo --replace-text /tmp/replacements.txt --force

# 6. 验
git log --all -p 2>&1 | grep -c "<真泄漏字面>"
# 期望: 0

# 7. force push 覆盖远程
git push --force-with-lease origin <branch>

# 8. 起 phase 修脱敏源头 (类比 Phase 68.E sanitize_fixture.py _HOSTNAME_RE)

详见 feedback_bitter_lessons_r10_r37.md（站内未公开） lesson 10.

紧急 5: 真发现 AI 给的建议含”执行性动作” (违 preview_only)

真症状:

• 运维截图发现 AI 建议里写”删除 X 配置” / “重启 nginx” / “drop ACL rule”
• 这违反 preview_only=true 设计契约

真立即响应:

# 1. 截图保留
# 2. 看哪个 endpoint 真返的
grep -rE "rm -rf|systemctl restart|drop|delete from" workspace/system_monitor/backend/assistant/ | head -10

# 3. 找到真生成这文本的位置
# 通常是 recommended_actions builder 或 LLM prompt 模板
# Phase 64.F 起严守"建议动作必须可执行但不真执行"

# 4. 立即 patch (改 LLM prompt 或 invariant 拦字面)
# 这是 P0 必修, 不可留账
# 起 phase70.X coding agent prompt (类比 Phase 68.E)

degraded_reason 全表 (运维高频遇到)

Backend log 真常见关键词

tail -f workspace/system_monitor/logs/backend-verify.log 看:

真后端 tool_trace 看法

任何 endpoint 真返 JSON 内含 tool_trace[]. 真值字段:

{
  "tool": "query_dns_failure_summary",
  "args": {"start": "...", "end": "...", "resolver_ip": "..."},
  "args_summary": {...},        // sanitize 后的 args (脱敏)
  "status": "ok|failed|skipped",
  "failure_reason": "",          // failed 时真因
  "result_summary": {...},       // tool 真返
  "execution_enabled": false,    // 安全旗
  "preview_only": true,
  "raw_log_scan": false
}

排障时看:

frontend 排障 (vite HMR 真不工作时)

# 1. 看 frontend dev server 在不在跑
pgrep -af "vite" | grep -v "bash -c"

# 2. 浏览器侧 F12 → Network tab → 看是否 fetch 到 :5000 真返
# 看 axios 真请求 url + response status / body

# 3. 浏览器侧 Ctrl+Shift+R 强刷 (清 vite HMR 缓存)

# 4. frontend dev 真挂重起
cd workspace/system_monitor/frontend
pkill -f "vite"
sleep 2
nohup npm run dev > ../logs/frontend-dev.log 2>&1 &
sleep 5
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:3002

真复现某个 bug 的 SOP

# 1. 收集真复现条件
# - 真用户操作 (哪个 endpoint, 什么 payload)
# - 真返 JSON (frontend network tab 拷)
# - 真 backend log tail 200 行

# 2. 真复现真 capture
cd workspace/system_monitor
./scripts/run_round_evaluation.sh r-debug-<descriptor>
# 6 步 pipeline 真跑, fixture 入 staging

# 3. 真后端 fixture 真 grep 找真凶字面
grep -rnE "<真凶关键字>" test_backup/fixtures_real_backend/r-debug-<X>_*.json | head

# 4. 真在源码定位
grep -rnE "<同款关键字>" backend/assistant/ | head
# 看哪个 .py 真生成这个字面

# 5. 起 source-fix phase prompt (类比 Phase 68.A-F)
# 走 plugin v0.1.2 phase-prompt-guard 5 检查

真返时间真异常 (慢)

升级到下一阶段时 (生产部署)

涉及 systemd / nginx / gunicorn / PostgreSQL 等. 详见 04-deployment.md §生产部署.

排障时找 systemd / nginx / PostgreSQL 各自 SRE 文档, 本 doc 不展开.

下一步: 07-extension-guide.md (加新功能怎么做)