66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
# 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 数据。
|