79 lines
6.9 KiB
Markdown
79 lines
6.9 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: fb34dfc3c1a8963f4edbd578733d1c1f5238c021
|
|
synchronized_at: 2026-08-13T13:32:00Z
|
|
<!-- 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_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` | 在设备管理中分别检查 ONVIF 与 RTSP 凭据，只有设备确实共用账号时才勾选“RTSP 与 ONVIF 使用相同账号”；不要把凭据写进地址。Sense 支持 ONVIF Basic 与 Digest，并会安全归一化摄像机广播的跨主机 Media/RTSP 地址。 |
|
|
| `clock_skew` | 校准摄像机时间后重新探测。 |
|
|
| 接入成功但提示“媒体服务未就绪” / `process_failed` | 接入资料和 Profile 已保存，实时监看路径也已建立；检查仓库外 `SENSE_MEDIAMTX_BINARY`、基础配置和进程退出原因，修复后到视频服务重新对账。达到三次重启上限后需人工处理。 |
|
|
| `apply_failed` / `unconverged` | 检查 localhost Control API 是否启用并为 v3；确认媒体路径和外部进程状态。 |
|
|
| 实时监看没有设备 | 先在视频接入完成一次检查；系统会自动建立媒体路径。若已接入仍为空，检查接入结果的媒体状态和视频服务对账。 |
|
|
| 实时监看提示“127.0.0.1 拒绝了我们的连接请求” | 先确认播放器接口响应头；该接口必须是 `X-Frame-Options: SAMEORIGIN` 且 CSP 包含 `frame-ancestors 'self'`，普通页面仍应为 `DENY`。播放器接口还必须允许不带 `X-Product`、但带有效 Sense Cookie 和同源 iframe Fetch Metadata 的浏览器导航；普通 API 仍应拒绝缺少产品头的请求。旧运行包会在响应头或认证中间件处阻止 iframe，需重新打包并重启 Sense。 |
|
|
| 实时监看持续“等待拉流” | `waiting` 会话应立即加载播放器以触发按需拉流。若连接后仍等待，检查 MediaMTX 路径 readers 和源状态；`401 Unauthorized` 表示摄像机拒绝当前 RTSP 凭据，应在设备管理修正凭据后重新执行视频接入，不能把凭据写入日志或地址。 |
|
|
| 画面等待、断开或会话过期 | 查看实时监看中的业务设备名和码流状态；会话轮询会只读刷新 MediaMTX 实际状态，无需手工对账。播放会话最长两分钟。 |
|
|
| 区域提示需要重新校准 | Profile 分辨率已变化，按新画面重新绘制并发布新版本，不能静默复用旧坐标。 |
|
|
|
|
自动测试不访问真实摄像头或未授权网络。PostgreSQL、MediaMTX、目标浏览器与实验室摄像机的联合验证必须在获准部署环境完成。
|
|
<!-- sense-mvp:end -->
|
|
|
|
<!-- sense-windows-package:start -->
|
|
## 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 验证替代。
|
|
<!-- sense-windows-package:end -->
|
|
|