feat(sense): add reconciliation safety controls [T-012]
This commit is contained in:
QiuSW
@@ -40,13 +40,13 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前为 **M0 指定型号实机准入已完成，M1 Sense 五路混合源集成待执行**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。
|
||||
当前为 **M0 指定型号实机准入与 M1 Sense 五路混合源集成均已完成，M2 正在补齐生产接入边界**。后续本地开发统一使用已准入的一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。
|
||||
|
||||
优先路径：
|
||||
|
||||
1. M0：已用一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容，真实断网恢复证据按负责人豁免留痕。
|
||||
2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，以 1 路准入实机 + 至少 4 路独立合成源完成五路自动建 path、探活和断线重建。
|
||||
3. M2：对账、多租户、隧道和至少一个站点的 16 路全流程。
|
||||
3. M2：Control API、多租户投影、调和 fencing、孤儿安全闸已完成；下一步是隧道和至少一个站点的 16 路全流程。
|
||||
4. M3：Brain + Bell 起步，默认 16 路端到端事件、预警、ack 与误报反馈。
|
||||
5. M4–M5：64/128 路分片、管理端和第二/第三场景包。
|
||||
|
||||
|
||||
@@ -50,7 +50,9 @@ MediaMTX 官方 `v1.19.3` OpenAPI 固定保存于 `Sense/api/vendor/mediamtx-v1.
|
||||
|
||||
M2 仍保留 SQLite 作为单机开发与 T-006 回归入口，但生产真相源切换目标是 PostgreSQL。运行时必须显式设置 `SENSE_DB_DRIVER=postgres` 和私有 `SENSE_DB_DSN` 才使用 PostgreSQL；仓库不提供带密码 DSN。初始 schema 由 `deploy/postgres/` 的顺序 migration 创建，不在 Sense 进程启动时使用高权限自动迁移。
|
||||
|
||||
T-011 复用同一套冻结的 Go、PostgreSQL、pgx 与 `oapi-codegen`，未增加第三方依赖。Sense Control API v1 从仓库 OpenAPI 生成 `net/http` server glue；首版认证是可替换 port 下的外部静态 SHA-256 注册表，公共路由默认关闭且只在 PostgreSQL v4 schema 上启用。静态适配器是私有部署启动方案，不替代后续 Bell/JWT/OIDC 身份服务。
|
||||
T-011 复用同一套冻结的 Go、PostgreSQL、pgx 与 `oapi-codegen`，未增加第三方依赖。Sense Control API v1 从仓库 OpenAPI 生成 `net/http` server glue；首版认证是可替换 port 下的外部静态 SHA-256 注册表，公共路由默认关闭且只在 PostgreSQL 生产路径启用。T-011 首次落成 v4 schema，T-012 后进程统一要求 v5。静态适配器是私有部署启动方案，不替代后续 Bell/JWT/OIDC 身份服务。
|
||||
|
||||
T-012 同样未增加第三方依赖：PostgreSQL v5 使用数据库时钟租约和 fencing token 协调多实例调和/孤儿扫描；MediaMTX Path 枚举继续使用同版生成客户端。`/metrics` 由 Go 标准库输出 Prometheus 文本格式，只包含固定结果枚举、构建/实例信息和汇总 gauge/counter，不使用 tenant、Site、device 或 Path 标签。孤儿处置是 PostgreSQL 专用本地命令，默认周期任务只报告、不自动删除。
|
||||
|
||||
## 2. 外部项目边界
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
主流程：
|
||||
|
||||
1. Bell 持有站点、Area、配额与 `capture_policy`；首期在同一 PostgreSQL 实例内发布 `bell.site_quota_v1` 和 `bell.area_policy_v1` 两个版本化只读视图。T-009/T-010 已实现 Bell 源表/视图、最小权限和 Sense PostgreSQL repository；Sense 按 Area→Site 的固定 advisory-lock 顺序执行策略与配额准入并记录所用版本。未来分库必须发布新版本契约，不能静默改变 v1 语义。
|
||||
2. Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态。
|
||||
2. Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态；PostgreSQL 多实例以数据库时钟短租约和 fencing token 领取 due row，过期 worker 不得提交结果。
|
||||
3. Brain 消费视频与触发信号，产生符合 v0.1 的事件。
|
||||
4. Bell 做 schema 与代码级断言，生成平台 ULID，保存不可变事件。
|
||||
5. 规则命中后创建独立 Alert，先落库再投递，等待 ack 并按策略升级。
|
||||
@@ -82,8 +82,8 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
## 7. 一致性与失败处理
|
||||
|
||||
- PostgreSQL `sense` schema 是生产期望态真相源；SQLite 只保留为 M1 本地开发/回归路径。MediaMTX、推理 worker 和对象存储是可对账的实际态。
|
||||
- 对账器水平触发、幂等、指数退避、限制并发；部分失败不做跨系统回滚，只持续收敛。
|
||||
- 孤儿删除必须有 10% 安全闸和人工可观察指标。
|
||||
- 对账器水平触发、幂等、指数退避、限制并发；PostgreSQL 使用 `FOR UPDATE SKIP LOCKED`、每项续租和 fencing token，SQLite 只保留单进程开发语义。部分失败不做跨系统回滚，只持续收敛。
|
||||
- MediaMTX Path 扫描把“Sense 历史拥有但当前失配”和“从未归属 Sense”分开；未知归属永不自动删除。历史拥有项也只允许在 15 分钟二次快照、1～128 项和 `候选 × 100 <= 当前 Path 总数 × 10` 全部通过时由本地运维命令逐项处置，不提供绕过。
|
||||
- `bell.site_quota_v1` 行缺失、数值越界、版本回退或读取失败只阻止视频设备新增/启用，不中断已有流；降低配额导致超限时不自动停用，后续准入返回稳定错误并产生运维信号。多 Sense 实例使用 PostgreSQL transaction-scoped advisory lock 串行化同 tenant/site 的计数与写入，不能用进程内锁替代。
|
||||
- `bell.area_policy_v1` 缺失、非法、版本回退或读取失败时，PostgreSQL repository 拒绝相关新增/启用；`non_imaging_only` 允许非成像设备但拒绝具有 `video_capture` 的设备。已有设备保持原状态，策略冲突由 Bell 管理端显式迁移或取消。同库实时视图不以源记录年龄误判 freshness。
|
||||
- 设备创建和期望态受理在本地事务内同时写脱敏 `sense.device_operation_outbox`；Outbox 失败回滚业务写入，相同期望态不增加 generation 但仍审计。异步 relay 尚未实现。
|
||||
@@ -107,14 +107,14 @@ Sense ── 视频流/触发信号 ──> Brain
|
||||
## 9. 目录目标
|
||||
|
||||
```text
|
||||
Sense/cmd + Sense/internal/{device,onvif,mtx,reconcile,probe,trigger,tunnel,authcb,store}
|
||||
Sense/cmd + Sense/internal/{device,onvif,mtx,reconcile,orphan,metrics,probe,trigger,tunnel,auth,store}
|
||||
Brain/{pipeline,models,judge,emit,trigger,contracts}
|
||||
Bell/cmd + Bell/internal/{ingest,event,rule,alert,deliver,feedback,tenant,audit,store}
|
||||
Bell/{web,packs,contracts}
|
||||
deploy/postgres/{001_roles.sql,...,007_privileges_area_audit.sql,tests}
|
||||
deploy/postgres/{001_roles.sql,...,011_privileges_reconcile_safety.sql,tests}
|
||||
```
|
||||
|
||||
Sense 脚手架和 PostgreSQL `001`～`007` 已实现；Brain/Bell 应用目录仍是占位，真实服务必须由对应任务创建。
|
||||
Sense 脚手架和 PostgreSQL `001`～`011` 已实现；Brain/Bell 应用目录仍是占位，真实服务必须由对应任务创建。
|
||||
|
||||
## 10. 开发顺序
|
||||
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@
|
||||
- T-009：使用 PostgreSQL 17.10 建立 `sense`/`bell` schema、Bell 配额源表/只读视图、最小权限和 Sense PostgreSQL repository；SQLite 保留为 M1 本地路径。
|
||||
- T-010：建立 Bell Area/`capture_policy` 只读投影、Sense 成像准入与设备操作审计 Outbox 原子写入；relay 传输协议留给后续任务。
|
||||
- T-011：按 T-008 契约实现认证 tenant 上下文、7 个设备/operation handler、PostgreSQL 幂等收据、ETag/HMAC cursor、最多 128 项批量操作和停用精确 path 收敛；公共控制 API 默认关闭且只在 PostgreSQL 路径启用。
|
||||
- 对账器幂等/退避/并发/10% 安全闸。
|
||||
- T-012：以 PostgreSQL 数据库时钟租约和 fencing token 防止多实例重复调和；增加可证明的 Path 历史归属、默认只读孤儿报告、15 分钟二次确认、10% 不可绕过安全闸和低基数 `/metrics`。
|
||||
- WireGuard 边缘隧道与断网恢复。
|
||||
- 16 路批量开通、停用和容量基准。
|
||||
|
||||
|
||||
+5
-3
@@ -69,10 +69,10 @@ Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代
|
||||
| Port | 操作 | 数据所有者 / 失败语义 |
|
||||
| --- | --- | --- |
|
||||
| ONVIF adapter | `Probe(target)`、`SetSystemDateAndTime(target, time)` | 设备是外部来源；`target` 只含 endpoint ref 与不透明 credential ref。错误稳定映射为认证失败、超时、不可用、响应无效，不记录凭据或完整流地址 |
|
||||
| MediaMTX paths | `CreatePath`、`GetPath`、`EnsurePath`、`DeletePath`、`PathReady` | SQLite 设备台账持有期望态，MediaMTX 只持有运行配置；`EnsurePath` 相同 source 不写、不同 source patch、缺失时 add；当前调和器绝不枚举或删除孤儿 |
|
||||
| MediaMTX paths | `CreatePath`、`GetPath`、`EnsurePath`、`DeletePath`、`PathReady`、`ListPathNames` | 设备台账持有期望态，MediaMTX 只持有运行配置；分页枚举只返回名称、不返回 source。普通调和只操作精确台账 Path；独立孤儿流程只报告未知归属，受控处置只接受有历史归属的 stale Path |
|
||||
| Device repository | 设备、期望态、实际态、调和进度 | SQLite 是 M1 默认开发路径；PostgreSQL 是 M2 生产路径并只读 Site/Area 两个 Bell 视图。调和退避持久化；配额/Area 失败时拒绝相关新增或启用，不关闭已有流；高风险写入与脱敏 Outbox 同事务 |
|
||||
|
||||
MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch|delete/{name}` 与 `/v3/paths/get/{name}`。生成源、版本和 SHA-256 见 `docs/03-tech-stack.md`；业务包不得直接 import 生成包。
|
||||
MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch|delete/{name}`、`/v3/config/paths/list` 与 `/v3/paths/get/{name}`。列表有最大页数和重复页保护，source URI 在薄封装内丢弃。生成源、版本和 SHA-256 见 `docs/03-tech-stack.md`；业务包不得直接 import 生成包。
|
||||
|
||||
### 5.2 设备台账语义
|
||||
|
||||
@@ -83,7 +83,9 @@ MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch
|
||||
|
||||
### 5.3 Sense 进程 HTTP 面
|
||||
|
||||
`GET /healthz` 表示进程存活，`GET /readyz` 表示所选数据库已打开且 schema/权限前置检查完成；两者不要求认证，也不等价于摄像头、MediaMTX path 或里程碑健康。T-011 在 `SENSE_CONTROL_API_ENABLED=true`、PostgreSQL v4 schema 和外部安全文件全部有效时注册冻结的 `/api/v1` 路由；默认 SQLite 运行仍只暴露探针。业务路由不提供无 Site 边界的 `/api/v1/devices` 临时接口。
|
||||
`GET /healthz` 表示进程存活，`GET /readyz` 表示所选数据库已打开且 schema/权限前置检查完成；两者不要求认证，也不等价于摄像头、MediaMTX path 或里程碑健康。`GET /metrics` 默认输出无租户/设备/Path 标签的 Prometheus 汇总，可通过 `SENSE_METRICS_ENABLED=false` 关闭。T-011 在 `SENSE_CONTROL_API_ENABLED=true`、PostgreSQL v5 schema 和外部安全文件全部有效时注册冻结的 `/api/v1` 路由；默认 SQLite 不注册业务路由。业务路由不提供无 Site 边界的 `/api/v1/devices` 临时接口。
|
||||
|
||||
孤儿报告/处置不是公共 HTTP API。它由 PostgreSQL 专用 `cmd/sense-orphan` 在受控运维主机执行，使用 15 分钟 scan ID、actor、精确确认文本和运行前二次快照；不改变 Sense Control API v1 的 7 个 endpoint。
|
||||
|
||||
## 6. 变更流程
|
||||
|
||||
|
||||
+10
-9
@@ -4,8 +4,8 @@
|
||||
|
||||
## 当前阶段
|
||||
|
||||
- 阶段：M0 指定摄像头型号准入已完成；M1 的“一实机 + 四合成源”实验室软件闭环已通过；M2 已完成控制面契约、Site/Area 准入与本地审计事务基础，但五条独立真实上游和生产 SLA 尚未验收。
|
||||
- 生产代码：Sense 已包含可构建进程、SQLite/PostgreSQL repository、Site/Area 准入、设备操作 Outbox、标准 ONVIF SOAP/WS-Security adapter、凭据引用、MediaMTX 生成客户端、对账、探活和 MediaMTX 重启重建；公共设备管理 API、认证、Outbox relay 和完整生产部署仍未实现。
|
||||
- 阶段：M0 指定摄像头型号准入已完成；M1 的“一实机 + 四合成源”实验室软件闭环已通过；M2 已完成 Control API、Site/Area 准入、本地审计事务、多实例调和 fencing 和孤儿受控处置基础，但 WireGuard、16 路容量出口、五条独立真实上游和生产 SLA 尚未验收。
|
||||
- 生产代码：Sense 已包含可构建进程、SQLite/PostgreSQL repository、Site/Area 准入、设备操作 Outbox、标准 ONVIF SOAP/WS-Security adapter、凭据引用、MediaMTX 生成客户端、Control API v1、对账/探活、数据库租约、孤儿只读扫描/受控命令和低基数指标；Bell 管理服务/JWT、Outbox relay、WireGuard 和完整生产部署仍未实现。
|
||||
- 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。
|
||||
|
||||
## 仓库现实
|
||||
@@ -14,13 +14,14 @@
|
||||
- Sense 设备模型使用 `modality + capabilities`，SQLite 执行 v1 migration；视频配额默认 16、允许 1～128，17/128/129、新增/启用和“降低配额不关闭已有流”均有测试。
|
||||
- T-009 冻结 PostgreSQL `17.10` 和 `pgx/v5 v5.10.0`，实现 `bell`/`sense` schema、NOLOGIN 权限角色、Bell Site 版本 trigger、`bell.site_quota_v1` 和 Sense PostgreSQL repository；同站点并发准入用事务级 advisory lock，配额缺失/越界/版本回退时失败关闭且不改变已有流。
|
||||
- T-010 增量实现 `bell.areas`、`bell.area_policy_v1`、Area 版本观察和 `sense.device_operation_outbox`；`non_imaging_only` 拒绝成像设备创建/启用，失败不改变已有设备。设备创建/期望态受理与脱敏 Outbox 同事务，相同期望态不增加 generation 但仍审计。
|
||||
- Windows 隔离测试使用 `D:\pgsql17\bin` 启动随机回环端口临时集群，`001`～`007` migration 可重放、权限断言和 18 个真实 PostgreSQL 测试通过后自动清理；现有 `D:\pgsql17\data` 和 5432 服务未被读取、停止或修改。
|
||||
- MediaMTX 固定为独立二进制 `v1.19.3`，官方 OpenAPI 已按 SHA-256 vendoring，并由固定 `oapi-codegen v2.8.0` 生成客户端；手写薄封装有 create/read/delete、幂等 ensure 与探活假 HTTP 测试。
|
||||
- T-003 对账进度与指数退避持久化，覆盖取消和 SQLite 重启恢复；T-006 增加真实 ONVIF adapter、RTSP router、实验室播种/状态工具、故障代理和五路自动验收。当前仍不枚举/删除孤儿。
|
||||
- Windows 隔离测试使用 `D:\pgsql17\bin` 启动随机回环端口临时集群，`001`～`011` migration 可重放、权限断言和 29 个真实 PostgreSQL 测试通过后自动清理；现有 `D:\pgsql17\data` 和 5432 服务未被读取、停止或修改。
|
||||
- MediaMTX 固定为独立二进制 `v1.19.3`，官方 OpenAPI 已按 SHA-256 vendoring，并由固定 `oapi-codegen v2.8.0` 生成客户端；手写薄封装有 create/read/delete、幂等 ensure、探活和只返回名称的受限分页枚举测试。
|
||||
- T-003 对账进度与指数退避持久化，覆盖取消和 SQLite 重启恢复；T-006 增加真实 ONVIF adapter、RTSP router、实验室播种/状态工具、故障代理和五路自动验收。T-012 的普通调和不枚举孤儿；独立 PostgreSQL 扫描默认只报告，未知归属永不删除。
|
||||
- T-006 正式使用 1 台准入实机和 4 个独立合成 publisher 连续观察 `1806.6 s` / 180 次采样，四类恢复均通过，最大与最终 `unconverged` 均为 0；详细证据见 `docs/research/sense-5-stream-integration.md`。
|
||||
- `docs/raw/01`～`08` 已记录需求、分析、方案、客户场景、事件比对和三系统职责。
|
||||
- `docs/raw/contracts/event-v0.1.schema.json` 已冻结，并有多份示例与语义说明。
|
||||
- `docs/contracts/sense-control-v1.openapi.json` 的 7 个站点作用域/operation endpoint 已由 T-011 实现：外部静态 SHA-256 主体注册表、tenant/Site scope、HMAC cursor、ETag、PostgreSQL 24 小时幂等收据和最多 128 项 batch operation 均有代码与隔离集成测试。默认 SQLite 仍只暴露探针；Bell 管理服务、JWT/OIDC 和 Outbox relay 尚未实现。
|
||||
- `docs/contracts/sense-control-v1.openapi.json` 的 7 个站点作用域/operation endpoint 已由 T-011 实现：外部静态 SHA-256 主体注册表、tenant/Site scope、HMAC cursor、ETag、PostgreSQL 24 小时幂等收据和最多 128 项 batch operation 均有代码与隔离集成测试。默认 SQLite 只暴露运维探针与低基数 `/metrics`，不注册业务路由；Bell 管理服务、JWT/OIDC 和 Outbox relay 尚未实现。
|
||||
- T-012 把 PostgreSQL schema 提升到 v5：due row 用数据库时钟、`FOR UPDATE SKIP LOCKED`、逐项续租和 fencing token 协调；MediaMTX Path 历史归属、15 分钟孤儿快照、最多 10%/128 项安全闸、无 bypass 的本地处置命令及 `/metrics` 已实现。SQLite 明确保留单实例开发语义。
|
||||
- harness coding 文档、上下文清单、Gitea Issue/PR 模板和治理脚本已接入。
|
||||
- Gitea 已初始化 12 个协作标签；`status/waiting` 用于依赖或外部条件未满足的未领取任务，实时可领取状态必须从 Gitea 查询，不在本文复制。
|
||||
- T-002 已关闭架构影响型问题：首期 S2 民办寄宿学校、客户侧私有部署、ONVIF/RTSP、NVIDIA 主路径、自研 Bell、Web/H5 与客户侧证据存储等边界已批准。
|
||||
@@ -55,7 +56,7 @@ python scripts/validate_harness_governance.py
|
||||
./scripts/test_postgres.ps1 -PgRoot D:\pgsql17
|
||||
```
|
||||
|
||||
Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探针；它们不代表摄像头或 M1 里程碑健康。MediaMTX 获取、校验和独立启动方法见 `Sense/README.md`。
|
||||
Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz`、`/readyz` 运维探针和低基数 `/metrics`；探针不代表摄像头或 M1 里程碑健康。MediaMTX 获取、校验和独立启动方法见 `Sense/README.md`。
|
||||
|
||||
## 当前 blocker / 待确认
|
||||
|
||||
@@ -66,12 +67,12 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探
|
||||
- 人脸方向已延后至 M5 的 S4 成人园区候选试点；必要性/PIP 影响评估、单独同意与替代方式、合法底库来源和删除流程未完成，阻塞人脸能力上线。
|
||||
- 短信/语音具体供应商未选；生产前必须选定两条独立投递路径并验证故障切换。
|
||||
- Python/Savant 的精确版本、目标硬件和 Bell 前端栈尚未冻结；Sense M1 的 Go、SQLite driver、MediaMTX、生成器及生成运行时版本已在 T-003 冻结，PostgreSQL/pgx 版本已在 T-009 冻结。
|
||||
- 本机现有 PostgreSQL 5432 实例使用 SCRAM 且当前开发进程没有管理员密码；T-009～T-011 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、登录角色、外部 Control API 安全文件与备份方案。
|
||||
- 本机现有 PostgreSQL 5432 实例使用 SCRAM 且当前开发进程没有管理员密码；T-009～T-012 不绕过认证，自动验收使用隔离临时集群。向共享/生产实例安装 migration 前仍需管理员私下提供专用数据库、登录角色、外部 Control API 安全文件与备份方案。
|
||||
- 代码知识图谱在无业务代码阶段可能为空；工具不可用时使用 `rg` 处理文档与配置。
|
||||
|
||||
## 下一步
|
||||
|
||||
下一项建议创建 T-012，补齐 M2 对账安全闸、孤儿检测（只报告/受控处置）与多实例可观测性，再进入 WireGuard 和 16 路批量开通基准；不要把 Control API 完成误报为 M2 容量出口。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁。T-006 的合成结果不解除 T-007，也不形成容量或生产 SLA 承诺。
|
||||
下一项建议先冻结并实施 WireGuard 边缘隧道与断网恢复，再创建 16 路批量开通/停用和分维度容量基准任务；T-012 完成不等于 M2 容量出口。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁。T-006 的合成结果不解除 T-007，也不形成容量或生产 SLA 承诺。
|
||||
|
||||
## 已知风险
|
||||
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
# Sense 对账与孤儿处置 Runbook
|
||||
|
||||
本文适用于 PostgreSQL v5（migration `001`～`011`）与 MediaMTX `v1.19.3`。SQLite 仅用于单进程开发，不具备本 runbook 的多实例 fencing 或孤儿处置语义。
|
||||
|
||||
## 观察入口
|
||||
|
||||
- `GET /healthz`：进程存活。
|
||||
- `GET /readyz`：数据库 schema 和权限前置检查已完成。
|
||||
- `GET /metrics`：低基数进程指标；不包含 tenant、Site、device、Path 或 URI 标签。
|
||||
- 日志中的 `background convergence error`：只输出稳定、脱敏错误，不输出 stream URI 或凭据。
|
||||
|
||||
重点指标：
|
||||
|
||||
- `sense_reconcile_devices{state="unconverged"}`：未收敛的 enabled 视频设备数。
|
||||
- `sense_reconcile_items_total{result="lease_lost"}`：worker 在执行前或提交时失去 fencing token 的次数；失去租约的 worker 不得继续产生外部变更。
|
||||
- `sense_orphan_paths{classification="owned_stale|unowned"}`：最近一次成功扫描的两类差异。
|
||||
- `sense_orphan_cleanup_blocked_total`、`sense_orphan_cleanup_items_total`：安全闸阻断和人工处置结果。
|
||||
|
||||
## 多实例调和
|
||||
|
||||
每个实例应注入唯一、稳定且不含客户信息的 `SENSE_INSTANCE_ID`。PostgreSQL 使用数据库时钟、短事务、`FOR UPDATE SKIP LOCKED` 和随机 fencing token 领取 due row；批量等待中的每一项在调用 ONVIF/MediaMTX 前续租。默认租期 30 秒、单项 deadline 20 秒；operation timeout 必须严格短于租期。
|
||||
|
||||
发现 `lease_lost` 时先检查实例 ID 是否重复、数据库时钟和外部调用延迟。不要通过延长到超过 5 分钟或关闭 fencing 规避问题；先定位超时，再在变更评审后同时调整租期和单项 deadline。
|
||||
|
||||
## 生成孤儿报告
|
||||
|
||||
在已安装 v5 migration、能访问同一 PostgreSQL 和目标 MediaMTX 的受控运维主机执行：
|
||||
|
||||
```powershell
|
||||
$env:SENSE_DB_DRIVER = 'postgres'
|
||||
$env:SENSE_DB_DSN = '由部署环境私下设置'
|
||||
$env:SENSE_MEDIAMTX_URL = '受控 MediaMTX API 地址'
|
||||
go -C Sense run ./cmd/sense-orphan -mode report
|
||||
```
|
||||
|
||||
命令只输出 `scan_id`、计数、安全闸结论和过期时间。分类含义：
|
||||
|
||||
- `owned_stale`：Sense 有历史 Path 归属记录，但当前没有同一设备继续声明该 Path；可进入受控候选。
|
||||
- `unowned`：没有 Sense 归属证据；可能属于人工或其他系统，永远只报告。
|
||||
- 当前设备仍声明的 Path 不计入 finding。
|
||||
|
||||
不要因为名称相似把 `unowned` 手工改成 owned。先调查其创建者和用途；需要接管时应走独立、可审计的迁移任务。
|
||||
|
||||
## 执行受控处置
|
||||
|
||||
仅当报告显示 `safety_allowed=true`，并在 15 分钟有效期内由授权运维人员执行：
|
||||
|
||||
```powershell
|
||||
go -C Sense run ./cmd/sense-orphan -mode apply `
|
||||
-scan-id 'scan_...' `
|
||||
-actor 'operator-id' `
|
||||
-confirm 'DELETE scan_...'
|
||||
```
|
||||
|
||||
执行前程序会重新枚举 Path、重新读取归属并重新计算：候选必须仍是报告集合的子集、数量 1～128，且满足 `候选数 × 100 <= 当前 Path 总数 × 10`。过期、比例超限、归属变化、确认不匹配或租约冲突都会整批零删除；没有 `force`/bypass。删除逐项记入 PostgreSQL，成功项重复执行会跳过，失败项在快照仍有效且重新计算仍通过时可重试。
|
||||
|
||||
## 故障与恢复
|
||||
|
||||
- 扫描失败：不产生可执行快照；修复数据库/MediaMTX 连通性后重新 `report`。
|
||||
- `ratio_exceeded`：停止自动化，核对 MediaMTX 实例/分片是否选错、台账是否缺失或发生大面积配置漂移；不得拆小批次规避 10% 闸。
|
||||
- 部分删除失败：保留输出与数据库处置事实，修复 MediaMTX 后用同一 scan ID 重试；超过 15 分钟必须重新报告和审批。
|
||||
- 误删怀疑：立即停止 apply。数据库期望态仍是来源；当前设备声明的 Path 会由调和器重建。无当前设备声明的历史 Path 不自动恢复，应根据变更记录人工确认来源。
|
||||
- 回滚 Sense 二进制：先停用 `SENSE_ORPHAN_SCAN_ENABLED` 并停止所有新实例，再回滚；v5 表和已记录事实保留，不执行破坏性 down migration。
|
||||
|
||||
本流程只处置 MediaMTX 配置 Path，不删除设备、录像、证据对象或 Bell 数据。
|
||||
+11
-1
@@ -3,7 +3,7 @@ id: T-012
|
||||
title: 补齐 Sense 对账安全闸、孤儿受控处置与多实例可观测性
|
||||
phase: 2
|
||||
deps: [T-011]
|
||||
status: DOING
|
||||
status: DONE
|
||||
created: 2026-08-07
|
||||
issue: 43
|
||||
context_ref: 25357723a09218bae58626a9934309abcda34899
|
||||
@@ -88,6 +88,16 @@ T-003 已实现幂等调和与持久化退避，T-011 已完成 Control API、
|
||||
|
||||
## 执行记录
|
||||
|
||||
### 2026-08-07 完成多实例对账安全与孤儿受控处置
|
||||
|
||||
- PostgreSQL schema 提升到 v5：`010`/`011` 为 due row 增加 owner/token/expiry fencing，新增不含 source URI 的 MediaMTX Path 历史归属、孤儿扫描租约、15 分钟报告、发现项和处置审计，并补齐 `sense_app` 最小权限与 PUBLIC 拒绝；启动会拒绝旧 schema 或越权运行角色。
|
||||
- 调和器改为 `FOR UPDATE SKIP LOCKED` 批量领取、逐项续租、短于租期的外部调用 deadline 和带 token 的完成/失败；数据库时钟判定租约，旧 worker 不能覆盖接管者结果。成功启用在同一完成事务中刷新 Path 归属；SQLite 明确保留单进程开发语义。
|
||||
- MediaMTX 薄客户端新增只返回排序去重 Path 名称的有界分页枚举，包含重复页保护且不读取/返回 source；独立孤儿扫描把差异分为 `owned_stale` 与永不删除的 `unowned`。周期任务默认只报告，人工 `sense-orphan apply` 必须使用 15 分钟内 scan ID、合法 actor 和精确确认文本，并在删除前重取库存/归属。
|
||||
- 处置安全闸固定为 1～128 项且不超过当前 Path 的 10%，使用整数交叉相乘，无 force/bypass；目标只能从原快照收窄。逐项结果可审计和幂等重试，数据库外键/约束也拒绝为 `unowned` 写入删除记录。
|
||||
- 新增无第三方运行时依赖的 `/metrics`：只使用构建/实例及固定结果枚举标签，覆盖调和 run/item/lease-lost/时长/未收敛和孤儿扫描/阻断/删除汇总；tenant、Site、device、Path、URI 与错误正文均不进入标签。
|
||||
- `./scripts/test_postgres.ps1 -PgRoot D:\pgsql17` 通过：隔离 PostgreSQL 17.10 临时集群连续重放 `001`～`011`，SQL 权限/约束断言及 29 个 `TestPostgres*` 全绿，覆盖两个 store 并发唯一领取、租约接管/旧 token fencing、归属记录、扫描租约、未知 Path 数据库拒删和处置幂等；随机端口实例已停止并清理，现有 `D:\pgsql17\data`/5432 未被读取、停止或修改。
|
||||
- `./init.ps1` 通过；Python 治理/契约测试共 52 项通过，T-012 定向静态契约 12 项通过；全部 Go 测试、生成漂移、`go vet`、`go build` 与 `git diff --check` 通过；`go test -race ./internal/metrics ./internal/mtx ./internal/orphan ./internal/reconcile ./internal/store` 通过。不需要摄像头/GPU，本结果不解除 T-007，也不形成 16/128 路容量承诺。
|
||||
|
||||
### 2026-08-07 领取任务
|
||||
|
||||
- dispatcher `ila` 将 Issue #43 分配给 `codex`；`context_ref` 为 `25357723a09218bae58626a9934309abcda34899`，claim 为 `claims/T-012`，工作分支为 `agent/codex/T-012`。
|
||||
|
||||
Reference in New Issue
Block a user