Files
knowledge-governance/internal/releaseadapter/v071/library_reuse.go
T
姚章浩 537a6df46d
build / build (push) Successful in 1m39s
fix(library): 首次同步可复用同租户已存在资源
取消资源复用必须属于本目标历史成功同步/预备份的自加门槛。
仍要求目标行逐列一致与实际对象字节一致;旧库资源行/绑定/对象不删不改。
新增 reuse evidence v3:无 provenance,保留行摘要与逐对象字节证据。
2026-11-04 14:22:51 +08:00

459 lines
18 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
reuseEvidenceNoPrior = 3
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 && e.Version != 2 && e.Version != reuseEvidenceNoPrior {
return fmt.Errorf("复用证据版本 %d 不受支持(当前 %d)", e.Version, reuseEvidenceVersion)
}
if e.JobID == "" || e.Target == "" || e.TargetSnapshotID == "" || e.ResourceID == "" {
return errors.New("复用证据缺少作业/目标/快照/资源身份")
}
// v3:目标首次复用,本目标没有历史成功同步/预备份来源。归属改由
// “目标行 == 本次映射行”与“对象字节 == 归档对象”证明,不再要求 provenance。
// v1/v2 仍必须是完整历史来源,旧证据语义不变。
if e.Version != reuseEvidenceNoPrior &&
(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.Version == 1 && e.ProvenanceRowDigest != e.ArchivedRowDigest {
return errors.New("复用证据里的来源行与本次快照行不一致")
}
if e.Version == 2 && (e.ProvenanceKind != libraryrelease.PriorSnapshotPrebackup || e.ProvenanceRowDigest != e.RetargetedRowDigest) {
return errors.New("prebackup reuse proof differs from target projection")
}
if e.Version == reuseEvidenceNoPrior && (e.ProvenanceJobID != "" || e.ProvenanceSnapshotID != "" || e.ProvenanceKind != "" ||
len(e.Objects) == 0) {
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("复用证据没有摘要,拒绝落盘")
}
if err := evidence.Verify(); err != nil {
return "", err
}
raw, err := json.Marshal(*evidence)
if err != nil {
return "", err
}
path := reusePath(archiveRoot, evidence.Digest)
if err := persistImmutableJSON(path, raw); err != nil {
return "", 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
}
evidenceVersion := reuseEvidenceVersion
backupIDs, backupErr := archivedSnapshotResourceIDs(archive, plan.BackupSnapshotID)
if backupErr != nil {
return libraryrelease.WriteSetRow{}, backupErr
}
if backupIDs[id] {
baseline, err := archive.Load(plan.BackupSnapshotID)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if baseline.TenantID != t.scope.TenantID || baseline.KnowledgeBaseID != t.scope.KnowledgeBaseID {
return libraryrelease.WriteSetRow{}, errors.New("resource prebackup scope mismatch")
}
for _, p := range baseline.Parts {
if p.Kind != "database" || p.Name != "resources" {
continue
}
row, err := archivedRowByID(archive, p, id)
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
digest, err := canonicalRowDigest(projectRow(row, columns))
if err != nil {
return libraryrelease.WriteSetRow{}, err
}
if digest != retargetedDigest {
return libraryrelease.WriteSetRow{}, errors.New("shared resource differs from immutable before-image")
}
provenance = libraryrelease.PriorSnapshot{JobID: plan.JobID, SnapshotID: plan.BackupSnapshotID, Kind: libraryrelease.PriorSnapshotPrebackup}
provenanceDigest = digest
evidenceVersion = 2
}
}
if provenance.JobID == "" {
// 用户批准:首次同步不要求本目标历史归属。行内容一致已在上方核对;
// 下面仍逐对象核对实际字节,任一不一致即拒绝,且不删/不改旧库资源与绑定。
evidenceVersion = reuseEvidenceNoPrior
}
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: evidenceVersion, 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
}