Files
knowledge-governance/internal/governance/library_flow.go
T
姚章浩 5e1482e349
build / build (push) Successful in 1m40s
feat(library): 恢复验证成为可页面发起的真实作业
根因:生产可恢复性只有 PRODUCTION_BACKUP_RESTORE_VERIFIED 这个手填 env 开关,
页面没有任何入口去真跑一次恢复;CLI(librarydrill)又不是 worker 能复用的实现,
所以"已验证"既证明不了跑过、也证明不了跑的是当前目标。

改动:
- 共享实现 internal/libraryverify(维护隔离→捕获→基线校验→canary→恢复→复核→关窗口),
  cmd/librarydrill 改为薄封装,CLI 与 worker 只允许一份执行体。
- verify 成为独立业务作业:kind + VerifyStages(capture/verify/canary/restore/finalize),
  与 sync/restore/baseline 共用同一把写互斥;迁移 79 加 kind 约束、重建部分唯一索引、
  新建 library_restore_verifications(按 target_id 绑定,换库/索引/桶旧证据自动失效,
  同 target+scope+job 幂等)。
- worker:admitLibraryJob + runOwnedLibraryAttempt 之后调用共享实现,阶段实时写
  library_job_stages,结束后写真实终态;通过写 passed 证据,失败写 failed+原因(不伪成功);
  中断接管按同一作业 id 收掉维护窗口。
- API:POST/GET /api/v1/library/verifications(管理员;闸口关闭/维护中拒绝;返回完整
  整库目标、最近证据、失败原因),OpenAPI 同步。
- 闸口:同步/恢复/续作的证据判断改为读当前目标证据;历史 env 仅在证据缺失时兜底,
  证据存在时以证据为准。
- 页面:生产保护与恢复面板加「恢复验证」块(完整 KB/索引/桶、状态、最近证据、失败原因、
  管理员按钮、5s 轮询),作业类型补 verify 文案。

测试:make verify 16/16 全绿(go 1387 例 + web 454 例 + 契约/迁移/密钥/依赖锁定);
新增用例覆盖证据四条件、闸口证据优先、页面无证据/失败/通过三种呈现与管理员可见性。
2026-11-03 10:14:08 +08:00

233 lines
11 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 governance
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"time"
)
// 整库版本与作业的领域类型:与队列(jobs)分开——队列负责租约与重试,
// 这里负责业务身份、阶段与结果,重启后仍能如实展示。
type LibraryVersionKind string
const (
// LibraryVersionTestSealed 是测试库封存产物:只证明一份完整测试版本被封存,
// 不代表生产生效,也不代表做过生产恢复演练。
LibraryVersionTestSealed LibraryVersionKind = "test_sealed"
// LibraryVersionProductionEffective 是生产当前权威版本:只有生产验证通过并
// 记录证据后才能写入,测试快照不能顶替它。
LibraryVersionProductionEffective LibraryVersionKind = "production_effective"
// LibraryVersionProductionPrebackup 是每次生产写入前的独立预备份。
LibraryVersionProductionPrebackup LibraryVersionKind = "production_prebackup"
// LibraryVersionRecoveryVerified 是"按预备份恢复并逐类校验通过"的恢复事实:
// 它让 current 指向恢复出来的内容身份,而不是继续宣称已经失败的新版本生效(F06)。
// 它不是测试封存,也不代表生产发布授权。
LibraryVersionRecoveryVerified LibraryVersionKind = "recovery_verified"
)
type LibraryJobKind string
const (
LibraryJobSeal LibraryJobKind = "seal"
LibraryJobSync LibraryJobKind = "sync"
// LibraryJobRestore 是按指定整库版本恢复:与同步分开,授权与阶段也独立。
LibraryJobRestore LibraryJobKind = "restore"
// LibraryJobRecover 是"按预备份恢复这个失败窗口"这一次**新意图**。
// 它必须是一条独立意图:恢复要把 current 指回更早发布的快照,而 current 的次序按
// 意图的创建时间排序(见 CurrentOrderKey),拿旧失败作业的身份去写就会被判成"迟到的
// 旧意图"而拒绝——那正是 F06 不能解决的形状。
LibraryJobRecover LibraryJobKind = "recover"
// LibraryJobBaseline 建立首次发布目标的权威基线:在维护隔离下把目标整库
// 读出来封存成快照并逐类校验,再登记成 production_effective。
// 它不写目标内容、不清空目标、不猜版本——基线只能来自真实捕获与校验。
LibraryJobBaseline LibraryJobKind = "baseline"
// LibraryJobVerify 是"恢复验证":在维护窗口内捕获目标 → 校验基线一致 →
// 写一个 canary 证明校验能发现差异 → 按预备份恢复 → 复核完全一致。
// 它是唯一能产生"生产可恢复"证据的作业,页面不再接受手填开关。
LibraryJobVerify LibraryJobKind = "verify"
)
type LibraryJobState string
const (
LibraryJobPending LibraryJobState = "pending"
LibraryJobRunning LibraryJobState = "running"
LibraryJobSucceeded LibraryJobState = "succeeded"
LibraryJobFailed LibraryJobState = "failed"
LibraryJobCancelled LibraryJobState = "cancelled"
)
// ErrLibraryJobActive:同一目标同一类作业已有在飞作业(数据库级互斥)。
var ErrLibraryJobActive = errors.New("library job already active for this target")
// ErrLibraryJobIdempotencyConflict:同一幂等键对应了不同的请求体。
var ErrLibraryJobIdempotencyConflict = errors.New("library job idempotency key reused with a different request")
type LibraryStage struct {
Stage string `json:"stage"`
State string `json:"state"`
// Total/Completed/BytesTotal/BytesDone 为 nil 表示该维度没有可靠数据,
// 界面必须显示"未知",不得当 0 或据此算百分比。
Total *int64 `json:"total"`
Completed *int64 `json:"completed"`
BytesTotal *int64 `json:"bytes_total"`
BytesDone *int64 `json:"bytes_done"`
Detail string `json:"detail"`
UpdatedAt time.Time `json:"updated_at"`
}
type LibraryJob struct {
ID string `json:"id"`
Scope string `json:"scope"`
Kind LibraryJobKind `json:"kind"`
State LibraryJobState `json:"state"`
Stage string `json:"stage"`
IdempotencyKey string `json:"-"`
// OperationID 让"同一个意图的多次执行"有稳定谱系;AttemptEpoch 是本次执行代次。
OperationID string `json:"operation_id"`
AttemptEpoch int `json:"attempt_epoch"`
RequestDigest string `json:"request_digest"`
QueueJobID string `json:"queue_job_id"`
SnapshotID string `json:"snapshot_id"`
TargetSnapshotID string `json:"target_snapshot_id"`
Actor string `json:"actor"`
Error string `json:"error"`
Recovery string `json:"recovery"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
FinishedAt *time.Time `json:"finished_at"`
Stages []LibraryStage `json:"stages"`
}
// LibraryVersion 是一条**不可变版本事件**。同一 operation 重放幂等(同 id 不重写),
// 不同 operation 引用同一快照是不同事件,谁也不覆盖谁的证据与作业归属。
type LibraryVersion struct {
ID string `json:"id"`
Scope string `json:"scope"`
Kind LibraryVersionKind `json:"kind"`
SnapshotID string `json:"snapshot_id"`
VersionLabel string `json:"version_label"`
SourceJobID string `json:"source_job_id"`
// OperationID/AttemptEpoch 是这条事件的执行身份:登记时用它做 epoch 守卫,
// 保证失租的旧代次不能写事件,也不能推进 current。
OperationID string `json:"operation_id"`
AttemptEpoch int `json:"attempt_epoch"`
// AttemptOwner 只用于 epoch 守卫(不落库、不展示):写入时必须与作业行租约一致。
AttemptOwner string `json:"-"`
Evidence map[string]any `json:"evidence"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
SupersededAt *time.Time `json:"superseded_at"`
}
// LibraryRequestDigest 绑定一次请求的确切含义:同键不同体必须被拒绝,而不是
// 复用旧作业。只覆盖会影响执行结果的字段;actor 不参与摘要。
// LibraryVersionID 生成版本记录 ID:library_versions.id 是 varchar(64),
// 用完整快照 ID 拼会超长(真实踩过),所以用稳定短摘要——同样的输入永远得到同一个 ID,
// 收尾重试因此是幂等的。
func LibraryVersionID(kind LibraryVersionKind, scope, snapshotID string) string {
sum := sha256.Sum256([]byte(string(kind) + "|" + scope + "|" + snapshotID))
return "libver-" + string(kind)[:0] + hex.EncodeToString(sum[:])[:16]
}
// QueueJobIDFor 生成队列作业 ID:jobs.id 是 varchar(36),
// 直接用业务作业 ID 加后缀会超长(真实踩过),所以用固定长度摘要。
func QueueJobIDFor(libraryJobID string) string {
sum := sha256.Sum256([]byte(libraryJobID))
return "q" + hex.EncodeToString(sum[:])[:32]
}
// LibraryHandoffQueueJobID 是"先搬运"这一步的队列作业号。
//
// 为什么单独一个函数:API(投递)与 capture worker(认所有权/幂等重放)必须算出同一个
// 值,否则重放会被判成"另一个执行者"。jobs.id 是 varchar(36),所以对带后缀的键再哈希,
// 而不是直接在 33 字符 ID 后面拼字符串。
func LibraryHandoffQueueJobID(libraryJobID string) string {
return QueueJobIDFor(libraryJobID + ":handoff")
}
func LibraryRequestDigest(scope string, kind LibraryJobKind, payload map[string]any) (string, error) {
canonical := map[string]any{"scope": scope, "kind": string(kind), "payload": payload}
raw, err := json.Marshal(canonical)
if err != nil {
return "", err
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:]), nil
}
// SyncStages 是生产同步作业的固定阶段顺序:先备份并核验恢复条件,再写生产,
// 最后验证;失败时走恢复而不是把作业标成功。
func SyncStages() []string {
// finalize 是收尾:登记生产生效版本。登记失败不得报成功,所以它是独立阶段。
return []string{"prebackup", "database", "resources", "index", "wiki", "verify", "finalize", "rollback"}
}
// SealStages 是封存作业的阶段:导出是原子操作,没有分项进度。
func SealStages() []string {
return []string{"export"}
}
// BaselineStages 是"建立目标权威基线"的阶段:捕获目标整库 → 与快照逐类校验
// → 登记生效版本。没有 rollback 阶段:基线过程不写目标内容。
func BaselineStages() []string {
return []string{"capture", "verify", "finalize"}
}
// VerifyStages 是恢复验证的阶段:捕获 → 基线校验 → 写 canary(证明校验有效)
// → 按预备份恢复 → 恢复后复核。canary 与 restore 都是真实写入,失败必须可见。
func VerifyStages() []string {
return []string{"capture", "verify", "canary", "restore", "finalize"}
}
// LibraryReleaseAuthorization 是生产发布授权:绑定目标、快照、参数摘要与有效期。
type LibraryReleaseAuthorization struct {
ID string `json:"id"`
Scope string `json:"scope"`
SnapshotID string `json:"snapshot_id"`
ParamsDigest string `json:"params_digest"`
AuthorizedBy string `json:"authorized_by"`
ExpiresAt time.Time `json:"expires_at"`
RevokedAt *time.Time `json:"revoked_at,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
// ValidAt 只在未撤销且未过期时为真;参数摘要由调用方显式比对。
func (a LibraryReleaseAuthorization) ValidAt(now time.Time) bool {
return a.RevokedAt == nil && now.Before(a.ExpiresAt)
}
// LibraryDeadLetterRelease 是治理平台对一条上游死信的精确解除记录。上游行保持原样,
// 这条记录只说明"这一行已被审计、重放并结清";指纹一变就不再命中。
type LibraryDeadLetterRelease struct {
ID string `json:"id"`
Instance string `json:"instance"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"kb_id"`
DeadLetterID int64 `json:"dead_letter_id"`
Fingerprint string `json:"fingerprint"`
TaskType string `json:"task_type"`
Scope string `json:"scope"`
ScopeID string `json:"scope_id"`
RelatedID string `json:"related_id"`
ReplayQueue string `json:"replay_queue"`
ReplayTaskID string `json:"replay_task_id"`
ReplayedAt time.Time `json:"replayed_at"`
ReplayEvidence string `json:"replay_evidence"`
ObservationDigest string `json:"observation_digest"`
Observation json.RawMessage `json:"observation"`
Note string `json:"note"`
Actor string `json:"actor"`
CreatedAt time.Time `json:"created_at"`
}
// LibraryDeadLetterReleaseID 生成解除记录 ID。同一实例同一指纹永远得到同一个 ID,
// 重复提交返回已存记录而不是造第二条审计。
func LibraryDeadLetterReleaseID(instance, fingerprint string) string {
sum := sha256.Sum256([]byte(instance + "|" + fingerprint))
return "dldr-" + hex.EncodeToString(sum[:])[:24]
}