为什么:维护窗口记录的是部署/实例指纹(journal 与 library_instance_maintenance), observeRestoreTarget 返回的是内容/索引/桶身份;两者本来不同层(r38 实测 dbe7… vs bb3f…)。v2 证据拆成 target_fingerprint 与 restore_target_fingerprint: 前者绑定窗口与治理行,后者绑定激活时的实时只读观察,避免用一个值冒充两层。
5.8 KiB
DS01 激活证据的不变量(v2)
状态:源码与隔离测试已实现;未在正式治理库执行激活。
相关实现:internal/libraryrelease/restore_dispatch_activation.go、
internal/platform/postgres/library_restore_dispatch_activation.go、
internal/libraryfreeze/journal_evidence.go。
1. 当前生产装配从哪里取得可核证据
worker(LIBRARY_RESTORE_DISPATCH_V2=true)
└─ librarymaintenance.Manager(LIBRARY_TARGET_*)
└─ libraryfreeze.Coordinator
├─ 关闭入口 → 读 gate drain.json(closed / drained / active_at_close)
├─ 等后台静默 → QuiesceProof(depth/pending_ops/unsettled=0,稳定窗口)
├─ 停写者 → Controller.Stop + Inventory 复核 + 退出码
└─ 写 <LIBRARY_TARGET_JOURNAL_ROOT>/<job>.json(state=held)
└─ library_instance_maintenance(治理库):instance / owner_job_id / target_fingerprint /
level=instance / services / state / released_at
激活是部署动作,不是业务请求:Store.ActivateRestoreDispatch 只在部署流程里调用。
Store.WithRestoreDispatchEvidence(LIBRARY_TARGET_JOURNAL_ROOT) 是唯一允许读取 journal 的根;
未配置该根 ⇒ ErrRestoreDispatchActivationDisabled(能力关闭),不退回"只看字符串"。
2. 证据文件只声明身份,不声明结论
v2 证据文档(protocol_version=2)字段。注意:台账行 library_index_restore_dispatch_activation.protocol_version
仍是 1(迁移 78 的派发协议身份约束),证据文档版本与台账协议版本不是同一个数字:
| 字段 | 含义 |
|---|---|
target_identity |
目标身份 |
target_fingerprint |
维护窗口/部署目标指纹(64 位 sha256 hex),必须等于 journal 与维护行 |
restore_target_fingerprint |
激活时对恢复目标(库/索引/桶)的实时观察指纹 |
target_instance |
治理库维护窗口的实例名,必须等于 journal 的 source |
governance_database |
当前治理库名,与 current_database() 比对 |
protocol_build |
必须是运行中二进制的 version.DisplayVersion() |
maintenance_job / maintenance_journal |
维护窗口作业;journal 名必须恰好是 <job>.json |
maintenance_journal_sha256 |
磁盘 journal 字节的 sha256(不是文件内自报值) |
writers[] {name, kind, instance_id} |
旧 writer 集合:名字对治理库 services,实例 ID 对 journal services[].id |
没有 stopped / queue_drained / exited_at / drain_evidence 这些调用方布尔字段。
"已退出、已排空"只能从 journal 事实与治理库行推出来。
3. 激活门逐项不变量
- A1 来源:journal 由
libraryfreeze写、位于配置的私有根(目录 0700、非符号链接); 文件以O_NOFOLLOW打开、≤1MiB、严格 JSON(未知字段拒绝)。 - A2 摘要:磁盘字节 sha256 == 证据声明值;写入台账的
drain_evidence_digest是这个值。 - A3 窗口状态:journal
state=held、level=instance;已recovered/released的窗口 不能证明"旧 writer 仍停着"。 - A4 实例绑定:journal
source== 证据target_instance,且 == 治理库library_instance_maintenance.instance。 - A5 作业绑定:journal
job== 证据maintenance_job== 维护行owner_job_id。 - A6 目标绑定:journal
target_fingerprint== 证据target_fingerprint== 维护行指纹; 证据restore_target_fingerprint== 调用方激活时对恢复目标的只读观察值。两者是 不同层(实例/部署 vs 内容/索引/桶身份),不能用一个值互相顶替。 - A7 入口排空:
ingress_closed=true、drain_verified=true、gateclosed && drained && active_at_close==0。 - A8 后台静默:
quiesce存在且 depth/pending_ops/unsettled 全 0、有合法 digest、 停写后复核(post_stop_at ≥ proven_at、post_stop_depth=0、post_stop_digest=digest)。 - A9 writer 集合:证据 writer 名字集合 == 维护行
services;实例 ID 集合 == journalservices[].id;每个 writerstop_requested=true且有exit_code;数量必须一致。 - A10 有效性:停写/排空观察(
quiesce.post_stop_at)在 2 小时有效期内; 证据attested_at不早于该观察、不晚于未来 5 分钟;窗口acquired_at早于观察。 - A11 现场身份:
current_database()等于证据库名;运行构建必须已注入身份且等于protocol_build;调用方传入的目标指纹必须等于证据指纹。 - A12 失败关闭:任一不满足 ⇒ 不写 activation 行;已撤销行的终局性仍由迁移 78 的
trigger 保证(
revoked_at→NULL、删行、状态倒退都拒绝)。
4. 它不证明什么
- 不独立观测"外部 writer 进程此刻不在运行";A7–A9 是维护链自己的受控观察 (入口 drain、退出码、后台静默),不是通用进程扫描。
- 不提供 ES 端 fence,也不保证已
dispatching的旧 owner 不会迟到一次。 - 不抵抗超级管理员禁用 trigger 或恢复旧 PG 快照。
5. 测试如何证明它不是"验字符串"
反例(真 PG,见 library_restore_dispatch_linearization_test.go):伪造 journal 摘要、
摘要计算后替换真实文件、错 writer 名字/实例、无退出码、从未要求停、入口未排空
(drained=false / active_at_close=1 / drain_verified=false)、停写观察过期、
证据过期、治理库身份不符、现场指纹不符、构建不符、维护窗口已释放、作业不属于窗口、
journal 已 recovered、未配置受信根。全部要求零 activation 行;正例才产生 1 行,并把
已核事实(journal 摘要、gate、quiesce、每个 writer 的退出码)写进 evidence.verified。