yovision/docs/06-troubleshooting.md

<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Troubleshooting
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
wiki_revision: eec4beb8e5b9b8ff18401b272fd249aff7711509
synchronized_at: 2026-08-31T13:00:41Z
<!-- 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 重新实施。 |

<!-- sense-admission:start -->
## 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-media:start -->
## 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-media:end -->

<!-- sense-admission:end -->

<!-- sense-area:start -->
## Sense 区域与警戒线排错

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

<!-- sense-capabilities-jsonb:start -->
## 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-capabilities-jsonb:end -->

<!-- sense-media-path-constraint:start -->
## 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` 停止。

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


## DevHarness 同步排错

1. 先运行 `python dev_scripts/harness.py check --strict` 定位结构或项目规则问题。
2. 镜像不一致时运行 `python dev_scripts/harness.py sync --check`；不得直接修改 `docs/` 后反向覆盖 Wiki。
3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。
4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。
5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。

<!-- machine-identity-v1:start -->
## 机器身份 v1 排错

| 现象/错误码 | 常见原因 | 检查 | 安全处理 |
|---|---|---|---|
| `machine_token_missing` | 未使用 Authorization Bearer 或格式错误 | 检查 connector 配置，不粘贴令牌 | 修复调用方；不改用 Cookie/query token |
| `machine_token_invalid` | 签名、kid、请求方法/路径/正文摘要或封闭字段不匹配 | 核对版本、kid 和请求绑定 | 停止重试，修复配置/实现 |
| `machine_token_expired` | 时钟偏差或令牌超过 5 分钟 | 检查双方 UTC 时钟 | 校时并签发新令牌，不延长长期 token |
| `machine_audience_denied` / `machine_scope_denied` | 目标产品或最小权限不匹配 | 核对公钥注册表和调用方向 | 修正精确授权，不添加通配符 |
| `machine_identity_revoked` | principal/key 已禁用或吊销 | 核对当前 kid 与轮换状态 | 切换已批准新 key；不得恢复旧 key绕过吊销 |
| `machine_token_replayed` | 同一 jti 被再次使用 | 检查重试是否重新签名 | 新建 jti，保留业务幂等键 |

排错日志只记录稳定错误码、已认证 principal/kid 和 correlation ID；不得记录令牌、签名、密钥、完整 Authorization header 或秘密路径。无法安全恢复时关闭 connector，三端保持独立运行。
<!-- machine-identity-v1:end -->

<!-- integration-connectors-v1:start -->
## #152/#153 connector 排错

| 现象/错误 | 检查 | 安全处理 |
|---|---|---|
| connector 启用后提示迁移缺失 | 核对 Sense/Bell `2026083112000_*` 迁移记录和默认数据库 | 停止 connector，先备份并执行正式迁移；不依赖 AutoMigrate |
| 配置被 Brain 拒绝 | 核对 schema 主版本、JCS/SHA-256、config_id/revision、Profile/几何和 recalibration 状态 | 修复新 revision；保留 last-known-good，不回写旧 revision |
| Sense 显示 Brain 陈旧/离线或 revision mismatch | 核对 Brain sequence、observed_at、实际 applied_revision 和传输错误码 | 修复时钟/传输/配置；不手工改只读投影 |
| Sense Outbox 持续积压 | 核对 Bell ingress 开关、HTTPS、机器身份、available_at、lease、attempt 与脱敏错误 | 恢复 Bell 后等待幂等补投；不清空消息或改业务 ID |
| Bell 返回 duplicate | 同一 producer/source ID 与相同规范摘要已接收 | 视为成功；不得创建新 source_event_id |
| Bell 返回 idempotency conflict | 同一 producer/source ID 对应不同摘要 | 终止重试并调查 producer；保留原 Receipt/Event 与冲突审计 |
| evidence unavailable/timeout/expired | 核对 Sense evidence endpoint、`evidence:read` 权限、owner_id、HTTPS 和过期时间 | 保持降级状态；不把失败伪装 success，不改 Alert 生命周期 |
| 启动出现重复路由或错误数据库 | 检查 Sense 是否使用默认 DB、是否重复启动实例 | 每实例只注册一次；不让 connector 随机选择 secondary DB |
| Request-ID 或机器令牌拒绝 | 检查 16–128 字符 Request-ID、方法/路径/正文绑定、audience/scope/kid 和时钟 | 新签发 token/jti；保持原业务幂等键，不记录 Authorization |
| 对端离线导致本端无法启动 | connector 被错误配置成强依赖 | 关闭对应开关并恢复独立运行；保留持久事实后另行排查 |

日志只记录稳定错误码、request/correlation ID、已认证 principal/kid 和脱敏业务引用；不得记录私钥、令牌、完整 Authorization、摄像头凭据、内部证据路径或事件完整敏感载荷。
<!-- integration-connectors-v1:end -->

<!-- coordination-deployment-v1:start -->
## 根级协调编排排错

工单 #154 已于 2026-08-31 验收；本节适用于已验收的可选根级编排。

先使用与启动时相同的仓库外清单查询状态：

```powershell
pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product all
```

| 现象/状态 | 检查 | 安全处理 |
|---|---|---|
| 清单校验失败 | 检查包、env、私钥路径是否存在且位于仓库和包外；检查三端端口、目录、数据库、Cookie、JWT、账户和身份是否独立 | 修正仓库外清单或环境文件；不得放宽隔离断言或把秘密写进仓库 |
| `port ... is already in use` | 用状态命令确认是否已有受管实例，再检查对应监听端口 | 先按归属停止旧实例或为产品分配独立端口；不得终止未知进程 |
| `stopped` | 没有该产品状态文件 | 按需单独启动；不代表其他产品异常 |
| `unhealthy` | 进程仍归属本实例，但 HTTP/进程健康检查失败 | 查看该产品独立 `coordination.err.log`、`coordination.out.log` 和产品日志；修复该端，不自动重启其他端 |
| `stale` / `ownership-mismatch` | PID 已复用、启动器或命令令牌与状态不符 | 不会停止该进程；人工核对进程与状态文件，确认归属后再处理 |
| `stale` / `manifest-drift` | 运行中的实例来自不同清单摘要 | 使用原清单安全停止，或确认归属后停止再以新清单启动；不得用新清单覆盖运行事实 |
| 单端启动失败 | 查看该端协调日志、产品日志和退出码 | 编排只清理该端新进程；确认其他端状态，修复失败端后单独重试 |
| connector 使对端成为启动强依赖 | connector 开关或产品配置错误 | 关闭对应 event export、ingress、relay 或 evidence connector，恢复三端独立运行；保留 Outbox/Receipt/Event 等持久事实 |
| 停止命令拒绝执行 | 状态归属不匹配，或产品停止入口返回非零 | 不使用无条件 taskkill；先核对 PID、启动器、命令令牌和产品停止日志 |

日志和状态不得包含环境变量值、密码、JWT、token、私钥、完整 Authorization、摄像头凭据或客户数据。协调层故障时可停止使用根级入口并恢复三个产品各自的已验收启动脚本，不删除数据或共享事实。
<!-- coordination-deployment-v1:end -->

<!-- coordination-e2e-v1:start -->
## 三项目协调 E2E 排错

先从完整输出定位第一个失败阶段，不同时修改多个猜测原因。默认入口是：

```powershell
pwsh scripts/e2e/coordination/run-coordination-e2e.ps1
```

| 现象 | 检查 | 安全处理 |
|---|---|---|
| 缺少 `initdb.exe`、`pg_ctl.exe`、`createdb.exe` 或 `psql.exe` | 检查 `-PostgresBin` 是否指向同一 PostgreSQL 安装的 `bin` | 修正工具路径；不要改用生产数据库或默认 5432 |
| Python 缺少契约依赖 | 确认所选 Python 可创建 venv 且能安装仓库冻结依赖 | 修复 Python/依赖源后重试；不要把依赖临时装进产品环境充当固定基线 |
| Bell 正式迁移失败 | 查看当轮临时目录的 `bell-migrate.log`，核对首个 SQLSTATE | 修复迁移或工具链；不得跳过迁移、手工补表或连接业务库 |
| Sense/Bell 数据库隔离断言失败 | 检查生成的 owner/database 是否不同 | 停止测试；不得共享数据库、角色、JWT、Cookie 或账户空间 |
| Bell Rule/Alert 评估数偶发增加 | 检查是否把 ingress、rule、lifecycle 多个有状态 Go 包放在同一数据库并行运行 | 恢复 root harness 的串行阶段；不要降低断言或清除不可变事实 |
| `machine_token_*`、duplicate 或 conflict 与预期不符 | 核对 audience/scope/kid、请求绑定、jti 和 producer/source 业务键 | 保持稳定错误和原业务键；不得记录 Authorization、复用网页登录态或为重试改 source ID |
| Outbox 在 Bell 离线后未补投 | 核对 retry/lease/available_at、Bell 恢复和新 relay 进程 | 保留消息和历史，恢复 Bell 后重试；不得清空 Outbox/Receipt/Event |
| evidence timeout/unavailable 导致整条事件失败 | 检查 evidence resolver 与降级状态 | Event/Receipt/Alert 应继续保留；不得把失败伪装为 success |
| 端口仍占用或测试结束后有进程 | 确认进程是否由本轮测试启动，查看所属临时目录和状态 | 只停止能证明归属的进程；不得无条件 taskkill 或终止其他实例 |
| 秘密扫描失败 | 在本轮临时日志中搜索该随机测试值，禁止把值粘贴到工单 | 修复日志输出后重新运行；不得仅关闭扫描 |
| 需要保留失败现场 | 使用 `-KeepTemporary` 并记录明确绝对临时路径 | 目录只用于本机受控诊断，完成后按已核对路径清理；不得提交或共享 |
| 使用 `-SkipIndependentProductE2E` 后通过 | 只证明协调 harness 主体，不证明三端独立回归 | 修复依赖后重新运行默认完整入口，不能据此通过 MVP 验收 |

若失败发生在 Sense、Brain 或 Bell 的独立 E2E，转到对应产品章节按该端首个错误排查；不得在协调文档工单中顺手修改产品代码。真实 GPU、真机、通知供应商、生产迁移、16 路长稳或客户现场问题不属于该隔离 E2E 的结论。
<!-- coordination-e2e-v1:end -->