Files

T

QiuSW a8431216e3 docs: 记录 Sense 30天登录有效期 (#104 )

2026-08-17 10:55:21 +08:00

13 KiB

Raw Blame History

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: 8df12aa3e136b1faee9c2dffb58ca39b045bc49f synchronized_at: 2026-08-17T02:54:44Z

架构与代码地图

项目定位

YoVision 采用单仓三项目、两个销售产品的结构。单仓用于保持共享契约和端到端验证一致，不代表共享认证、数据库或发布生命周期。

摄像头 / RTSP / ONVIF
        │
        v
Sense（设备、媒体、区域、运维）
        │ 版本化媒体/配置契约
        v
Brain（推理、跟踪、区域判定、事件 mapper）
        │ 标准事件契约
        v
Bell（事件入站、规则、Alert、ack/close、升级、通知）

Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense 与 Brain 不得成为 Bell 的启动依赖。Sense 未配置 Bell 时仍可完成设备接入、实时监看、区域配置、运维和本地事件查看。

代码地图

能力	路径	首个阅读入口	验证位置	风险
Sense 产品	`Sense/`	`Sense/AGENTS.md`、`Sense/README.md`、`Sense/server/main.go`、`Sense/ui/src/main.js`	`Sense/server/` Go 测试；`Sense/ui/` lint/单测/构建	高：GoAdmin 派生、设备、媒体、凭据
Brain 推理	`Brain/`	`Brain/AGENTS.md`；后续包入口	`Brain/` 内测试与契约测试	高：模型、GPU、隐私、事件语义
Bell 产品	`Bell/`	`Bell/AGENTS.md`；待 GoAdmin 派生工单建立 README/入口	待新骨架建立	高：GoAdmin 派生、认证、事件与告警状态机
共享契约	`contracts/`	`contracts/AGENTS.md`	三端消费者/生产者测试	高：兼容性与跨项目影响
Harness	`dev_scripts/`	`check_harness.py`	`tests/`	中
工单模板	`.gitea/issue_template/`	`task.md`	Harness 严格检查	中
Wiki 镜像	`docs/`	`docs/README.md`	`sync_wiki_docs.py --check`	低；禁止直接编辑

旧 Sense、Bell 入口仅存在于 explore 快照，不是 main / dev 当前代码地图。三个项目的新入口必须随新骨架工单建立；不得把旧自研基础框架复制回 dev。

两条主要执行路径

独立产品路径

Sense：独立登录 → 添加摄像头 → ONVIF/RTSP 验证 → 实时画面 → 绘制区域

Bell：独立登录 → 接收合成/第三方事件 → 规则匹配 → Alert → ack → close

可选集成路径

Sense/Brain 生成事件
→ Sense 持久 Outbox 或 Brain 可靠投递
→ Bell 版本化事件 API
→ (producer_id, source_event_id) 幂等入站
→ Rule → Alert → Delivery/Escalation → ack/close

集成断开不得阻断任一产品核心能力；恢复后按 Outbox 和幂等收据继续。

数据与安全边界

Sense 与 Bell 拥有独立账户、会话、RBAC、审计、数据库角色和备份恢复。
Brain 业务无状态，不持有用户、Alert 或通知真相。
产品间不做跨库 SQL，不共享 JWT/Cookie，不发送摄像头凭据或内部文件路径。
contracts/ 是跨项目字段与语义唯一事实来源；发布契约不可原地破坏。
MediaMTX 是数据面独立进程；GoAdmin/GORM 只承担管理面和普通 CRUD。

不可破坏的边界

16 是默认配额，不是数组、数据库、分页或循环硬上限。
Event 与 Alert 分离；Event 不可变，状态变化与处置结果只追加。
模型输出观测，规则作业务判定；模型升级不能暗改事件语义。
业务预警与运维告警分开。
Area/设备/规则在各独立产品内有自己的业务投影，不以共享数据库同步。
单项目工单不得顺带修改其他项目；共享契约变更必须由协调工单统筹。

Sense 新代码入口

Sense 已由工单 #61 从冻结 go-admin/go-admin-ui 源码建立：后端入口为 Sense/server/main.go，前端入口为 Sense/ui/src/main.js，来源和完整 commit 记录在 Sense/LICENSES/SOURCES.md。后端保留 Cobra、Gin、GORM、Casbin、JWT 和迁移体系，前端保留 Router、Store、API、Layout、动态菜单与权限指令。上游作业、代码生成、监控等源码暂留用于升级追溯，但路由及用户入口不启用。

Sense 业务菜单必须遵循冻结 GoAdmin 的路由树：顶层目录使用 MenuType=M、Component=Layout，设备管理、视频接入、视频服务、实时监看、区域与警戒线使用相对路径作为 MenuType=C 子页面，操作权限继续作为页面下的 MenuType=F 节点。这样动态路由只替换 Layout 的右侧内容区，左侧导航、顶部栏和标签页始终保留；旧数据库由 Sense/server/cmd/migrate/migration/version/2026081623100_sense_layout.go 新增迁移修正父子关系和完整 paths，页面 URL 与权限标识不变。

工单 #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 或账户库。Sense 默认登录有效期为固定 30 天：后端 JWT 使用 2,592,000 秒，前端 Token Cookie 使用 30 天持久化期限；不做滑动续期、Refresh Token 或服务端单 Token 撤销，退出只删除本机 Cookie。部署新版本后已有 Token 不会自动延长，用户必须重新登录取得新有效期。登录成功/失败、登出、密码变更和鉴权拒绝写入身份审计；审计内容必须剔除密码、令牌、Cookie、验证码和其他秘密。配置管理 CRUD、configKey、set-config、接口管理等非产品必要路由不注册，即使管理员直接调用也返回 404。登录外壳必需的匿名只读 GET /api/v1/app-config 是唯一例外：它复用 GoAdmin SysConfig.Get2SysApp，只投影标记为前端可见的配置，不提供写入或管理能力。

工单 #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。工单 #67 在 Sense/server/app/sense/media/ 与 reconcile/ 建立 MediaMTX 管理面：cmd/api/server.go 随 Sense 生命周期启动后台对账并只停止本实例拥有的子进程；检测到外部实例时设置孤儿安全闸，不发送停止信号。MediaMTX Control API 只允许 loopback HTTP，禁用代理与重定向。

媒体路由只保存设备/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 旧 MVP 对照

旧设备、ONVIF/RTSP、MediaMTX、实时监看和区域配置实现保存在 explore。迁移时只提取已确认业务需求和必要业务适配器；通用认证、权限、菜单、请求封装和管理端外壳必须优先使用 GoAdmin/go-admin-ui。

Bell 旧 MVP 对照

旧 Event → Rule → Alert → ack/close 实现在 explore。迁移时保留业务语义、不可变与幂等约束，但新的通用认证、RBAC、菜单、审计和管理端外壳必须基于冻结 GoAdmin 源码。

Sense 区域与警戒线代码入口

工单 #69 在 Sense/server/app/sense/area/ 建立区域配置业务层，GoAdmin 路由位于 Sense/server/app/admin/router/sense_area.go，前端页面位于 Sense/ui/src/views/sense/area/index.vue。页面继续复用 BasicLayout、Axios、Element Plus 表单/表格/分页/Dialog/Tag/Alert 和权限指令；Sense/ui/src/components/sense/geometry-editor/ 是唯一新增的业务专用绘制组件。

数据采用两层结构：sense_area_definitions 保存当前版本指针和当前校准状态，sense_area_versions 保存每次创建、编辑、启停或重校准形成的不可变快照。更新请求携带 expectedVersion，服务在 PostgreSQL 事务中锁定当前定义；并发保存只有一个成功，其余返回冲突。历史版本不覆盖、不删除。

几何坐标使用画面内 0–1 归一化值，同时每个版本固化 Device、Profile Token、分辨率和编码。视频接入成功替换 Profile 后，admission 服务比较 Token、分辨率和编码并主动标记当前定义 needs_recalibration；读取时也会对缺失或失效 Profile 进行保守校验。系统不自动重投影旧坐标，只有用户重新确认画面并保存新版本后才清除重校准状态。

认证 API 为 /api/v1/area/configurations 及其版本子资源，接入 GoAdmin JWT、Casbin、动态菜单和操作权限。API 只返回设备/Profile 展示字段、规格、归一化坐标和版本信息，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。

Sense Windows 交付运行链

工单 #70 在 GoAdmin 派生入口上建立 Windows amd64 交付链。构建入口为 Sense/scripts/build/build-windows.ps1；运行包入口为 start-sense.bat，它先调用现有 sense.exe migrate -c data\runtime\settings.yml，迁移成功后再调用 sense.exe server -c ...。前端生产构建复制到包内 web/，后端只在显式配置 SENSE_WEB_ROOT 时提供同源静态资源和 SPA fallback，API 与健康检查不会被 fallback 覆盖。

运行脚本将 config\sense.env 当作数据解析，只接受白名单 SENSE_* 字段，不执行文件内容；同名非空进程环境变量优先。生成的 data\runtime\settings.yml 含运行秘密，只能留在部署目录。production 固定使用 PostgreSQL，要求至少 32 字符 JWT secret，且 MediaMTX 只能为 managed 或 external；managed 在 HTTP 启动前拉起包内二进制，external 在 HTTP 启动前确认回环 Control API 可达。Demo 使用独立配置和名称含 demo/test 的隔离数据库，默认禁用 MediaMTX，绝不回退 production 数据库。

交付包同时提供检查、迁移、管理员初始化、停止、备份和恢复入口。停止脚本只操作当前包且监听配置端口的 Sense 进程树；备份密码只进入子进程环境；恢复要求数据库名和二次短语确认。包不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。

13 KiB Raw Blame History Unescape Escape