Files
knowledge-governance/internal/libraryrelease/writeset.go
T
姚章浩 e0fc2c32b8
build / build (push) Successful in 2m11s
feat(library): 目标库隔离 ID 映射并保留旧库
同实例第二个目标 KB 与旧库共享源 UUID 时,计划/写入/校验/恢复按目标范围派生稳定身份;
计划持久化 target_id_mode,旧计划与写前镜像不二次映射;资源保持共享 ID。
2026-11-04 12:07:27 +08:00

383 lines
17 KiB
Go

package libraryrelease
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sort"
"strconv"
"time"
)
// WriteSetVersion 是写集合台账的格式版本。读到的版本不认识就拒绝恢复:
// 宁可保持维护,也不要用一份"格式变了但看起来还能读"的记录去删目标数据。
const WriteSetVersion = 1
// MigrationWriteSetVersion rejects reinterpretation by old V1 executors.
const MigrationWriteSetVersion = 2
// WriteSetKindRestoreDrill marks a write set that authorizes only a recovery
// drill: canary rows plus a zero-object/zero-index execution plan. It shares
// the V2 envelope so the object gateway controller can verify it, but it is
// never a publish plan and must not be adopted as one.
const WriteSetKindRestoreDrill = "restore-drill"
// 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 绑定。恢复只读它,不读目标现状去推断。
// LocalIDMapping is operation-local source lineage. Decimal strings are used
// only inside this typed sidecar; archived row values remain JSON integers.
type LocalIDMapping struct {
Table string `json:"table"`
Column string `json:"column"`
Source string `json:"source"`
Target string `json:"target"`
}
type WriteSet struct {
// Kind 区分发布执行计划与受限演练恢复计划。空值 = 历史发布计划。
// 演练计划必须显式为 restore-drill:它只授权 canary 回放,不含对象/索引
// 写项,读取方不能把它当发布计划接管。
Kind string `json:"kind,omitempty"`
// TargetIDMode 记录这份计划是否把源身份映射成目标隔离身份,以及用哪套算法。
// 空值 = 历史计划/写前镜像:按原 ID 回放,绝不能在恢复时二次映射。
TargetIDMode string `json:"target_id_mode,omitempty"`
Index []IndexWrite `json:"index,omitempty"`
Objects []ObjectWrite `json:"objects,omitempty"`
SchemaDigest string `json:"schema_digest,omitempty"`
ContractVersion int `json:"contract_version,omitempty"`
SourceTenantID uint64 `json:"source_tenant_id,omitempty"`
SourceKnowledgeBaseID string `json:"source_knowledge_base_id,omitempty"`
LocalIDs []LocalIDMapping `json:"local_ids,omitempty"`
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"`
}
// ValidateRestoreBinding 是恢复身份合同(DS01):写集合必须绑定**本次**预备份、
// 同一目标 tenant/KB,且来源快照(要回放到目标的内容身份)与写前镜像不能是同一份。
// 它是 ProductionLibraryTarget.Restore 在建任何派发绑定之前调用的同一个判定:
// 演练的写前/来源身份也必须过这一关,不能靠调用方约定。
func (w WriteSet) ValidateRestoreBinding(snapshotID string, tenantID uint64, knowledgeBaseID string) error {
if snapshotID == "" {
return errors.New("恢复需要绑定的预备份快照")
}
if w.BackupSnapshotID != snapshotID {
return fmt.Errorf("写集合记录绑定的是预备份 %s,不是 %s", w.BackupSnapshotID, snapshotID)
}
if w.TenantID != tenantID || w.KnowledgeBaseID != knowledgeBaseID {
return fmt.Errorf("写集合记录绑定的是 %d/%s,与目标 %d/%s 不一致",
w.TenantID, w.KnowledgeBaseID, tenantID, knowledgeBaseID)
}
// 派发绑定只能来自原锚点:来源快照是发布基线,backup 是这份写集的写前镜像。
// 二者缺失或相同都说明装配没有拿到真实身份,必须在任何写之前失败关闭。
if w.TargetSnapshotID == "" || snapshotID == "" {
return errors.New("恢复缺少来源快照或写前镜像,拒绝建立派发绑定")
}
if w.TargetSnapshotID == snapshotID {
return errors.New("来源快照与写前镜像不能是同一份快照,拒绝建立派发绑定")
}
return nil
}
// 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) {
if w.Version == WriteSetVersion && (w.ContractVersion != 0 || w.SourceTenantID != 0 || w.SourceKnowledgeBaseID != "" || len(w.LocalIDs) != 0 || w.SchemaDigest != "" || len(w.Objects) != 0 || len(w.Index) != 0) {
return nil, errors.New("historical V1 cannot carry migration contract fields")
}
if w.Version != WriteSetVersion && w.Version != MigrationWriteSetVersion {
return nil, errors.New("unsupported write set format")
}
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 校验摘要与必备身份。缺任一身份都必须失败:没有绑定就没有"这份记录属于
// 这个作业/目标/预备份"的证明,拿它去删目标数据无法追责。
const (
// TargetIDModeScoped 是目标隔离身份的持久契约标识。
// 算法是自定义的 sha256(namespace|tenant|kb|table|source) 16 字节派生,
// 只保证确定性与隔离,不自称标准 UUIDv5。
TargetIDModeScoped = "scoped-sha256-v1"
)
func (w *WriteSet) Verify() error {
if w.TargetIDMode != "" && w.TargetIDMode != TargetIDModeScoped {
return fmt.Errorf("unsupported target id mode %q", w.TargetIDMode)
}
if w.TargetIDMode == TargetIDModeScoped && (w.TenantID == 0 || w.KnowledgeBaseID == "") {
return errors.New("target id mode lacks target identity")
}
if w.ContractVersion != 0 && w.ContractVersion != 1 {
return errors.New("unsupported migration contract version")
}
if len(w.LocalIDs) > 0 && (w.ContractVersion != 1 || w.SourceTenantID == 0 || w.SourceKnowledgeBaseID == "") {
return errors.New("local mapping lacks source contract binding")
}
sources, targets := map[string]bool{}, map[string]bool{}
for _, m := range w.LocalIDs {
valid := (m.Table == "chunks" || m.Table == "knowledge_tags") && m.Column == "seq_id" || m.Table == "wiki_log_entries" && m.Column == "id"
a, e1 := strconv.ParseInt(m.Source, 10, 64)
b, e2 := strconv.ParseInt(m.Target, 10, 64)
if !valid || e1 != nil || e2 != nil || a <= 0 || b <= 0 || strconv.FormatInt(a, 10) != m.Source || strconv.FormatInt(b, 10) != m.Target {
return errors.New("invalid typed local mapping")
}
source, target := m.Table+"/"+m.Source, m.Table+"/"+m.Target
if sources[source] || targets[target] {
return errors.New("duplicate typed local mapping")
}
sources[source] = true
targets[target] = true
}
if w.Version != WriteSetVersion && w.Version != MigrationWriteSetVersion {
return fmt.Errorf("写集合记录版本 %d 不受支持(当前 %d)", w.Version, WriteSetVersion)
}
if w.Kind != "" && w.Kind != WriteSetKindRestoreDrill {
return fmt.Errorf("写集合记录种类 %q 不受支持", w.Kind)
}
if w.Kind == WriteSetKindRestoreDrill {
// 演练恢复计划只回放写前镜像:不新建对象、不按发布计划改索引、不做本地 ID 映射。
// 任何一项非空都说明它被当成发布计划构造/改写过,拒绝。
if w.Version != MigrationWriteSetVersion || w.ContractVersion != 1 || len(w.SchemaDigest) != 64 {
return errors.New("演练恢复计划缺少可执行契约(V2 + contract 1 + schema 摘要)")
}
if len(w.Objects) != 0 || len(w.Index) != 0 || len(w.LocalIDs) != 0 {
return errors.New("演练恢复计划不得包含对象/索引/本地映射写项")
}
if w.SourceTenantID == 0 || w.SourceKnowledgeBaseID == "" {
return errors.New("演练恢复计划缺少来源身份")
}
}
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
}
// IsRestoreDrill 表示这是一份受限演练恢复计划,而不是发布执行计划。
func (w WriteSet) IsRestoreDrill() bool { return w.Kind == WriteSetKindRestoreDrill }
// 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)
}
// WriteSetAdopter 让"计划已经存在"的执行也能带上复用语义(F07)。
//
// 触发场景:首次 planner 证明某些 resources 可复用 → 写集合落盘 → 进程中断 → 接管时用
// **新进程/新 target** 继续。写集合已存在,planner 因此被跳过;如果执行目标不消费这份
// 计划,它会按"没有复用"重新 upsert 资源行并重传对象——账本说"共享对象没动",实际却
// 重写了共享对象。必须显式接管计划,而不是重新按半写现状计划一遍。
type WriteSetAdopter interface {
AdoptWriteSet(set WriteSet) error
}
// WriteSetObserver 让调用方在写第一笔之前把写集合摘要持久化到治理库。
// 失败同样意味着"一笔都不许写":没有可追溯的写集合,恢复就只能靠推断。
type WriteSetObserver interface {
WriteSetPlanned(ctx context.Context, set WriteSet) error
}