Files
knowledge-governance/internal/releaseadapter/v071/library_reuse.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

445 lines
17 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 v071
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"time"
"github.com/jackc/pgx/v5"
"knowledge-governance/internal/libraryrelease"
"knowledge-governance/internal/librarysnapshot"
)
// 资源复用证据:目标里已经有这个资源 ID、但它不在预备份范围内时,唯一安全的
// 处理是证明"本次要写的那一行/那一份对象字节,已经原样存在于目标里"。
//
// 为什么不能按"没人引用"推断归属:历史孤儿、同租户另一个知识库暂未绑定的资源
// 同样没人引用;按它放行等于允许覆盖别人的数据。这里的证据必须同时满足三件事:
// 1. 有可审计的持久来源(治理库里这个目标成功同步过的快照或它自己的预备份,
// 且同一资源行内容一致);
// 2. 整行内容(除易变时间戳外)与本次写入将要落地的行完全一致;
// 3. 该资源的对象字节与本次快照归档摘要一致。
//
// 证据独立落盘(reuse/<digest>.json),摘要写进写集合行;它不冒充历史写集合——
// 那两次没有 writeset 的成功作业依然没有 writeset。
const (
reuseDirName = "reuse"
reuseEvidenceVersion = 1
resourceReuseTableName = "resources"
)
// reuseObject 是一个资源对象的字节证据:归档摘要 + 目标现状必须匹配。
type reuseObject struct {
Name string `json:"name"`
Path string `json:"path"`
Bytes int64 `json:"bytes"`
SHA256 string `json:"sha256"`
}
// ResourceReuseEvidence 是"这一行可以复用"的完整证据文档。
// Digest 覆盖除自己以外的全部内容:被改动就对不上写集合行里的摘要。
type ResourceReuseEvidence 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"`
SourceTenantID uint64 `json:"source_tenant_id"`
SourceKnowledgeBaseID string `json:"source_knowledge_base_id"`
TargetSnapshotID string `json:"target_snapshot_id"`
ResourceID string `json:"resource_id"`
// ArchivedRowDigest 是来源快照里那一行(不含易变时间戳)的摘要。
ArchivedRowDigest string `json:"archived_row_digest"`
// RetargetedRowDigest 是同一行按本次目标范围/存储改写后的摘要。
RetargetedRowDigest string `json:"retargeted_row_digest"`
// TargetRowDigest 是目标现状按归档列投影后的摘要:必须与上一条一致。
TargetRowDigest string `json:"target_row_digest"`
// ProvenanceJobID / ProvenanceSnapshotID 指向一次**已成功**的同步作业及
// 它当时写入目标的快照;ProvenanceRowDigest 是那份快照里同一行的摘要。
ProvenanceJobID string `json:"provenance_job_id"`
ProvenanceSnapshotID string `json:"provenance_snapshot_id"`
ProvenanceKind string `json:"provenance_kind"`
ProvenanceRowDigest string `json:"provenance_row_digest"`
Objects []reuseObject `json:"objects,omitempty"`
CreatedAt time.Time `json:"created_at"`
Digest string `json:"digest"`
}
func reusePath(archiveRoot, digest string) string {
return filepath.Join(archiveRoot, reuseDirName, digest+".json")
}
// Seal 规范化并写入摘要;字段顺序由 json.Marshal 的结构体顺序固定。
func (e *ResourceReuseEvidence) Seal() error {
copied := *e
copied.Digest = ""
raw, err := json.Marshal(copied)
if err != nil {
return fmt.Errorf("编码复用证据失败: %w", err)
}
sum := sha256.Sum256(raw)
e.Digest = hex.EncodeToString(sum[:])
return nil
}
// Verify 校验版本、必备身份与摘要;缺任何一项都不许拿它去放行覆盖。
func (e *ResourceReuseEvidence) Verify() error {
if e.Version != reuseEvidenceVersion {
return fmt.Errorf("复用证据版本 %d 不受支持(当前 %d)", e.Version, reuseEvidenceVersion)
}
if e.JobID == "" || e.Target == "" || e.TargetSnapshotID == "" || e.ResourceID == "" ||
e.ProvenanceJobID == "" || e.ProvenanceSnapshotID == "" || e.ProvenanceKind == "" {
return errors.New("复用证据缺少作业/目标/快照/来源身份")
}
if e.TenantID == 0 || e.KnowledgeBaseID == "" || e.SourceTenantID == 0 || e.SourceKnowledgeBaseID == "" {
return errors.New("复用证据缺少范围身份")
}
// 三份行摘要必须一致:来源行、映射后的行、目标现状是同一份内容。
if e.RetargetedRowDigest == "" || e.TargetRowDigest != e.RetargetedRowDigest {
return errors.New("复用证据里目标行与本次要写的行不一致")
}
if e.ProvenanceRowDigest != e.ArchivedRowDigest {
return errors.New("复用证据里的来源行与本次快照行不一致")
}
copied := *e
copied.Digest = ""
raw, err := json.Marshal(copied)
if err != nil {
return err
}
sum := sha256.Sum256(raw)
if hex.EncodeToString(sum[:]) != e.Digest {
return errors.New("复用证据摘要不符(内容被改动或截断)")
}
return nil
}
// PersistReuseEvidence 按内容寻址落盘(只读、幂等)。同摘要已存在时校验后直接返回。
func PersistReuseEvidence(archiveRoot string, evidence *ResourceReuseEvidence) (string, error) {
if evidence.Digest == "" {
if err := evidence.Seal(); err != nil {
return "", err
}
}
if evidence.Digest == "" {
return "", errors.New("复用证据没有摘要,拒绝落盘")
}
directory := filepath.Join(archiveRoot, reuseDirName)
if err := os.MkdirAll(directory, 0700); err != nil {
return "", fmt.Errorf("创建复用证据目录失败: %w", err)
}
path := reusePath(archiveRoot, evidence.Digest)
if existing, readErr := os.ReadFile(path); readErr == nil {
var recorded ResourceReuseEvidence
if json.Unmarshal(existing, &recorded) != nil || recorded.Verify() != nil || recorded.Digest != evidence.Digest {
return "", errors.New("复用证据同名但内容不符,拒绝覆盖")
}
return path, nil
} else if !errors.Is(readErr, os.ErrNotExist) {
return "", fmt.Errorf("读取已有复用证据失败: %w", readErr)
}
raw, err := json.Marshal(*evidence)
if err != nil {
return "", fmt.Errorf("编码复用证据失败: %w", err)
}
temporary := path + ".tmp"
file, err := os.OpenFile(temporary, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
if err != nil {
return "", fmt.Errorf("写入复用证据失败: %w", err)
}
if _, err := file.Write(raw); err != nil {
file.Close()
os.Remove(temporary)
return "", fmt.Errorf("写入复用证据失败: %w", err)
}
if err := file.Sync(); err != nil {
file.Close()
os.Remove(temporary)
return "", fmt.Errorf("复用证据未落盘: %w", err)
}
if err := file.Close(); err != nil {
os.Remove(temporary)
return "", fmt.Errorf("复用证据未落盘: %w", err)
}
if err := os.Chmod(temporary, 0444); err != nil {
os.Remove(temporary)
return "", fmt.Errorf("复用证据只读化失败: %w", err)
}
if err := os.Rename(temporary, path); err != nil {
os.Remove(temporary)
return "", fmt.Errorf("复用证据落盘失败: %w", err)
}
return path, nil
}
// LoadReuseEvidence 取回并校验证据;摘要或绑定对不上就失败。
func LoadReuseEvidence(archiveRoot, digest string) (*ResourceReuseEvidence, error) {
if digest == "" {
return nil, errors.New("没有复用证据摘要")
}
raw, err := os.ReadFile(reusePath(archiveRoot, digest))
if err != nil {
return nil, fmt.Errorf("复用证据缺失(%s)", digest)
}
var evidence ResourceReuseEvidence
if err := json.Unmarshal(raw, &evidence); err != nil {
return nil, errors.New("复用证据不可解析")
}
if err := evidence.Verify(); err != nil {
return nil, err
}
if evidence.Digest != digest {
return nil, errors.New("复用证据摘要不符")
}
return &evidence, nil
}
// archivedRowByID 从归档部件里读出指定身份的行(原样,不改写)。
func archivedRowByID(archive *librarysnapshot.Archive, part librarysnapshot.Part, id string) (map[string]json.RawMessage, error) {
reader, err := archive.OpenPart(part)
if err != nil {
return nil, fmt.Errorf("读取归档 %s 失败", part.Name)
}
defer reader.Close()
decoder := json.NewDecoder(reader)
token, err := decoder.Token()
if err != nil || token != json.Delim('[') {
return nil, fmt.Errorf("归档 %s 不是行数组", part.Name)
}
for decoder.More() {
var row map[string]json.RawMessage
if err := decoder.Decode(&row); err != nil {
return nil, fmt.Errorf("解析归档 %s 行失败", part.Name)
}
var identity string
if json.Unmarshal(row["id"], &identity) == nil && identity == id {
return row, nil
}
}
return nil, nil
}
// targetResourceRow 读出目标里这一行;不存在返回 nil。
func (t *ProductionLibraryTarget) targetResourceRow(ctx context.Context, id string) (map[string]json.RawMessage, error) {
var raw map[string]json.RawMessage
err := t.pool.QueryRow(ctx, `SELECT to_jsonb(r) FROM resources r WHERE r.id=$1 AND r.tenant_id=$2`,
id, t.scope.TenantID).Scan(&raw)
if err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return nil, nil
}
return nil, fmt.Errorf("读取目标资源 %s 失败", id)
}
return raw, nil
}
// cloneRow 复制一行,避免改写归档缓存/调用方数据。
func cloneRow(row map[string]json.RawMessage) map[string]json.RawMessage {
copied := make(map[string]json.RawMessage, len(row))
for key, value := range row {
copied[key] = value
}
return copied
}
// projectRow 只保留给定列集合里的列:目标行比归档多出的默认列不参与比对。
func projectRow(row map[string]json.RawMessage, columns map[string]bool) map[string]json.RawMessage {
projected := make(map[string]json.RawMessage, len(columns))
for key := range columns {
if value, ok := row[key]; ok {
projected[key] = value
}
}
return projected
}
// targetObjectSHA256 读取目标对象的实际字节并返回大小与摘要。
func (t *ProductionLibraryTarget) targetObjectSHA256(ctx context.Context, provider, path string) (int64, string, error) {
if t.config.ObjectsReader == nil {
return 0, "", errors.New("缺少目标对象读取器,无法证明对象字节一致")
}
reader, err := t.config.ObjectsReader.Open(ctx, provider, path)
if err != nil {
return 0, "", err
}
defer reader.Close()
hash := sha256.New()
size, err := io.Copy(hash, reader)
if err != nil {
return 0, "", err
}
return size, hex.EncodeToString(hash.Sum(nil)), nil
}
// resourceLocatorField 解析改写后的资源行里的定位符与提供方(与写入/校验同一口径)。
func resourceLocatorField(row map[string]json.RawMessage) (provider, path string, err error) {
if err := json.Unmarshal(row["provider"], &provider); err != nil {
return "", "", errors.New("资源行提供方不可解析")
}
if err := json.Unmarshal(row["physical_path"], &path); err != nil || path == "" {
return "", "", errors.New("资源行定位符不可解析")
}
return provider, path, nil
}
// provenanceFor 在"这个目标的持久来源"里找同一资源的同一行内容:
// - 成功同步过的快照(说明这个目标先前就把这行写进去过);
// - 这个目标自己的预备份(说明这行本来就是本目标历史状态的一部分)。
//
// 找不到就说明归属无法证明:即使目标里那行看起来一模一样,也不能覆盖/复用。
func provenanceFor(archive *librarysnapshot.Archive, manifest librarysnapshot.Manifest, targetSnapshotID,
id, archivedDigest string, prior []libraryrelease.PriorSnapshot) (libraryrelease.PriorSnapshot, string, error) {
for _, candidate := range prior {
if candidate.JobID == "" || candidate.SnapshotID == "" {
continue
}
if candidate.SnapshotID == targetSnapshotID {
// 本次要写的快照本身就是一次成功同步写进目标的那一份。
return candidate, archivedDigest, nil
}
priorManifest, err := archive.Load(candidate.SnapshotID)
if err != nil {
// 来源快照不可读不能当作"没有来源":那会把不可审计变成静默放行。
return libraryrelease.PriorSnapshot{}, "", fmt.Errorf("复用来源快照 %s 不可读", candidate.SnapshotID)
}
if priorManifest.TenantID != manifest.TenantID || priorManifest.KnowledgeBaseID != manifest.KnowledgeBaseID {
continue
}
var part librarysnapshot.Part
found := false
for _, item := range priorManifest.Parts {
if item.Kind == "database" && item.Name == resourceReuseTableName {
part, found = item, true
break
}
}
if !found {
continue
}
row, err := archivedRowByID(archive, part, id)
if err != nil {
return libraryrelease.PriorSnapshot{}, "", err
}
if row == nil {
continue
}
digest, err := canonicalRowDigest(row)
if err != nil {
return libraryrelease.PriorSnapshot{}, "", err
}
if digest != archivedDigest {
continue
}
return candidate, digest, nil
}
return libraryrelease.PriorSnapshot{}, "", nil
}
// planReusableResource 是资源冲突的唯一放行路径:内容相同 + 字节相同 + 来源可审计。
// 返回写集合行(Existing + Reused)并把它登记到本次目标,写入阶段据此跳过这一行。
func (t *ProductionLibraryTarget) planReusableResource(ctx context.Context, archive *librarysnapshot.Archive,
manifest librarysnapshot.Manifest, part librarysnapshot.Part, id, owner string,
plan libraryrelease.WriteSetPlan) (libraryrelease.WriteSetRow, error) {
archived, err := archivedRowByID(archive, part, id)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if archived == nil {
return libraryrelease.WriteSetRow{}, fmt.Errorf("资源 %s 在快照 %s 的 resources 部件里找不到", id, plan.TargetSnapshotID)
}
archivedDigest, err := canonicalRowDigest(archived)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
columns := map[string]bool{}
for key := range archived {
columns[key] = true
}
retargeted := cloneRow(archived)
if err := t.retargetRow(resourceReuseTableName, retargeted); err != nil {
return libraryrelease.WriteSetRow{}, err
}
retargetedDigest, err := canonicalRowDigest(retargeted)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
existing, err := t.targetResourceRow(ctx, id)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if existing == nil {
return libraryrelease.WriteSetRow{}, fmt.Errorf("资源 %s 在目标里已不存在,不能复用", id)
}
targetDigest, err := canonicalRowDigest(projectRow(existing, columns))
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if targetDigest != retargetedDigest {
return libraryrelease.WriteSetRow{}, fmt.Errorf(
"资源 ID 冲突:%s 已存在于目标租户但内容与本次快照不一致(目标 %s / 本次 %s),拒绝覆盖",
id, shortDigest(targetDigest), shortDigest(retargetedDigest))
}
provenance, provenanceDigest, err := provenanceFor(archive, manifest, plan.TargetSnapshotID, id, archivedDigest, plan.PriorSnapshots)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if provenance.JobID == "" {
return libraryrelease.WriteSetRow{}, fmt.Errorf(
"资源 ID 冲突:%s 已存在于目标租户但不在预备份范围内,且没有可审计的持久来源(成功同步/预备份)证明它属于本目标,拒绝覆盖", id)
}
provider, path, err := resourceLocatorField(retargeted)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
objects := make([]reuseObject, 0, 2)
for _, item := range manifest.Parts {
if item.Kind != "resource" || item.Name != id {
continue
}
size, digest, err := t.targetObjectSHA256(ctx, provider, path)
if err != nil {
return libraryrelease.WriteSetRow{}, fmt.Errorf("资源 %s 的对象读不到,无法证明字节一致:%w", id, err)
}
if size != item.Bytes || digest != item.SHA256 {
return libraryrelease.WriteSetRow{}, fmt.Errorf(
"资源 ID 冲突:%s 的目标对象字节与本次快照不一致(%d/%d 字节),拒绝覆盖",
id, size, item.Bytes)
}
objects = append(objects, reuseObject{Name: item.Name, Path: path, Bytes: size, SHA256: digest})
}
evidence := &ResourceReuseEvidence{
Version: reuseEvidenceVersion, JobID: plan.JobID, Target: plan.Target,
TenantID: t.scope.TenantID, KnowledgeBaseID: t.scope.KnowledgeBaseID,
SourceTenantID: manifest.TenantID, SourceKnowledgeBaseID: manifest.KnowledgeBaseID,
TargetSnapshotID: plan.TargetSnapshotID, ResourceID: id,
ArchivedRowDigest: archivedDigest, RetargetedRowDigest: retargetedDigest, TargetRowDigest: targetDigest,
ProvenanceJobID: provenance.JobID, ProvenanceSnapshotID: provenance.SnapshotID, ProvenanceKind: provenance.Kind,
ProvenanceRowDigest: provenanceDigest, Objects: objects, CreatedAt: t.now().UTC(),
}
if _, err := PersistReuseEvidence(t.config.ArchiveRoot, evidence); err != nil {
return libraryrelease.WriteSetRow{}, fmt.Errorf("复用证据无法落盘,拒绝放行覆盖:%w", err)
}
if t.reusedResources == nil {
t.reusedResources = map[string]bool{}
}
t.reusedResources[id] = true
return libraryrelease.WriteSetRow{Table: resourceReuseTableName, ID: id, Existing: true,
Owner: owner, Reused: true, ReuseEvidence: evidence.Digest}, nil
}
func shortDigest(digest string) string {
if len(digest) > 12 {
return digest[:12]
}
return digest
}