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. 无法验证的部分写回工单。 ## 必须停止的情况 出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。