From c2ab658033ffaa2ae8001134528214fe14f25c07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Fri, 30 Oct 2026 09:14:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E5=86=99=E9=9B=86?= =?UTF-8?q?=E5=90=88=E8=AF=81=E6=8D=AE=E8=A2=AB=E6=95=B4=E4=BB=BD=E8=A6=86?= =?UTF-8?q?=E7=9B=96=E7=9A=84=E9=99=B7=E9=98=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 trap 20:复用预备份时重新造一份证据,会让已登记的写集合锚点被整份 抹掉(现场 backup_bytes:0 + writeset_* 全丢)。写明症状、根因、负例优先的 判据与修法,含预备份版本行「一条只属于首次登记的作业」这一归属语义。 AGENTS.md 索引表那一行受写入保护、需主人批准,本次未改(见交接单待批准项)。 --- docs/agents/traps.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/agents/traps.md b/docs/agents/traps.md index ff86ed7..13095a3 100644 --- a/docs/agents/traps.md +++ b/docs/agents/traps.md @@ -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"——那不是"没有记录",不许覆盖。