Files
knowledge-governance/internal/libraryrelease/writeset.go
T
姚章浩 e0768f2caa
build / build (push) Successful in 1m34s
fix(library): 写集合台账与跨范围冲突预检
失败恢复会在写完之后按"目标租户里没人引用"清理资源行,于是历史孤儿、同租户其它
知识库暂未绑定的资源、被共享的资源都可能被删掉;而预备份里没有这些行,删了不可
恢复,随后整实例指纹才发现不一致,只能停在 rollback_failed。恢复校验依赖的整实例
证据又只存在内存里,worker 重启后只按快照 id 恢复,等于静默跳过比对。

改法:写第一笔之前把"本次明确写集合 + 写前存在状态 + 预备份时刻整实例内容证据"
算出来并按内容寻址落盘(文件名与治理库里的引用都是 sha256),摘要登记在预备份
版本证据里;恢复只删"写前不存在 ∧ 由本次写入 ∧ 不在恢复内容里"的精确 ID,并对
资源额外要求仍无绑定/正文引用;缺记录、记录被改、绑定对不上都直接失败、维护保持。
resources 的 upsert 补租户限定,跨范围同 ID 在写入之前就被预检拒绝。
整实例指纹从"身份集合"改成"逐行内容摘要",别的知识库同 ID 行被覆盖写坏也会暴露。

本地验证(已跑):
- make verify 15 项全 success(identity 因本地档案 skipped)
- go test ./internal/releaseadapter/v071/ -run Isolated(真实 PG + 真实 ES +
  真实 MinIO 对象存储,写失败按定位符注入):目标非空/同租户其它知识库/共享资源/
  历史孤儿/跨租户数据在失败恢复后逐行字节不变、本次残留 0;缺写集合拒绝恢复;
  跨范围 ID 冲突在写入前拒绝;wiki 阶段半写回滚干净
- SIGKILL 子进程后按盘上写集合接管恢复,目标原有数据逐行不变
- go test ./internal/libraryrelease/:写集合先于第一笔、规划失败/登记失败都不写目标、
  接管不重新规划
2026-10-29 23:55:13 +08:00

201 lines
7.0 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"`
}
// WriteSetPlan 是调用方在写第一笔之前交给目标的信息:绑定作业、目标、预备份与快照,
// 以及预备份时刻的整实例证据。
type WriteSetPlan struct {
JobID string
Target string
BackupSnapshotID string
TargetSnapshotID string
Universe map[string]TableFingerprint
}
// 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("写集合记录没有摘要")
}
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
}
// 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
}