41 lines
2.8 KiB
Markdown
41 lines
2.8 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
|
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
|
|
<!-- gitea-wiki-mirror:end -->
|
|
|
|
# 故障排查
|
|
|
|
## 本页用途
|
|
|
|
按“现象 → 原因 → 检查 → 处理”定位 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. 无法验证的部分写回工单。
|
|
|
|
## 必须停止的情况
|
|
|
|
出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。
|