docs: 记录写集合证据被整份覆盖的陷阱
build / build (push) Successful in 1m19s

新增 trap 20:复用预备份时重新造一份证据,会让已登记的写集合锚点被整份
抹掉(现场 backup_bytes:0 + writeset_* 全丢)。写明症状、根因、负例优先的
判据与修法,含预备份版本行「一条只属于首次登记的作业」这一归属语义。
AGENTS.md 索引表那一行受写入保护、需主人批准,本次未改(见交接单待批准项)。
This commit is contained in:
姚章浩
2026-10-30 09:14:14 +08:00
parent d0310761b6
commit c2ab658033
+43
View File
@@ -513,3 +513,46 @@ scheme)。`validObjectKey` 认这种形状并把它拆成裸 key,`ValidObjec
**修法**:`cmd/worker/library_takeover_log.go` 一份实现(认领行/决策行),两条认领路径
共用;`scripts/takeover_log_contract.py` 是唯一判据(含自检,进 `make verify`);
演练脚本 `verify_takeover_semantics` 改成上面那组断言。
## 20. 复用预备份时"重新造一份证据" ⇒ 已持久化的写集合锚点被整份抹掉
**症状**(2026-10-30T00:58Z 真实演练,job `librestore-internal-1793321916382871758-retry`):
SIGKILL 137 后按策略重启,接管认领与决策行都对,`database/resources/index/wiki/verify/finalize`
全部 `succeeded`,预备份快照 id、manifest 的 hash/mtime、首次 `created_at` 都没变,
`backup_reused:true` 也在;但 `verify_effective` 失败 —— 生效链上的
`writeset_digest` 从 `fddd98cf70…` 变成**空**。直接读生产库:
```
production_prebackup : {job, backup_bytes:0, backup_reused:true, backup_snapshot, index_mapping_sha256}
production_effective : {…, backup_bytes:0}
```
`writeset_*` 一个都不剩。同一作业第二次中断后再接管,`loadWriteSetForJob` 已经读不回
记录(`预备份 … 没有登记写集合摘要`)—— 恢复链在"再次故障"这一档彻底断掉。
**根因**:`BackupPrepared` 每次都**新造**一份证据 map(只放 `backup_snapshot`/`backup_bytes`/
`job`/`index_mapping_sha256`/`backup_reused`),而 `RecordLibraryVersion` 的 upsert 是
`evidence = EXCLUDED.evidence`(整份覆盖)。接管路径上:
- `ledgerBackupStore` 只带 `WriteSet`(没有字节数)⇒ 新证据里 `backup_bytes` 写 0;
- `WriteSetPlanned` 只在**首轮预检**时调用(`backup.WriteSet == nil` 才规划),
接管复用不重算 ⇒ 被抹掉的 `writeset_*` 没有任何一条路径会补回来。
**判据(负例优先)**:
- 真实 PG:`BackupPrepared` → `WriteSetPlanned` → `loadWriteSetForJob` → 接管
`Run`(复用)→ 再 `loadWriteSetForJob` 必须仍取回**同一摘要**;连做两轮中断+
第三次完整恢复后,证据里 `writeset_digest/writeset_rows/backup_bytes(真实值)/job/
backup_snapshot/backup_reused` 逐项还在,`created_at` 等于首次登记时刻;
- 把合并改回"新造一份 map"⇒ 该用例必须红(实测:`第 1 次接管后写集合丢失`);
- 复用却没有任何已登记证据、字节数与已登记不一致、证据 `job`/`backup_snapshot`
与本次不符 ⇒ 一律失败(不许"看起来对就合",那会把别的作业的写集合带进来);
- 同一作业第二次预检出**不同** `writeset_digest` ⇒ 失败(台账不再描述"实际写了什么");
- 复用拿不到真实字节 ⇒ 失败,不许把 0 写进证据(`backup_bytes:0` 与"空备份"不可区分)。
**修法**:`prebackupEvidence`(`cmd/worker/library_writeset.go`)一份实现,先核
`job`/`backup_snapshot` 身份再**合并**旧证据;接管路径用 `prebackupBytesOf` 从首次
登记的证据取回真实字节交给 `ledgerBackupStore`(`Bytes<=0` 直接拒绝);
生效版本证据统一由 `effectiveEvidence` 构造。预备份版本行的归属语义:
**一条预备份版本行只属于首次登记它的那个作业**,别的作业撞同一个快照 id 由
`LibraryVersionByRef` 报"属于作业 X"——那不是"没有记录",不许覆盖。