ila/yovision
1
0
Fork 0
Code Issues 14 Pull Requests 14 Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
QiuSW
2026-08-14 18:48:11 +08:00
parent c63c623df5
commit a279a1ec0d
4 changed files with 63 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-architecture-and-code-map.md
+6 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
wiki_revision: c5482806a40428a436c202760eefdb6403406584
synchronized_at: 2026-08-14T09:46:37Z
wiki_revision: 0a15795aa69c5a0279a42ff1b48b44ddf68a9fad
synchronized_at: 2026-08-14T10:45:46Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -100,6 +100,10 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea
媒体路由只保存设备/Profile 引用、无秘密路径名、期望态、实际态、reader、退避和下次重试；摄像头凭据从内部端口按需解密，仅在 loopback Control API 请求内临时组装，不写入路由表、基础配置、日志或 Sense 响应。MediaMTX 故障和退避不改变 #66 的设备/Profile 验证状态。
工单 #68 在 `Sense/server/app/sense/liveview/` 建立单路监看投影和短期播放会话：认证 API 只返回设备/Profile 展示字段、播放状态和同源短期播放器地址，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放能力令牌使用 192 位随机值、绑定登录用户、同一用户只保留一个活动会话，登录页面持续轮询时按 2 分钟无活动窗口续期；关闭页面后停止续期。
`Sense/server/app/admin/router/sense_liveview.go` 将列表、创建会话和状态查询接入 GoAdmin JWT/Casbin，短期播放器包装页只凭不可猜测能力令牌访问，并设置 no-store、no-referrer、SAMEORIGIN 与 CSP。前端入口为 `Sense/ui/src/views/sense/liveview/index.vue`，复用 BasicLayout、Element Plus 表格/分页/Dialog/Tag 和权限指令；仅 `Sense/ui/src/components/sense/video-player/` 是业务专用播放器组件，任一时刻只建立一路 reader。
<!-- sense-runtime:end -->
<!-- sense-mvp:start -->
docs/03-business-rules-and-glossary.md
+10 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Business-Rules-and-Glossary
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
wiki_revision: ea2c540a9ac3f8ccf40123f8389eb392fb5e172b
synchronized_at: 2026-08-14T09:46:41Z
wiki_revision: e80685e19115e26384d58ddee8a15e5d80b03bb4
synchronized_at: 2026-08-14T10:45:50Z
<!-- gitea-wiki-mirror:end -->
# 业务规则与术语
@@ -85,6 +85,14 @@ synchronized_at: 2026-08-14T09:46:41Z
- 路径状态区分 pending、waiting、ready、process_unavailable、apply_failed、status_unavailable、path_missing、stopped，并保存失败次数和有上限的下次重试时间。
- 冷启动恢复 desired=running 路径；用户明确停止的路径保持 stopped，不因启动扫描自动重新启用。稳定路径只刷新状态，不重复下发配置或无意义增加版本。
- MediaMTX 失败不得删除或降级设备台账与最后一次已验证 Profile。
### Sense 实时监看规则
- 设备/Profile 列表必须分页和搜索；16/128 路不能导致页面同时创建全部播放器。用户选择一路并打开 Dialog 后才建立 reader，关闭或切换时销毁当前播放器。
- 页面和 JSON API 不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放器只使用同源短期能力地址；能力令牌必须高熵、绑定用户、每用户单会话，并在停止认证轮询后最多 2 分钟失效。
- 播放状态必须区分 loading、waiting、ready、authentication_failed、stream_not_found、service_unavailable、timeout、expired、offline 和 stopped，并同时显示文字与可行动处理建议，不能只用颜色表达。
- waiting 表示媒体路径存在且播放器正在建立 reader，不等于摄像头接入失败；20 秒仍未就绪才显示连接超时并允许显式重连。
- 默认从浏览器访问 Sense 的主机名推导 MediaMTX WebRTC 端口 8889；经过反向代理、HTTPS 或端口映射时，部署方必须显式配置安全的 `SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE`，不得回退到只对服务器自身有效的地址。
<!-- sense-media:end -->
<!-- sense-mvp:start -->
docs/04-local-development-and-verification.md
+32 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.-
wiki_revision: e084a4ae3f5038c4ec7dae6028a2e3d7527680a8
synchronized_at: 2026-08-14T09:46:47Z
wiki_revision: 95be7e2aa152205f524a185897dff5eb2c7e7e04
synchronized_at: 2026-08-14T10:45:55Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -190,6 +190,36 @@ go test ./cmd/migrate/migration/version -run TestMediaMigrationOnPostgres -v
测试必须使用隔离端口和数据库；结束后停止测试进程。不得输出连接串或摄像头凭据。
### Sense 实时监看
浏览器直接访问 Sense 所在主机且 MediaMTX 使用默认 WebRTC 端口 8889 时无需额外变量。反向代理、HTTPS 或端口映射部署必须在 Sense 进程环境提供浏览器可达的基础地址；值只能是无用户信息、查询和片段的 HTTP(S) origin：
```powershell
$env:SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE = 'http://<浏览器可达主机>:8889'
```
不要填写 RTSP 地址、Control API 地址、摄像头凭据或服务器内部文件路径。HTTPS 页面不得嵌入 HTTP 视频地址；应为 MediaMTX WebRTC 配置 HTTPS 或受控同源代理后填写对应 HTTPS origin。
定向与回归验证：
```powershell
cd Sense/server
go test -race ./app/sense/liveview
go test ./...
go vet ./...
go build ./...
$env:SENSE_LIVEVIEW_MIGRATION_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./cmd/migrate/migration/version -run TestLiveviewMigrationOnPostgres -count=1 -v
cd ../ui
corepack pnpm@9.15.1 lint
corepack pnpm@9.15.1 test:unit
corepack pnpm@9.15.1 build:prod
```
真实 smoke 使用隔离端口、MediaMTX 和合成 RTSP：浏览器打开 WebRTC 播放地址后必须取得非零视频尺寸和可播放 readyState，并确认任一时刻只存在一个播放器。结束后停止测试 MediaMTX/FFmpeg/浏览器并删除临时目录。客户真实摄像机与现场网络仍需获得授权后验证，记录状态而不记录地址、URI 或凭据。
<!-- sense-runtime:end -->
docs/06-troubleshooting.md
+15 -2
View File
@@ -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 -->