From 26e2e632d5ece00ea61bc7554d5f2b16f0434014 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Fri, 14 Aug 2026 16:58:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20Sense=20=E8=A7=86?= =?UTF-8?q?=E9=A2=91=E6=8E=A5=E5=85=A5=E5=AE=89=E5=85=A8=E8=BE=B9=E7=95=8C?= =?UTF-8?q?=20(#66)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/02-architecture-and-code-map.md | 8 ++++++-- docs/03-business-rules-and-glossary.md | 14 ++++++++++++-- docs/04-local-development-and-verification.md | 8 ++++++-- docs/06-troubleshooting.md | 18 ++++++++++++++++-- docs/delivery/README.md | 12 ++++++++++-- 5 files changed, 50 insertions(+), 10 deletions(-) diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 4f2fd24..bdeda25 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -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: 6880a2918c46be27738467361d8d3f923f33fc69 -synchronized_at: 2026-08-14T07:02:35Z +wiki_revision: 915b5ca9a9a097470cb67a80f73045d16d3d57be +synchronized_at: 2026-08-14T08:53:04Z # 架构与代码地图 @@ -92,6 +92,10 @@ Sense JWT realm 固定为 `Sense`；浏览器令牌 Cookie 为 `Sense-Admin-Toke 工单 #65 新增设备台账入口：后端按 `models → dto → service → api → router` 分层位于 `Sense/server/app/sense/device/`，管理路由在 `Sense/server/app/admin/router/sense_device.go`，前端页面位于 `Sense/ui/src/views/sense/device/index.vue`。设备凭据由 `Sense/server/app/sense/credential/` 独立存储和 AES-256-GCM 加密，HTTP 只返回是否已配置，不提供凭据读取接口。 设备写入采用版本号乐观并发控制；视频设备适配器状态为可接入，雷达、门磁、按钮、穿戴和其他类型明确显示“适配器未就绪”，不得伪装成已接入。`admin`、`implementation_operator`、`site_admin` 可维护设备，`viewer` 只读；停用替代物理删除。 + +工单 #66 在 Sense/server/app/sense/onvif/、rtsp/ 与 admission/ 建立视频接入边界：WS-Discovery 只能绑定 SENSE_ONVIF_DISCOVERY_IP 指定的本机网卡，所有 ONVIF、Media XAddr 与 RTSP Stream URI 都必须落在 SENSE_ONVIF_ALLOWED_CIDRS 明确授权的网段。HTTP 客户端禁止代理和重定向，并在每次连接时重新解析、校验和固定目标 IP，防止 DNS 重绑定；URL 用户信息及敏感查询参数被拒绝。 + +ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Stream URI 持久化到 PostgreSQL。接入失败会记录可行动状态但保留最后一次已验证 Profile；成功接入清除凭据更新触发的重试标记。前端继续复用 GoAdmin 动态菜单、权限链、BasicLayout 和 Element Plus 表单、Dialog、Table、Tag。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index d560731..12c1110 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -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: 013865e0b48d156bb984515d6fabd42139829459 -synchronized_at: 2026-08-14T07:02:39Z +wiki_revision: d1471acadb4759b80e9bc20e5cec18bd21ba65cd +synchronized_at: 2026-08-14T08:53:13Z # 业务规则与术语 @@ -105,3 +105,13 @@ synchronized_at: 2026-08-14T07:02:39Z - 凭据只写不可读：HTTP 和页面仅显示“已配置/未配置”，不得回填用户名、密码或密文；更新凭据后只记录状态并请求后续接入流程重试。 - `admin`、`implementation_operator`、`site_admin` 可维护设备与凭据，`viewer` 仅可查看设备台账。 + + +## Sense 视频接入规则 + +- “获准网卡”和“获准目标网段”都是部署人员显式配置的授权边界；私网地址不自动代表已授权。未配置发现网卡时不发送 WS-Discovery，手工地址也必须通过目标 CIDR 检查。 +- ONVIF 设备地址、Media XAddr 和 RTSP Stream URI 禁止 URL 用户信息、敏感认证查询参数、HTTP 重定向和超出授权网段的目标。摄像机返回不可用主机名时，只能归一化为已验证设备主机并重新执行授权检查。 +- ONVIF 支持 Basic、MD5 Digest 和 SHA-256 Digest 的 auth；不支持的算法或 qop 必须拒绝，不静默降级。 +- Profile 保存 token、名称、分辨率、编码、用途、无凭据 Stream URI 和逐 Profile 验证状态；主码流默认取分辨率最高项，子码流取最低项。 +- 认证失败、超时、时间异常、目标未授权和重定向拒绝必须给出不同状态。失败重探不得删除最后一次已验证 Profile；凭据更新后可重新探测。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index d4e92cf..5bbedd5 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -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: f68bbd8c7a99689e65453ae00c7bbd2c3ee00357 -synchronized_at: 2026-08-14T07:02:43Z +wiki_revision: c8afa08e1e189a9c2779da1cbd3ed75124fd7eae +synchronized_at: 2026-08-14T08:53:20Z # 本地开发与验证 @@ -163,6 +163,10 @@ $env:SENSE_CREDENTIAL_KEY = [Convert]::ToBase64String($keyBytes) ``` 缺少或格式错误的密钥时，普通设备台账仍可读写，但凭据更新返回服务不可用且不得产生部分写入。设备回归至少覆盖：中文名称与位置、未知 JSON 字段拒绝、版本冲突返回 409、非视频设备显示适配器未就绪、viewer 只读、凭据响应/操作日志不含明文，以及 PostgreSQL 迁移重复执行不增加菜单或权限记录。 + +视频接入还需在仓库外配置 SENSE_ONVIF_DISCOVERY_IP（获准的本机网卡 IP）和 SENSE_ONVIF_ALLOWED_CIDRS（逗号分隔的获准摄像头网段）。不要使用 0.0.0.0/0 代替授权清单。 + +协议回归位于 app/sense/onvif、app/sense/rtsp、app/sense/admission；隔离 PostgreSQL 重启恢复测试通过 SENSE_ADMISSION_TEST_DATABASE_URL 显式启用。验证至少覆盖 Digest/Basic、无配置发现提示、URL 凭据和敏感查询拒绝、目标网段、重定向、Media/Stream 主机归一化、主子码流、失败重探保留已验证 Profile，以及 viewer 只读权限。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index de2864e..6df6047 100644 --- a/docs/06-troubleshooting.md +++ b/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: 2be5d803b954df64e31085bcf097ee27f8611f9d -synchronized_at: 2026-08-14T01:17:28Z +wiki_revision: ae80dc2d34341ff3cddfff93f51373adb3bd0664 +synchronized_at: 2026-08-14T08:53:30Z # 故障排查 @@ -60,3 +60,17 @@ synchronized_at: 2026-08-14T01:17:28Z |---|---| | 在 `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 跟随到未知目标。 | + diff --git a/docs/delivery/README.md b/docs/delivery/README.md index df954e4..e415ea3 100644 --- a/docs/delivery/README.md +++ b/docs/delivery/README.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Delivery-Documentation-Guide wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.- -wiki_revision: 93cda004538c5114c5c4ca8a03b19e3e975b503d -synchronized_at: 2026-08-14T07:03:33Z +wiki_revision: 07c8711ff4d75da5e4acbd61d029d27f01009747 +synchronized_at: 2026-08-14T08:54:16Z # 交付文档指南 @@ -112,3 +112,11 @@ Sense 面向网管、实施人员和非技术现场人员，菜单按日常任 凭据窗口每次均为空，不会回显已保存用户名或密码；“已配置”标签只表示服务器保存了密文。部署人员必须在仓库外为服务进程配置 Base64 编码的随机 32 字节 `SENSE_CREDENTIAL_KEY`，丢失或更换该密钥会使旧凭据不可用，因此应纳入受控秘密备份。停用设备不会物理删除台账。 + + +### Sense 视频接入交付说明 + +部署人员必须先确认获准摄像头网段，再把本机对应网卡 IP 配置为 SENSE_ONVIF_DISCOVERY_IP，把获准网段配置为逗号分隔的 SENSE_ONVIF_ALLOWED_CIDRS。不得为了省事填写全网段。现场人员在“视频接入”选择已登记且已配置凭据的视频设备，可使用发现结果或手工填写不含账号密码的 ONVIF 地址。 + +验证结果区分可用、部分码流失败、认证失败、目标未获准、重定向拒绝、响应超时、设备时间异常和无法连接，并显示主/子码流及逐 Profile 状态。失败重试不会删除上次已验证 Profile；修改凭据后应重新验证。真实摄像机兼容性、网络 ACL 和设备校时仍需在客户授权环境完成。 +