yovision/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting wiki_revision: 832eace3bb0083168cc9ff11f689180e2d13bdea synchronized_at: 2026-08-13T03:39:34Z

故障排查

常见问题

现象	常见原因	检查	处理
三个 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 排错

现象/状态	检查与处理
启动提示缺少 SENSE_DATABASE_URL	正式模式必须提供独立 PostgreSQL URL；只有测试/smoke 可显式使用 memory。
登录统一提示用户名或密码错误	为避免枚举账户，失败响应不区分用户不存在、密码错误或账户停用；由管理员查看审计。
管理员登录后侧栏没有模块	先确认 /api/v1/identity/me 返回角色与权限；若权限正常，检查前端是否从具有 children 的应用布局路由派生菜单，不得依赖重复 / 路由记录顺序。
adapter_not_ready	当前设备类型尚无适配器，不代表网络故障；首期完整支持 video。
discovery_unavailable	未设置获准的 SENSE_ONVIF_DISCOVERY_IP，或该 IP 不属于本机网卡。可改用手工 ONVIF 地址。
authentication_failed	在设备管理中重新写入凭据后再次执行接入检查；不要把凭据写进地址。Sense 支持 ONVIF Basic 与 Digest；若 Profile 能读取但视频验证失败，确认 ONVIF 与 RTSP 是否使用同一组账号。当前每台设备只保存一组凭据，不同账号需后续凭据模型支持。
clock_skew	校准摄像机时间后重新探测。
process_failed	检查仓库外 SENSE_MEDIAMTX_BINARY、基础配置和进程退出原因；达到三次重启上限后需人工处理。
apply_failed / unconverged	检查 localhost Control API 是否启用并为 v3；确认媒体路径和外部进程状态。
画面等待、断开或会话过期	先在视频服务执行对账，再重新连接；播放会话最长两分钟。
区域提示需要重新校准	Profile 分辨率已变化，按新画面重新绘制并发布新版本，不能静默复用旧坐标。

自动测试不访问真实摄像头或未授权网络。PostgreSQL、MediaMTX、目标浏览器与实验室摄像机的联合验证必须在获准部署环境完成。

Sense Windows 打包与启动排错

现象	检查与处理
打包提示 Go/Node/pnpm 版本不符	对照根 goadmin-baseline.json 安装精确版本，并把 Go 1.26.5 放到 PATH 首位；不要修改脚本绕过版本检查。
生产启动提示缺少环境变量	确认运行目录中存在 config\sense.env（不是只保留 sense.env.example），并填写 SENSE_DATABASE_URL、SENSE_IDENTITY_SIGNING_KEY、SENSE_BOOTSTRAP_TOKEN、SENSE_CREDENTIAL_KEY；也可在进程环境中设置，非空进程环境变量优先。运行 start-sense.bat check 定位缺失的变量名，脚本不会打印变量值。
本机健康检查被代理返回空响应	localhost 可能被 HTTP_PROXY 接管；测试工具应对 127.0.0.1 使用 no-proxy，再检查 SENSE_HTTP_ADDRESS 端口占用。
页面可打开但视频不可用	Windows 运行包不包含 MediaMTX；按包内说明配置独立 MediaMTX 二进制、配置和 Control API。

demo 只用于临时查看。生产数据持久性、真实设备和媒体链路不能用 demo 验证替代。