yovision/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting wiki_revision: 1a452e9aafdfe01580f37f9179584b89516cf992 synchronized_at: 2026-08-15T07:59:38Z

故障排查

常见问题

现象	常见原因	检查	处理
三个 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 的数据库、ONVIF/RTSP、MediaMTX、实时监看、会话和区域排错只适用于 explore 快照。新 main / dev 当前没有可运行 Sense；在新的 GoAdmin 派生骨架和业务迁移工单完成前，不使用旧命令或旧状态判断新实现。

旧 Sense Windows 包状态

旧 Windows 打包与启动脚本仅保存在 explore，不属于新开发基线。新的 GoAdmin 派生实现必须由独立工单重新建立打包、配置和排错说明。

重建阶段常见问题

现象	处理
在 dev 找不到 Sense/Bell 可运行代码	这是重建空基线的预期状态；旧实现位于 explore，新代码必须由 GoAdmin 源码派生工单建立。
新骨架只有相似页面、没有 GoAdmin 启动链或权限模块	不符合二次开发门禁；停止验收，对照 goadmin-baseline.json、上游源码和 go-admin-doc 重新实施。

Sense 视频接入排错

现象	原因与处理
未配置获准的发现网卡	在服务进程环境设置本机实际网卡 IP SENSE_ONVIF_DISCOVERY_IP；不要填写摄像机 IP。
配置的发现地址不是本机网卡	网卡地址已变化或填写错误；用 Get-NetIPAddress 核对后重启服务。
目标地址不在获准网段内	核对摄像机实际地址与 SENSE_ONVIF_ALLOWED_CIDRS；只追加已审批的最小 CIDR，不使用全网放行。
认证失败	在设备管理重新填写 ONVIF/RTSP 凭据，再返回视频接入重新验证；页面不会回显旧凭据。
设备时间异常	在摄像机管理页或受控 NTP 环境校时后重新探测；Sense 不自动修改设备时间。
部分码流失败	查看逐 Profile 状态、设备 RTSP 权限和端口；最后一次已验证 Profile 会保留。
重定向已拒绝	ONVIF 服务返回了 3xx；修正为摄像机最终服务地址，不允许 Sense 跟随到未知目标。

Sense 视频服务排错

现象	原因与处理
进程状态“未配置”	未设置 SENSE_MEDIAMTX_BINARY；如由外部服务管理，先确认 loopback Control API 已就绪，否则配置二进制和仓库外配置路径。
进程启动失败	核对二进制存在、配置目录可写、MediaMTX 配置可解析，以及 RTSP/API 端口未被其他进程占用。
等待拉流	路径已建立但 sourceOnDemand 尚无 reader；打开实时监看后再观察，不等同于接入失败。
配置失败或路径缺失	在“视频服务”点击对账；检查 Control API 仍为 loopback、Profile 仍已验证、RTSP 凭据可用。
显示外部启动（受保护）	Sense 检测到不是本实例启动的 MediaMTX；孤儿安全闸生效，Sense 关闭时不会停止它。
持续自动重试	查看失败码、失败次数和下次重试时间；修正二进制、端口、凭据或上游后等待退避到期，或由有权限用户立即对账。
Sense 重启后路径未恢复	确认数据库 route 的 desired 为 running、迁移已执行、Control API 可达；明确停止的路径不会自动恢复。

Sense 实时监看排错

现象	原因与处理
浏览器提示 127.0.0.1 拒绝连接	127.0.0.1 指向使用者电脑，不一定是 Sense 服务器；将 SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE 配成浏览器实际可达的 MediaMTX HTTP(S) origin，并检查 8889 或映射端口。
stream not found / 未找到视频流	路径未恢复或 Profile 已失效；先到“视频服务”对账，确认路径存在，再重新打开实时监看建立 reader。不要把内部路径手工拼进页面。
一直显示“等待视频”	播放器已创建但 sourceOnDemand 尚未 ready；保持 Dialog 打开并检查摄像头 RTSP、WebRTC 端口和 MediaMTX reader。20 秒后页面会转为超时并提供重连。
摄像头认证失败	到“设备管理”更新凭据，再到“视频接入”重新验证；页面不会显示或回填旧凭据。
视频服务不可用	到“视频服务”检查 MediaMTX 进程、Control API、WebRTC 端口和路径对账，不要只刷新浏览器。
播放会话已过期	页面关闭、网络中断或认证轮询停止超过 2 分钟；重新连接会生成新能力令牌，旧地址不应继续可用。
HTTPS 页面无法播放 HTTP 视频	浏览器阻止混合内容；为 MediaMTX WebRTC 配置 HTTPS 或受控同源代理，并把公开基础地址改成 HTTPS。
服务端 curl 正常、浏览器仍失败	服务端可达不代表客户端可达；从实际用户浏览器检查公开主机、端口、防火墙、证书和 WebRTC UDP/TCP 路径。

Sense 区域与警戒线排错

现象	原因与处理
显示“需要重新校准”	绑定 Profile 已删除、验证失效，或 Token、分辨率、编码发生变化；打开“编辑/校准”，选择当前可用码流，在实际画面确认坐标后保存新版本。不要手工清状态或复制旧坐标冒充校准。
保存提示配置已被其他用户更新	当前页面的 expectedVersion 已过期；刷新列表，查看最新版本后重新编辑。系统会保留已成功写入的版本，不覆盖对方结果。
画面可见但无法添加更多顶点	方向警戒线最多两个点，多边形最多 64 个点；检查配置类型，必要时撤销或清空后重画。
提示边线交叉或面积过小	顶点顺序形成自交、重叠或退化多边形；拖动顶点消除交叉，确保至少三个不同且围成有效面积的点。
实时画面不可用	先到“实时监看”确认该 Profile 可播放，再检查 MediaMTX/WebRTC 公开地址。区域 API 不返回或要求填写 RTSP URI。
Profile 已恢复但仍显示重校准	这是保守安全状态；恢复相同规格不会自动认可旧坐标。必须由有权限用户打开实际画面确认并保存新版本。
viewer 看得到页面但不能保存	符合只读权限；由 implementation_operator、site_admin 或 admin 完成配置。
键盘无法操作顶点	Tab 聚焦画布或编号顶点；Enter/Space 添加中心点，方向键移动，Delete/Backspace 删除。检查浏览器焦点轮廓是否可见。

Sense 旧设备能力字段迁移排错

启动迁移出现 字段 "capabilities" 的默认值不能转换成类型 jsonb (SQLSTATE 42804)，表示数据库仍保留旧版 sense_devices.capabilities text DEFAULT ''，而当前 GoAdmin 派生模型要求 JSONB。不要跳过迁移、删除设备记录或只手工删除默认值；旧单值数据仍可能在下一步转换失败。

工单 #92 的兼容迁移会在同一事务内锁定设备表并先验证全部旧值：空值转为 []，video、radar、contact、button、wearable、other 等旧单值转为 JSON 数组，合法 JSON 数组保持数组。未知值或非数组 JSON 会拒绝迁移并整体回滚，不输出具体业务值。

处理步骤：

1. 停止所有连接该 Sense 数据库的服务实例。
2. 使用 backup-sense.bat 创建 PostgreSQL custom-format 备份，并确认备份文件可读取。
3. 部署包含 #92 的新 sense.exe 后重新运行 migrate-sense.bat 或正常启动。
4. 若提示“unsupported legacy data”，不要直接改表；保留错误、恢复测试副本并由维护人员确认旧能力语义。
5. 迁移成功后确认设备仍存在、能力标签正确，再启动其他实例。

正式数据库未备份时不得执行该结构迁移。需要回退版本时停止服务并从迁移前备份恢复，不把 JSONB 反向猜测为旧文本。

Sense 旧媒体路由迁移排错

旧库迁移出现 约束 "uni_sense_media_routes_path" 不存在 (SQLSTATE 42704)，表示旧 sense_media_routes.path 由 PostgreSQL 自动命名的唯一约束保护，而新 GORM 模型准备改用唯一索引；GORM 按推导名称删除旧约束时找不到实际名称。修正该名称后若继续出现 source_ready ... contains null values (SQLSTATE 23502)，表示非空旧表还缺少当前模型要求的运行态列。

工单 #95 的兼容迁移只在 PostgreSQL 旧表存在时执行：取得 ACCESS EXCLUSIVE 表锁，确认只有一个单列 UNIQUE(path) 约束，将实际约束名规范为 GORM 可识别名称；同时为旧路由初始化保守运行态 source_ready=false、failure_count=0、last_error_code=''，再继续 AutoMigrate。迁移不会把旧路由伪装成已就绪，服务启动后仍由对账恢复真实状态。复合约束、多重 path 约束或其他无法确认的唯一性结构会拒绝迁移并整体回滚。

处理步骤：

1. 停止连接该数据库的全部 Sense 实例，并确认 Sense 与 MediaMTX 相关端口已释放。
2. 使用 backup-sense.bat 生成 PostgreSQL custom-format 备份；非标准 PostgreSQL 安装目录需通过 SENSE_POSTGRES_BIN 指向包含 pg_dump.exe、pg_restore.exe 的目录。
3. 使用 pg_restore --list <备份文件> 确认备份可读取，再部署包含 #95 的 Windows 包。
4. 先运行 migrate-sense.bat；成功后确认旧路由数量不变、运行态列无空值、path 仍有唯一索引。
5. 再启动 Sense，检查首页、/healthz、MediaMTX Control API 和视频服务对账；验证完成后使用 stop-sense.bat 停止。

如果迁移报告不支持的唯一性结构，不要手工删除约束或路由；在备份副本中核对实际约束和业务数据。正式迁移失败时保留错误并从迁移前备份恢复，不通过关闭唯一性绕过迁移。