Files
knowledge-governance/cmd/worker/library_writeset.go
T
姚章浩 d0310761b6 fix(worker): 接管复用预备份不再抹掉写集合证据
BackupPrepared 每轮都新造一份证据,而版本登记是 evidence=EXCLUDED.evidence
整份替换。接管复用时 BackupRef 只带快照 id(没有字节数)、写集合预检又只在
首轮执行,于是已登记的 writeset_digest/writeset_rows 被抹掉、backup_bytes
记成 0;同一作业第二次中断后再接管就取不回写集合,恢复链彻底断开
(2026-10-30T00:58Z 演练 …-1793321916382871758-retry,摘要 fddd98cf70… → 空)。

现在证据按「同一作业 + 同一份预备份」合并进已持久化那一行,身份不符一律失败;
接管路径用 prebackupBytesOf 从首次登记的证据取回真实字节,缺失即拒绝(不再写 0);
生效版本证据统一由 effectiveEvidence 构造;同一作业的写集合只允许落定一次。

验证:真实 PG(一次性库 127.0.0.1:25471)上先复现再修
- 修前红:cmd/worker 两条新集成用例分别停在「第 1 次接管后写集合丢失」
  与「复用未登记的预备份竟然成功」
- 修后绿:两轮中断+接管+第三次完整恢复后 writeset_digest/backup_bytes(4096)/
  job/backup_snapshot/backup_reused 逐项存活,created_at 仍是首次登记时刻
- 反向自检(各自单独变异后复跑,均红):去掉合并、去掉身份核对、
  去掉摘要冲突判定、去掉复用字节硬门禁
- make verify:16 项全部 success(含 tests-go 真跑集成用例)
2026-10-30 09:14:10 +08:00

311 lines
14 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"sort"
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/libraryrelease"
v071 "knowledge-governance/internal/releaseadapter/v071"
)
// 写集合台账在治理侧的锚点:摘要登记在"这次作业的预备份版本"证据里。
// 为什么不用新表:版本记录本来就绑定 scope + snapshot + 作业,且 id 由这三者
// 决定;把摘要挂上去,重启后按同一身份就能取回,不需要改 schema。
// libraryVersionLookup 只暴露"按身份取一条版本记录"这一件事。
//
// 为什么不是"按 scope 列表":列表是有排序窗口的(真实 Store 上限 100),
// 历史超过窗口后登记/接管/恢复会把"存在"读成"不存在"。身份查询必须是精确条件,
// 而 found=false 只表示"这个身份没有记录",冲突由 store 返回错误(不许挑一条)。
type libraryVersionLookup interface {
LibraryVersionByRef(ctx context.Context, scope string, kind governance.LibraryVersionKind,
sourceJobID, snapshotID string) (governance.LibraryVersion, bool, error)
}
// libraryVersionLedger 是写集合锚点需要的两件事:按身份取一条、登记一条。
// 分开声明是为了让"身份不符/摘要冲突就失败"能在没有真实库时也被证明。
type libraryVersionLedger interface {
libraryVersionLookup
RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error
}
// writeSetDigestOf 读某次作业/某份预备份登记的写集合摘要。
// 读不到就返回错误:缺失必须让调用方失败,不能降级成"没有记录就当没写过"。
func writeSetDigestOf(ctx context.Context, store libraryVersionLookup, scope, jobID, snapshotID string) (string, error) {
version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup, jobID, snapshotID)
if err != nil {
return "", fmt.Errorf("读不到版本记录:%w", err)
}
if !found {
return "", fmt.Errorf("找不到作业 %s 的预备份版本记录(快照 %s)", jobID, snapshotID)
}
raw, _ := version.Evidence["writeset_digest"].(string)
if raw == "" {
return "", fmt.Errorf("预备份 %s 没有登记写集合摘要(作业 %s)", snapshotID, jobID)
}
return raw, nil
}
// loadWriteSetForJob 按"作业 + 目标 + 预备份"取回写集合并逐项核对绑定。
// 任何一步不符都返回错误:恢复宁可保持维护,也不许用一份对不上的记录去删目标数据。
func loadWriteSetForJob(ctx context.Context, store libraryVersionLookup, archiveRoot, scope, jobID, snapshotID string) (*libraryrelease.WriteSet, error) {
digest, err := writeSetDigestOf(ctx, store, scope, jobID, snapshotID)
if err != nil {
return nil, err
}
set, err := v071.LoadWriteSet(archiveRoot, digest)
if err != nil {
return nil, err
}
if set.JobID != jobID {
return nil, fmt.Errorf("写集合记录属于作业 %s,不是 %s", set.JobID, jobID)
}
if set.Target != scope {
return nil, fmt.Errorf("写集合记录属于目标 %s,不是 %s", set.Target, scope)
}
if set.BackupSnapshotID != snapshotID {
return nil, fmt.Errorf("写集合记录绑定预备份 %s,不是 %s", set.BackupSnapshotID, snapshotID)
}
return set, nil
}
// evidenceOwnerMatches 核对一份已持久化的证据是不是"这个作业 + 这份预备份"的。
//
// 为什么必须核这两维:版本行的 id 只由 (kind, scope, 快照) 决定,登记走 upsert。
// 只要调用方手里有一份"看起来对"的证据,就能把它盖到别人的行上;反过来,
// 合并证据时不核身份,就会把别的作业的写集合/字节数带进这一行。
func evidenceOwnerMatches(existing map[string]any, jobID, snapshotID string) error {
if job, ok := existing["job"].(string); ok && job != "" && job != jobID {
return fmt.Errorf("版本证据属于作业 %s,不是 %s:拒绝合并/覆盖", job, jobID)
}
if snapshot, ok := existing["backup_snapshot"].(string); ok && snapshot != "" && snapshot != snapshotID {
return fmt.Errorf("版本证据绑定预备份 %s,不是 %s:拒绝合并/覆盖", snapshot, snapshotID)
}
return nil
}
// evidenceBytes 取证据里的备份字节数。从库里读回来的是 float64(JSON 数字),
// 进程内构造的是 int64 —— 两种形状都要认,否则"字节数缺失"会被读成 0。
func evidenceBytes(evidence map[string]any) int64 {
switch value := evidence["backup_bytes"].(type) {
case int64:
return value
case int:
return int64(value)
case float64:
return int64(value)
case json.Number:
if parsed, err := value.Int64(); err == nil {
return parsed
}
}
return 0
}
// prebackupBytesOf 读某次作业/某份预备份已登记的备份字节数。
//
// 接管的预备份是"复用"的,ledgerBackupStore 手里只有快照 id 与写集合;
// 字节数只能来自首次登记的那条证据。读不到或非正数一律失败:把 0 写进
// 生效版本证据,事后就分不清"空备份"和"没记下来"(现场正是 backup_bytes:0)。
func prebackupBytesOf(ctx context.Context, store libraryVersionLookup, scope, jobID, snapshotID string) (int64, error) {
version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup, jobID, snapshotID)
if err != nil {
return 0, fmt.Errorf("读不到预备份版本证据:%w", err)
}
if !found {
return 0, fmt.Errorf("找不到作业 %s 的预备份版本记录(快照 %s)", jobID, snapshotID)
}
if err := evidenceOwnerMatches(version.Evidence, jobID, snapshotID); err != nil {
return 0, err
}
bytes := evidenceBytes(version.Evidence)
if bytes <= 0 {
return 0, fmt.Errorf("预备份 %s 没有可信的字节数(作业 %s):拒绝把 0 字节当恢复基线", snapshotID, jobID)
}
return bytes, nil
}
// writeSetEvidence 在预备份原有证据上追加写集合锚点(纯函数,便于单独验证)。
// 不能整份替换:备份字节、索引映射这些字段是页面与恢复都在用的。
func writeSetEvidence(existing map[string]any, set libraryrelease.WriteSet, mappingDigest string) map[string]any {
evidence := map[string]any{}
for key, value := range existing {
evidence[key] = value
}
evidence["backup_snapshot"] = set.BackupSnapshotID
evidence["job"] = set.JobID
if mappingDigest != "" {
evidence["index_mapping_sha256"] = mappingDigest
}
evidence["writeset_digest"] = set.Digest
evidence["writeset_universe_digest"] = set.UniverseDigest()
evidence["writeset_target_snapshot"] = set.TargetSnapshotID
evidence["writeset_rows"] = len(set.Rows)
evidence["writeset_reused_rows"] = len(set.ReusedIDs("resources"))
return evidence
}
// prebackupEvidence 把"这一轮预备份"的字段合并进已持久化的那份证据。
//
// 为什么必须是合并而不是覆盖:接管复用同一份预备份时,BackupRef 手里只有快照 id
// (字节数、写集合摘要都是首次那一轮登记的事实)。每次造新 map 就等于用
// "这一轮知道的东西"替换"上一次已经证明过的东西" —— 而 writeset_* 只会在
// 首轮规划时写入,接管路径根本不会重算,丢了就再也补不回来。
//
// 为什么不能无条件合并所有字段:版本行 id 只由 (kind, scope, 快照) 决定,
// 那一行可能属于另一个作业。所以先核身份(job/backup_snapshot),再只保留
// 与本作业、本预备份一致的部分;字节数出现两个不同真值也直接失败。
func prebackupEvidence(existing map[string]any, backup libraryrelease.BackupRef, jobID, mappingDigest string) (map[string]any, error) {
evidence := make(map[string]any, len(existing)+4)
for key, value := range existing {
evidence[key] = value
}
if err := evidenceOwnerMatches(evidence, jobID, backup.SnapshotID); err != nil {
return nil, err
}
bytes := backup.Bytes
if backup.Reused {
persisted := evidenceBytes(existing)
if bytes > 0 && persisted > 0 && bytes != persisted {
return nil, fmt.Errorf("复用预备份字节数不一致(本次 %d,已登记 %d):拒绝把两份不同的备份当成一份",
bytes, persisted)
}
if bytes <= 0 {
bytes = persisted
}
if bytes <= 0 {
return nil, fmt.Errorf("预备份 %s 复用登记缺少可信字节数:拒绝把 0 字节写进证据", backup.SnapshotID)
}
evidence["backup_reused"] = true
}
if bytes > 0 {
evidence["backup_bytes"] = bytes
}
evidence["backup_snapshot"] = backup.SnapshotID
evidence["job"] = jobID
if mappingDigest != "" {
evidence["index_mapping_sha256"] = mappingDigest
}
return evidence, nil
}
// WriteSetPlanned 把写集合摘要登记进"这次作业的预备份版本"证据。
// 它在第一笔写入之前被调用;失败即中止(调用方据此不写目标)。
//
// 这里读的是"这一条预备份记录"(scope+kind+作业+快照),不是"最近 N 条":
// 现场正是历史上限把这条记录顶出窗口,才在预备份已经落盘之后登记失败。
// 记录不存在同样拒绝——把锚点写到一个不存在的证据行上,会让后续接管/恢复
// 读不到备份字节与索引映射,等于伪造一份台账。
func (r libraryStageRecorder) WriteSetPlanned(ctx context.Context, set libraryrelease.WriteSet) error {
return anchorWriteSet(ctx, r.store, r.scope, r.jobID, r.mappingDigest, set)
}
// anchorWriteSet 是登记的实现:与 loadWriteSetForJob 一样只依赖"按身份取一条版本"
// 这一件事,便于在没有真实库时也能证明"身份不符/摘要冲突就失败"。
func anchorWriteSet(ctx context.Context, store libraryVersionLedger, scope, jobID, mappingDigest string,
set libraryrelease.WriteSet) error {
version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup,
jobID, set.BackupSnapshotID)
if err != nil {
return fmt.Errorf("读不到现有版本证据:%w", err)
}
if !found {
return fmt.Errorf("预备份 %s 的版本证据不存在(作业 %s):拒绝把写集合挂到不存在的记录上",
set.BackupSnapshotID, jobID)
}
// 同一作业的写集合只能落定一次:第二次预检出不同摘要,说明被登记的台账
// 不再描述"实际写了什么",恢复就无从按它清理——宁可停在写入之前。
if err := evidenceOwnerMatches(version.Evidence, jobID, set.BackupSnapshotID); err != nil {
return err
}
if recorded, ok := version.Evidence["writeset_digest"].(string); ok && recorded != "" && recorded != set.Digest {
return fmt.Errorf("预备份 %s 已登记写集合 %s,本次预检得到 %s:同一作业的写集合只能落定一次",
set.BackupSnapshotID, recorded, set.Digest)
}
evidence := writeSetEvidence(version.Evidence, set, mappingDigest)
return store.RecordLibraryVersion(ctx, governance.LibraryVersion{
ID: governance.LibraryVersionID(governance.LibraryVersionProductionPrebackup, scope, set.BackupSnapshotID),
Scope: scope, Kind: governance.LibraryVersionProductionPrebackup, SnapshotID: set.BackupSnapshotID,
SourceJobID: jobID, CreatedBy: "worker", Evidence: evidence, CreatedAt: time.Now().UTC(),
})
}
// ledgerBackupStore 是"接管/恢复"用的预备份来源:只认已经持久化的那一份,
// 并把它绑定的写集合一起带出来。
//
// 为什么不能像以前那样只返回 snapshot id:那一刻目标已经被写过,恢复若拿不到
// 写集合就只能按目标现状推断残渣——那正是会误删历史资源的路径。所以这里取不到
// 记录就直接失败,而不是返回一个"没有 Universe 的引用"。
type ledgerBackupStore struct {
ref libraryrelease.BackupRef
write *libraryrelease.WriteSet
}
func (s ledgerBackupStore) Prepare(context.Context, string, libraryrelease.CurrentState) (libraryrelease.BackupRef, error) {
if s.write == nil {
return libraryrelease.BackupRef{}, errors.New("恢复缺少持久化的写集合记录:拒绝在没有可追溯写集合的情况下继续")
}
// 字节数必须来自首次登记的证据:复用路径不重做备份,手上没有别的真值。
// 拿 0 继续会把"备份有多大"从生效版本证据里洗掉(现场 backup_bytes:0)。
if s.ref.Bytes <= 0 {
return libraryrelease.BackupRef{}, errors.New("恢复缺少已登记的真实备份字节数:拒绝用 0 字节当基线")
}
ref := s.ref
ref.WriteSet = s.write
// 明确的"复用":调用方据此把 backup_reused 落进版本证据,而不是让外部
// 从 created_at 变了没变去猜(那正是被同快照收尾伪造过的地方)。
ref.Reused = true
return ref, nil
}
// 能力必须在编译期就成立:Run 用的是类型断言(BackupObserver / WriteSetObserver),
// 少实现一个方法不会报错,只会让"预备份证据/写集合锚点"静默不落库(trap 14 的同一族)。
var (
_ libraryrelease.Recorder = libraryStageRecorder{}
_ libraryrelease.BackupObserver = libraryStageRecorder{}
_ libraryrelease.WriteSetObserver = libraryStageRecorder{}
_ libraryrelease.BackupStore = ledgerBackupStore{}
)
// effectiveEvidence 是"生产生效版本"证据的唯一构造点。
//
// 为什么单独成函数:生效版本证据里的 backup_bytes 是"这次恢复/同步用的是多大一份
// 基线"的唯一记录。接管复用路径上 BackupRef 若没带真实字节(历史缺陷),这里会
// 写进 0,事后与"空备份"无法区分(现场 production_effective 就是 backup_bytes:0)。
func effectiveEvidence(backup libraryrelease.BackupRef, action, mappingDigest string) map[string]any {
evidence := map[string]any{"backup_snapshot": backup.SnapshotID, "action": action}
if backup.Bytes > 0 {
evidence["backup_bytes"] = backup.Bytes
}
if mappingDigest != "" {
evidence["index_mapping_sha256"] = mappingDigest
}
return evidence
}
// sortedWriteSetSummary 只用于日志/证据:把本次写集合按表汇总成稳定的短摘要。
func sortedWriteSetSummary(set libraryrelease.WriteSet) string {
counts := map[string]int{}
for _, row := range set.Rows {
counts[row.Table]++
}
tables := make([]string, 0, len(counts))
for table := range counts {
tables = append(tables, table)
}
sort.Strings(tables)
summary := ""
for _, table := range tables {
if summary != "" {
summary += ","
}
summary += fmt.Sprintf("%s=%d", table, counts[table])
}
return summary
}