docs: 记录 Sense 设备台账与凭据边界 (#65)
This commit is contained in:
QiuSW
@@ -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: eb1174040657f2064e26b6448ca92e7a93666423
|
||||
synchronized_at: 2026-08-14T04:09:07Z
|
||||
wiki_revision: 6880a2918c46be27738467361d8d3f923f33fc69
|
||||
synchronized_at: 2026-08-14T07:02:35Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
@@ -88,6 +88,10 @@ Sense 已由工单 #61 从冻结 go-admin/go-admin-ui 源码建立：后端入
|
||||
工单 #64 在该基线上重建 Sense 独立身份能力：`Sense/server/app/admin/apis/identity_bootstrap.go` 提供受外部高熵令牌保护的一次性首位管理员初始化，数据库迁移固定建立 `admin`、`implementation_operator`、`site_admin`、`viewer` 四个角色及最小 Casbin 权限；前端继续复用 go-admin-ui 动态菜单、权限按钮、请求封装与 Layout。仓库仍不提供默认账号、默认密码或可用 JWT 密钥。
|
||||
|
||||
Sense JWT realm 固定为 `Sense`；浏览器令牌 Cookie 为 `Sense-Admin-Token`，后端仅接受标准 Authorization Bearer 或独立的 `sense_session` Cookie，不接受查询参数令牌，也不得与 Bell 共享 JWT 密钥、Cookie 或账户库。登录成功/失败、登出、密码变更和鉴权拒绝写入身份审计；审计内容必须剔除密码、令牌、Cookie、验证码和其他秘密。配置、接口管理等非产品必要路由不注册，即使管理员直接调用也返回 404。
|
||||
|
||||
工单 #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` 只读；停用替代物理删除。
|
||||
<!-- sense-runtime:end -->
|
||||
|
||||
<!-- sense-mvp:start -->
|
||||
|
||||
@@ -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: 53a9c59534560841cd65fec74492ac3a55ffebe1
|
||||
synchronized_at: 2026-08-14T04:09:11Z
|
||||
wiki_revision: 013865e0b48d156bb984515d6fabd42139829459
|
||||
synchronized_at: 2026-08-14T07:02:39Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -94,3 +94,14 @@ synchronized_at: 2026-08-14T04:09:11Z
|
||||
## 旧实现迁移边界
|
||||
|
||||
旧 Sense 中已验证的中文设备字段、请求白名单、凭据隔离和媒体链路行为可作为迁移验收用例；不得把旧自研基础框架直接复制到新 `dev`。
|
||||
|
||||
<!-- sense-device-ledger:start -->
|
||||
## Sense 设备台账与凭据规则
|
||||
|
||||
- Device 是 Sense 内的设备根实体，类型包括视频、雷达、门磁、按钮、穿戴和其他；16 路仍只是默认交付配额，分页和台账容量不得硬编码为 16。
|
||||
- 当前仅视频设备具备可用接入适配器；其余类型必须显示“适配器未就绪”，不允许通过虚假成功状态掩盖能力缺口。
|
||||
- 设备台账支持列表、新建、编辑和停用；停用保留审计与后续关联，不提供物理删除。编辑、停用和凭据更新均使用版本号检测并发冲突。
|
||||
- 摄像头 ONVIF 与 RTSP 凭据按设备和用途分离，以 AES-256-GCM 密文保存；加密密钥只从外部环境 `SENSE_CREDENTIAL_KEY` 注入，不写入数据库、仓库、工单、Wiki 或日志。
|
||||
- 凭据只写不可读：HTTP 和页面仅显示“已配置/未配置”，不得回填用户名、密码或密文；更新凭据后只记录状态并请求后续接入流程重试。
|
||||
- `admin`、`implementation_operator`、`site_admin` 可维护设备与凭据，`viewer` 仅可查看设备台账。
|
||||
<!-- sense-device-ledger:end -->
|
||||
|
||||
@@ -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: 9007f0ff45178b7535c2a38b6e38d44628c3210d
|
||||
synchronized_at: 2026-08-14T04:09:15Z
|
||||
wiki_revision: f68bbd8c7a99689e65453ae00c7bbd2c3ee00357
|
||||
synchronized_at: 2026-08-14T07:02:43Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 本地开发与验证
|
||||
@@ -151,6 +151,18 @@ Remove-Variable bootstrapToken, bootstrapBody
|
||||
身份回归至少覆盖：admin 可管理账户及查看审计；implementation_operator 只能查看实施所需日志和字典支撑数据；site_admin 可维护账户并读取角色、部门、岗位、字典，但不能修改角色或菜单；viewer 不能访问管理接口。还要验证配置/接口管理路由返回 404、短密码被拒绝、6 位全小写密码可用，以及登录/登出/改密/拒绝审计中不含密码、令牌、Cookie 或验证码。身份审计直接写入 PostgreSQL，不依赖通用操作日志数据库开关。
|
||||
|
||||
详细来源与安全约束见 `Sense/LICENSES/SOURCES.md` 和 `Sense/README.md`。
|
||||
|
||||
设备台账启用凭据写入前，还必须在服务进程环境提供独立随机密钥；示例文件 `Sense/server/config/credential.env.example` 只保留空值：
|
||||
|
||||
```powershell
|
||||
# 生成一次随机 32 字节密钥并以 Base64 形式注入当前进程；不要打印或写入仓库
|
||||
$keyBytes = New-Object byte[] 32
|
||||
[System.Security.Cryptography.RandomNumberGenerator]::Fill($keyBytes)
|
||||
$env:SENSE_CREDENTIAL_KEY = [Convert]::ToBase64String($keyBytes)
|
||||
[Array]::Clear($keyBytes, 0, $keyBytes.Length)
|
||||
```
|
||||
|
||||
缺少或格式错误的密钥时，普通设备台账仍可读写，但凭据更新返回服务不可用且不得产生部分写入。设备回归至少覆盖：中文名称与位置、未知 JSON 字段拒绝、版本冲突返回 409、非视频设备显示适配器未就绪、viewer 只读、凭据响应/操作日志不含明文，以及 PostgreSQL 迁移重复执行不增加菜单或权限记录。
|
||||
<!-- sense-runtime:end -->
|
||||
|
||||
|
||||
|
||||
+10
-2
@@ -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: c754ebd705c55329a46da12e1860ffd7d137f99a
|
||||
synchronized_at: 2026-08-14T04:09:55Z
|
||||
wiki_revision: 93cda004538c5114c5c4ca8a03b19e3e975b503d
|
||||
synchronized_at: 2026-08-14T07:03:33Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 交付文档指南
|
||||
@@ -104,3 +104,11 @@ Sense 面向网管、实施人员和非技术现场人员，菜单按日常任
|
||||
- 交付时记录 ZIP SHA-256，并至少验证 `/healthz` 与首页；真实 PostgreSQL、MediaMTX、摄像机和目标浏览器仍需在获准环境验收。
|
||||
- 包内 `README-WINDOWS.md` 是现场操作入口；真实 `config\sense.env` 只留在具体部署目录，不得提交 Git 或重新打入交付 ZIP，交付 ZIP 只保留 `sense.env.example`。
|
||||
<!-- sense-windows-package:end -->
|
||||
|
||||
<!-- sense-device-ledger:start -->
|
||||
### Sense 设备台账交付说明
|
||||
|
||||
设备管理已开放列表、新建、编辑、停用和摄像头凭据更新。系统管理员、实施/运维和站点管理员可以维护；只读用户只能查看。现场人员应使用中文设备名称和安装位置，类型选择“视频”时才可配置 ONVIF/RTSP 凭据；其他类型会明确提示适配器尚未就绪。
|
||||
|
||||
凭据窗口每次均为空，不会回显已保存用户名或密码；“已配置”标签只表示服务器保存了密文。部署人员必须在仓库外为服务进程配置 Base64 编码的随机 32 字节 `SENSE_CREDENTIAL_KEY`，丢失或更换该密钥会使旧凭据不可用，因此应纳入受控秘密备份。停用设备不会物理删除台账。
|
||||
<!-- sense-device-ledger:end -->
|
||||
|
||||
Reference in New Issue
Block a user