Files
knowledge-governance/internal/libraryrelease/writeset.go
T
姚章浩 0252492e53 fix(library): 恢复保留下来的资源凭可审计证据复用
同步 A 成功后手工恢复 B,resources 表既不删行也不删对象;再同步 A 时,
resources 里那 21 行以“同租户但不在预备份范围”被判成别人的知识库,整次
同步在写第一笔之前被拒。

“目标里没人引用”不是归属证据:历史孤儿、其它知识库暂未绑定的资源都满足
它。改成唯一放行路径——可审计复用(v071/library_reuse.go):
1. 持久来源:这个目标成功同步过且登记过生效版本的快照,或它自己的预备份,
   且同一资源行在来源里内容一致;
2. 整行内容(除易变时间戳)与本次写入将要落地的行完全一致;
3. 该资源的对象字节与本次快照归档摘要一致。

三条同时成立才允许复用:写入阶段跳过它(不重写行、不重传对象),写集合里
记 existing+reused,恢复不清理;证据单独落盘 reuse/<digest>.json,摘要写进
写集合行,不冒充历史台账。内容不同、来源范围不同、或没有持久来源一律继续
拒绝,且拒绝发生在写入之前。

为什么把预备份也算来源:恢复作业的写集合同样会把“本目标历史状态里已有的
资源”判成跨范围冲突,而它们本来就出自这个目标自己的快照。

验证:隔离 PG+ES+MinIO 真服务下新增 5 个场景用例(复用成功且 xmin 不变、
无来源拒绝、内容不同拒绝、同内容不同来源拒绝、wiki 半写回滚只清本次新建);
v071 整包与全仓 go test 通过;make verify 15 项全绿。
2026-10-30 01:59:32 +08:00

255 lines
9.6 KiB
Go

package libraryrelease
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sort"
"time"
)
// WriteSetVersion 是写集合台账的格式版本。读到的版本不认识就拒绝恢复:
// 宁可保持维护,也不要用一份"格式变了但看起来还能读"的记录去删目标数据。
const WriteSetVersion = 1
// WriteSetRow 是台账里的一行:本次发布明确要写的精确身份 + 写前状态。
//
// 为什么需要"写前状态":恢复不能在目标里按"没人引用"推断残渣。历史孤儿资源、
// 同租户另一个知识库暂未绑定的资源、被多个知识库共享的资源,都满足"没人引用",
// 但它们不是这次作业写的,删掉就是数据丢失(快照里没有这些行,恢复不回来)。
// 只有写前不存在、且由本次写进去的行才允许清理。
type WriteSetRow struct {
Table string `json:"table"`
ID string `json:"id"`
// Existing 表示写前目标里已经有这一行(属于目标自己的数据,恢复一律不许删)。
Existing bool `json:"existing"`
// Owner 是写前该行的归属("<tenant>/<knowledge_base>"),不存在时为空。
Owner string `json:"owner,omitempty"`
// Reused 表示这一行虽然写前就在目标里、却不在预备份范围内,但已经用
// "持久作业/快照证据 + 整行内容 + 对象字节"证明与本次要写的内容完全一致,
// 因此本次既不重写它、也不在恢复时清理它。
//
// 不能只因为"它没被任何绑定/正文引用"就当成自己的:历史孤儿、同租户另一个
// 知识库暂未绑定的资源同样满足"没人引用",覆盖或删除同样是数据丢失。
Reused bool `json:"reused,omitempty"`
// ReuseEvidence 是可复用证据文档的摘要(reuse/<digest>.json),独立于写集合,
// 防止把这次推断伪装成历史台账。
ReuseEvidence string `json:"reuse_evidence,omitempty"`
}
// WriteSetPlan 是调用方在写第一笔之前交给目标的信息:绑定作业、目标、预备份与快照,
// 以及预备份时刻的整实例证据。
type WriteSetPlan struct {
JobID string
Target string
BackupSnapshotID string
TargetSnapshotID string
Universe map[string]TableFingerprint
// PriorSnapshots 是治理库里"这个目标的持久来源":成功同步过的快照,以及这个
// 目标自己的预备份。资源复用必须沿它把来源追到真实登记过的快照,而不是按
// "目标里没人引用"推断归属。
PriorSnapshots []PriorSnapshot
}
// 复用来源的两种合法类别。
const (
// PriorSnapshotSync:这个目标成功同步过这份快照(且登记了生效版本)。
PriorSnapshotSync = "sync"
// PriorSnapshotPrebackup:这份快照是从这个目标自己身上拍的预备份,把它写回去
// 就是回到本目标的历史状态。
PriorSnapshotPrebackup = "prebackup"
)
// PriorSnapshot 是一次**已登记**的来源:作业身份 + 快照身份 + 来源类别。
// 只有它也含有同一个资源 ID、且行内容完全一致,才允许把目标里那行当作
// "本次写入的等价物"。
type PriorSnapshot struct {
JobID string `json:"job_id"`
SnapshotID string `json:"snapshot_id"`
Kind string `json:"kind"`
FinishedAt time.Time `json:"finished_at,omitempty"`
}
// WriteSet 是"这一次发布的写集合 + 写前整实例内容证据",内容寻址、可校验、
// 与 job/target/backup 绑定。恢复只读它,不读目标现状去推断。
type WriteSet struct {
Version int `json:"version"`
JobID string `json:"job_id"`
Target string `json:"target"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"knowledge_base_id"`
BackupSnapshotID string `json:"backup_snapshot_id"`
TargetSnapshotID string `json:"target_snapshot_id"`
CreatedAt time.Time `json:"created_at"`
Rows []WriteSetRow `json:"rows"`
Universe map[string]TableFingerprint `json:"universe"`
// Digest 是对除本字段外全部内容的 sha256:落盘文件名与治理库里的引用都用它,
// 记录被改一个字节就对不上。
Digest string `json:"digest"`
}
// Seal 把行序规范化为可复现的顺序并写入摘要。调用方在落盘与登记之前必须先 Seal。
// 排序在这里落地(而不是只在算摘要时排),否则落盘字节与摘要覆盖的内容不一致。
func (w *WriteSet) Seal() error {
sort.Slice(w.Rows, func(i, j int) bool {
if w.Rows[i].Table != w.Rows[j].Table {
return w.Rows[i].Table < w.Rows[j].Table
}
return w.Rows[i].ID < w.Rows[j].ID
})
digest, err := w.computeDigest()
if err != nil {
return err
}
w.Digest = digest
return nil
}
// CanonicalBytes 是不含摘要字段的规范字节:摘要覆盖的就是它,落盘文件另外
// 带上摘要本身(便于自描述),读回时用同一份规范字节重新推导。
func (w WriteSet) CanonicalBytes() ([]byte, error) {
copied := w
copied.Digest = ""
rows := make([]WriteSetRow, len(w.Rows))
copy(rows, w.Rows)
// 行序不影响语义但影响摘要:两边都按 (table,id) 排序才能算出同一个值。
sort.Slice(rows, func(i, j int) bool {
if rows[i].Table != rows[j].Table {
return rows[i].Table < rows[j].Table
}
return rows[i].ID < rows[j].ID
})
copied.Rows = rows
raw, err := json.Marshal(copied)
if err != nil {
return nil, fmt.Errorf("编码写集合失败: %w", err)
}
return raw, nil
}
func (w *WriteSet) computeDigest() (string, error) {
raw, err := w.CanonicalBytes()
if err != nil {
return "", err
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:]), nil
}
// Verify 校验摘要与必备身份。缺任一身份都必须失败:没有绑定就没有"这份记录属于
// 这个作业/目标/预备份"的证明,拿它去删目标数据无法追责。
func (w *WriteSet) Verify() error {
if w.Version != WriteSetVersion {
return fmt.Errorf("写集合记录版本 %d 不受支持(当前 %d)", w.Version, WriteSetVersion)
}
if w.JobID == "" || w.BackupSnapshotID == "" || w.TargetSnapshotID == "" {
return errors.New("写集合记录缺少作业/预备份/快照绑定")
}
if w.TenantID == 0 || w.KnowledgeBaseID == "" {
return errors.New("写集合记录缺少目标范围身份")
}
if len(w.Universe) == 0 {
return errors.New("写集合记录缺少整实例内容证据")
}
if w.Digest == "" {
return errors.New("写集合记录没有摘要")
}
for _, row := range w.Rows {
if row.Reused && !row.Existing {
return fmt.Errorf("写集合记录把 %s/%s 标成可复用却不是写前已存在行", row.Table, row.ID)
}
if row.Reused && row.ReuseEvidence == "" {
return fmt.Errorf("写集合记录把 %s/%s 标成可复用却没有证据摘要", row.Table, row.ID)
}
}
digest, err := w.computeDigest()
if err != nil {
return err
}
if digest != w.Digest {
return errors.New("写集合记录摘要不符(内容被改动或截断)")
}
return nil
}
// CreatedIDs 返回"本次新建"的精确身份(写前不存在的行)。恢复只允许删这些。
func (w WriteSet) CreatedIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && !row.Existing {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// ExistingIDs 返回写前已存在的身份(用于恢复后复核"目标自己的行都还在")。
func (w WriteSet) ExistingIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && row.Existing {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// ReusedIDs 返回本次"证明可复用、因此既不重写也不清理"的精确身份。
// 它与 CreatedIDs 互斥,恢复清理一律不看这里(复用行必须原样保留)。
func (w WriteSet) ReusedIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && row.Reused {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// UniverseDigest 是整实例证据的摘要,随台账一起登记,便于独立核对。
func (w WriteSet) UniverseDigest() string {
if len(w.Universe) == 0 {
return ""
}
tables := make([]string, 0, len(w.Universe))
for table := range w.Universe {
tables = append(tables, table)
}
sort.Strings(tables)
type pair struct {
Count int64 `json:"count"`
Digest string `json:"digest"`
}
ordered := make([]pair, 0, len(tables))
for _, table := range tables {
ordered = append(ordered, pair{Count: w.Universe[table].Count, Digest: w.Universe[table].Digest})
}
raw, err := json.Marshal(struct {
Tables []string `json:"tables"`
Values []pair `json:"values"`
}{Tables: tables, Values: ordered})
if err != nil {
return ""
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:])
}
// WriteSetPlanner 由能访问目标与归档的实现提供:它在写第一笔之前算出写集合、
// 拒绝跨范围 ID 冲突,并把记录落盘。失败即"一笔都不许写"。
type WriteSetPlanner interface {
PlanWriteSet(ctx context.Context, plan WriteSetPlan) (WriteSet, error)
}
// WriteSetObserver 让调用方在写第一笔之前把写集合摘要持久化到治理库。
// 失败同样意味着"一笔都不许写":没有可追溯的写集合,恢复就只能靠推断。
type WriteSetObserver interface {
WriteSetPlanned(ctx context.Context, set WriteSet) error
}