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 的受控运维主机执行：

$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 分钟有效期内由授权运维人员执行：

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。

4.1 KiB Raw Blame History Unescape Escape