5e1482e349
build / build (push) Successful in 1m40s
根因:生产可恢复性只有 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 例 + 契约/迁移/密钥/依赖锁定); 新增用例覆盖证据四条件、闸口证据优先、页面无证据/失败/通过三种呈现与管理员可见性。
233 lines
11 KiB
Go
233 lines
11 KiB
Go
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]
|
||
}
|