24608e132b
为什么:维护窗口记录的是部署/实例指纹(journal 与 library_instance_maintenance), observeRestoreTarget 返回的是内容/索引/桶身份;两者本来不同层(r38 实测 dbe7… vs bb3f…)。v2 证据拆成 target_fingerprint 与 restore_target_fingerprint: 前者绑定窗口与治理行,后者绑定激活时的实时只读观察,避免用一个值冒充两层。
86 lines
5.8 KiB
Markdown
86 lines
5.8 KiB
Markdown
# 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`、gate `closed && 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 集合 == journal
|
||
`services[].id`;每个 writer `stop_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`。 |