63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
|
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
|
wiki_page: Troubleshooting
|
|
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
|
|
wiki_revision: 2be5d803b954df64e31085bcf097ee27f8611f9d
|
|
synchronized_at: 2026-08-14T01:17:28Z
|
|
<!-- gitea-wiki-mirror:end -->
|
|
|
|
# 故障排查
|
|
|
|
## 常见问题
|
|
|
|
| 现象 | 常见原因 | 检查 | 处理 |
|
|
|---|---|---|---|
|
|
| 三个 agent 修改同一文件 | 工单写路径重叠或共享契约未设协调任务 | 查看工单“子项目影响”和 `git status` | 停止写入，由协调 agent 重排范围 |
|
|
| 一端测试通过、集成失败 | 契约副本漂移或兼容语义不一致 | 对照 `contracts/` 与三端契约测试 | 以契约事实源修复，不复制第二份 schema |
|
|
| Sense 依赖 Bell 才能启动 | 把可选 connector 写成强依赖 | 在 Bell 停止时启动 Sense | 改为 Outbox/可选配置，暴露降级状态 |
|
|
| Bell 接受 Sense 用户 token | 认证边界被混用 | 检查 issuer、audience、Cookie 和用户表 | 立即停止，恢复独立认证与机器身份 |
|
|
| `--strict` 缺页面或章节 | Wiki 未创建/未同步或模板结构损坏 | 查看 `wiki-docs.json` 与 Wiki | 先修 Wiki，读取确认后重新同步 |
|
|
| Wiki 同步提示本地脏镜像 | 直接编辑了 `docs/` | `git status --short -- docs` | 保留内容，先更新 Wiki；不要强制覆盖 |
|
|
| Gitea 401/403 | token 属于其他实例、过期或权限不足 | 不打印 token；验证目标 URL | 写操作停止，修复安全配置 |
|
|
| env 无法解析 | 使用 `KEY:VALUE` 而非 `KEY=VALUE` | 只检查键名和格式 | 改为标准 env 格式，不输出值 |
|
|
|
|
## 排查顺序
|
|
|
|
1. 停止继续修改并读取完整错误。
|
|
2. 核对当前工单、主 agent、子项目和允许写路径。
|
|
3. 确认问题属于单项目、共享契约还是环境。
|
|
4. 用最小命令复现，先处理第一个可行动错误。
|
|
5. 契约问题先检查唯一事实来源，再检查生产者和消费者。
|
|
6. 修复后运行受影响测试和 Wiki 一致性检查。
|
|
7. 无法验证的部分写回工单。
|
|
|
|
## 必须停止的情况
|
|
|
|
- 凭据、真实视频、个人信息或生产数据可能泄露；
|
|
- 需要共享 Sense/Bell 用户、JWT、Cookie、数据库或摄像头密码；
|
|
- 多个 agent 写路径重叠且无法证明单写入者；
|
|
- 契约破坏性变化没有新版本、迁移和回退方案；
|
|
- 涉及删除、不可逆迁移、发布或生产变更但没有明确授权；
|
|
- 工作区出现来源不明且与当前任务重叠的修改。
|
|
|
|
<!-- sense-mvp:start -->
|
|
## 旧 Sense MVP 排错资料
|
|
|
|
旧 Sense 的数据库、ONVIF/RTSP、MediaMTX、实时监看、会话和区域排错只适用于 `explore` 快照。新 `main` / `dev` 当前没有可运行 Sense；在新的 GoAdmin 派生骨架和业务迁移工单完成前，不使用旧命令或旧状态判断新实现。
|
|
<!-- sense-mvp:end -->
|
|
|
|
<!-- sense-windows-package:start -->
|
|
## 旧 Sense Windows 包状态
|
|
|
|
旧 Windows 打包与启动脚本仅保存在 `explore`，不属于新开发基线。新的 GoAdmin 派生实现必须由独立工单重新建立打包、配置和排错说明。
|
|
<!-- sense-windows-package:end -->
|
|
|
|
|
|
|
|
## 重建阶段常见问题
|
|
|
|
| 现象 | 处理 |
|
|
|---|---|
|
|
| 在 `dev` 找不到 Sense/Bell 可运行代码 | 这是重建空基线的预期状态；旧实现位于 `explore`，新代码必须由 GoAdmin 源码派生工单建立。 |
|
|
| 新骨架只有相似页面、没有 GoAdmin 启动链或权限模块 | 不符合二次开发门禁；停止验收，对照 `goadmin-baseline.json`、上游源码和 go-admin-doc 重新实施。 |
|