chorus/docs/06-troubleshooting.md

故障排查

排查顺序

遇到问题按下面的顺序走，不要跳步，也不要直接重置工作区或覆盖本地文档。

1. 确认环境与工作区

git status --short --branch
go version

工作区有不属于当前任务的修改时先处理干净，否则后面的判断都不可靠。

2. 判断问题落在哪一段

chorus 的请求分成同步提交和异步执行两段，绝大多数问题只在其中一段：

现象	大概率在哪段
点了生成没反应、报 4xx	同步段（portal/handler）
卡片出现了但一直转圈	异步段（queue / worker）
结果出来了但内容不对	提示词合成（generate/prompt.go）
结果失败并有错误码	provider 调用或选路

3. 查库，不要靠猜

SELECT id, kind, status, provider_model_id, attempt_count,
       error_code, error_message, lease_until, latency_ms, created_at, finished_at
FROM generations ORDER BY id DESC LIMIT 10;

观察到	含义与下一步
status=pending 且长时间不动	worker 没起来或没连上库；看 portal 启动日志有没有 “worker started”
status=running 且 lease_until 已过期	worker 崩了或卡在上游；查上游超时设置与进程日志
status=failed，error_code 是 429/5xx	上游限流或故障；看 attempts 是否按预期换了下一家
status=failed，error_code 是 400/401	参数或密钥问题；不应该发生故障转移，若 attempts 有多条说明 retryable 写反了
status=succeeded 但页面无图	查 generation_outputs 的 path 与 thumb_path，再查存储目录权限
rendered_prompt 与预期不符	角色规则模板或三层覆盖顺序的问题，不是模型的问题

4. 隔离上游

用 mock 上游重跑一次（internal/core/provider 的测试 mock 可构造 429、超时、400、内容拒绝）。mock 下正常、真实上游异常，问题在配置或网络；mock 下同样失败，问题在代码。

不要拿真实额度反复试错。

5. 检查出站是否被 SSRF 拦截

base_url 指向私网、回环地址或解析结果落在私网时会被 internal/core/security 拦截，表现是“连不上但网络看起来正常”。日志中有拦截记录。拦截生效是正确行为，要改的是配置，不是拦截规则。

6. 文档与 Harness 相关问题

症状	处理
harness.py check --strict 报缺少章节	按提示补回该标题，标题文字必须完全一致
harness.py check --strict 报“项目档案仍有未填写内容”	docs/00-project-profile.md 里还有 <填写 占位符
sync --check 报不一致	先确认是 Wiki 更新了还是本地被手工改了；本地被改过要恢复后重新同步
sync 中止并提示存在未提交修改	已映射镜像有未提交改动，先提交或还原
Wiki 页面读不到、没有 revision	停止初始化或同步，等 Gitea 恢复后从首个失败页面继续

7. 仍未定位

在工单中记录：最小复现步骤、generations 的相关行、attempts 内容、相关日志片段（去掉密钥）、已排除的可能性。然后交给 Agent 分析。

必须停止的情况

以下情况立即停止自行处理，交给 Agent 分析并等待人工确认：

• 需要修改 retryable、熔断参数、选路逻辑或 SSRF 规则；
• 需要修改数据库迁移，或需要手工改生产/共享库中的数据；
• 需要触碰密钥、加解密、身份认证、权限或 API Key；
• 需要写入点数余额或 point_ledger；
• 需要删除生成物、清理表数据或任何不可逆操作；
• 需要绕过失败重跑任务（可能造成重复计费或重复生成）；
• 日志或报错中出现疑似泄露的密钥、个人数据或生产数据——先停止传播，不要把原文贴进工单或 Wiki；
• 你已经在同一处试了两次仍不确定根因。