dev_harness/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Troubleshooting wiki_revision: e1a806bb8c6b6c32a4e271c94a9bcaaed36003db synchronized_at: 2026-08-08T00:58:12Z

故障排查

本页用途

按“现象 → 原因 → 检查 → 处理”定位 DevHarness 常见问题。处理后如果形成稳定结论，应更新本页；临时过程记录在工单。

现象	常见原因	检查方法	处理
--strict 提示项目档案未填写	新项目仍有占位内容	搜索 <填写	先在 Wiki 填写真实内容，再导出镜像
同步提示镜像有未提交改动	有人直接修改 docs，或上次镜像尚未提交	git status --short -- docs	确认来源；保留人工内容并先更新 Wiki，不要强制覆盖
Wiki 页面不存在	页面未创建、标题或映射错误	查看 Wiki 页面列表和 wiki-docs.json	修正明确的页面或映射；不要自动删除本地文件
API 路径出现重复 /api/v1	GITEA_URL 已包含 API 后缀	查看非敏感 URL 配置	同步器会规范化；新工具也应接受两种写法
公共仓库读取返回 401/403/404	环境令牌失效或属于其他实例	不打印令牌；尝试浏览公开页面	只读请求可安全降级匿名；写请求必须使用正确 PAT
中文 Wiki 页面读取 404	sub_url 被重复百分号编码	查看页面列表返回的 sub_url	保留已有 %，不要再次编码
Wiki 页面标题多出 .-	Gitea 1.25 的页面规范路径或更新时未显式传标题	对照页面 title 和 sub_url	更新中文页面时显式保留原 title；不要猜测路径
--check 正文不一致	Wiki 已更新但镜像未导出，或本地被修改	对照 revision 和 Git 差异	确认 Wiki 后运行正式同步
单元测试能过但真实同步失败	测试使用模拟数据，网络或 Gitea 行为不同	查看工单“未验证部分”	增加最小真实验证并记录服务端版本
Git 工作区包含无关修改	同时存在其他任务或人工工作	git status --short	保留并隔离无关修改，不重置用户工作

排查顺序

1. 读取完整错误信息，不只看最后一行。
2. 检查当前工单、分支和工作区。
3. 检查项目档案中的真实命令和环境。
4. 用最小命令复现。
5. 对照最近提交和 Wiki revision。
6. 修复后增加回归测试或稳定排错条目。
7. 无法验证的部分写回工单。

必须停止的情况

出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。