98294b9583
build / build (push) Failing after 24s
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
· 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
· 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
· 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
写业务状态、释放别人的维护锁;
· 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
· 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
· 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。
what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
· operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
· 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
心跳失租立刻取消 handler;
· 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
收尾;恢复成功登记 recovery 事件并推进 current;
· worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
· 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
发布前核目标实时模型契约、容量门禁前置;
· 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
· 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。
how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
265 lines
10 KiB
Go
265 lines
10 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)
|
|
}
|
|
|
|
// 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
|
|
}
|