docs: 记录 Sense 实时监看架构 (#68)

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: c615cd5235557a3888260beb5a682c6ed4e5b5dc
-synchronized_at: 2026-08-14T09:46:56Z
+wiki_revision: 331755cb39ac9d63c188395c5caafe0815d64975
+synchronized_at: 2026-08-14T10:46:04Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -85,6 +85,19 @@ synchronized_at: 2026-08-14T09:46:56Z
 | 显示外部启动（受保护） | 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 -->