Files
knowledge-governance/internal/libraryrelease/release.go
T
姚章浩 281699a431
build / build (push) Successful in 1m21s
feat(library): 生产整库真实读写/校验/恢复与本机真实服务验收
为什么:生产目标此前是"无条件失败"的占位,编排再完整也不能落地;本轮把它做成真实实现,
并在本机 WeKnora 测试栈的真实 PG/ES 上跑通导入、撤销、预备份与故障恢复。

- ProductionLibraryTarget:Current 读行数+身份摘要;Apply 按阶段真实写入(database/wiki
  同事务先删本库再插、resources 传对象、index 搬运原始文档与向量);Verify 比对身份摘要;
  Restore 按预备份快照回放。
- 撤销真正生效:索引阶段写入后 PruneScope 删除快照里没有的文档。
- ProductionBackupStore:导出前独立完整预备份,导出前后行数不一致即失败。
- worker 用注入配置装配目标与预备份;缺项把变量名写进阶段并失败,不再有占位对象。
- capacity 安全加法防溢出;保留策略组合语义明确(各维度都超限才候选)。
- 新增本机真实服务集成测试(一次性 kg_library_test_* 库 + 随机 ES 索引),
  覆盖导入/校验/撤销/预备份/故障注入/恢复。
2026-10-28 15:54:01 +08:00

209 lines
7.8 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 libraryrelease 是生产同步的执行编排:预备份 → 四类写入 → 验证 → 失败恢复。
//
// 它只编排顺序与责任,不自己连生产:目标读写由 Target 注入,备份由 BackupStore 注入,
// 授权由 Grant 描述。任何一步失败都不得标记成功;失败后必须尝试恢复原生产版本,
// 恢复失败要作为独立的、更严重的结论上报。
package libraryrelease
import (
"context"
"errors"
"fmt"
"time"
)
// Stage 是四类需要真实落地的数据;顺序即写入顺序。
type Stage string
const (
StageDatabase Stage = "database"
StageResources Stage = "resources"
StageIndex Stage = "index"
StageWiki Stage = "wiki"
)
func Stages() []Stage { return []Stage{StageDatabase, StageResources, StageIndex, StageWiki} }
// Grant 是一次生产发布的授权:绑定确切目标与快照,带有效期与参数摘要。
// 参数一旦变化(例如换了目标快照)就必须重新授权,不能复用旧 grant。
type Grant struct {
Target string `json:"target"`
SnapshotID string `json:"snapshot_id"`
ExpiresAt time.Time `json:"expires_at"`
ParamsDigest string `json:"params_digest"`
AuthorizedBy string `json:"authorized_by"`
}
// Request 是一次待执行的生产同步。
type Request struct {
Target string
SnapshotID string
// ParamsDigest 覆盖会影响生产结果的全部参数(目标、快照、排除范围等)。
ParamsDigest string
Grant Grant
Now time.Time
}
// CurrentState 是生产当前整库的指纹,用于预备份与最终验证。
type CurrentState struct {
Revision string `json:"revision"`
Counts map[string]int64 `json:"counts"`
Digests map[string]string `json:"digests"`
CapturedAt time.Time `json:"captured_at"`
}
// Expectation 是同步完成后生产应当具备的状态(来自测试封存)。
type Expectation struct {
SnapshotID string
Counts map[string]int64
Digests map[string]string
}
// BackupRef 指向一份可独立恢复的完整预备份。
type BackupRef struct {
ID string `json:"id"`
// SnapshotID 是预备份在归档里的快照身份:恢复必须按它回放,
// 不能只记"备份路径"却不知道恢复到哪一份内容。
SnapshotID string `json:"snapshot_id"`
Bytes int64 `json:"bytes"`
CreatedAt time.Time `json:"created_at"`
}
type Target interface {
// Current 读取生产当前整库指纹;读不到就不能开始写入。
Current(ctx context.Context) (CurrentState, error)
// Apply 把一类数据写入生产;实现必须幂等或可回滚。
Apply(ctx context.Context, stage Stage, snapshotID string) error
// Verify 校验生产是否与期望一致。
Verify(ctx context.Context, expect Expectation) error
// Restore 把生产恢复到给定预备份。
Restore(ctx context.Context, backup BackupRef) error
}
type BackupStore interface {
// Prepare 创建独立完整预备份,并在返回前自检可恢复性。
Prepare(ctx context.Context, snapshotID string, current CurrentState) (BackupRef, error)
}
// Recorder 把阶段状态写进持久作业,供页面恢复展示。
type Recorder interface {
Stage(ctx context.Context, stage string, state string, detail string)
}
type recorderFunc func(ctx context.Context, stage, state, detail string)
func (f recorderFunc) Stage(ctx context.Context, stage, state, detail string) {
f(ctx, stage, state, detail)
}
// NoopRecorder 用于测试或不需要落库的调用。
type NoopRecorder struct{}
func (NoopRecorder) Stage(context.Context, string, string, string) {}
type Outcome struct {
State string `json:"state"` // succeeded | failed | rolled_back | rollback_failed
Backup BackupRef `json:"backup"`
FailedAt Stage `json:"failed_at,omitempty"`
Error string `json:"error,omitempty"`
Rollback string `json:"rollback,omitempty"`
Finished time.Time `json:"finished"`
}
var (
ErrGrantExpired = errors.New("发布授权已过期")
ErrGrantTarget = errors.New("发布授权与目标不匹配")
ErrGrantSnapshot = errors.New("发布授权与快照不匹配")
ErrGrantParams = errors.New("发布参数与授权不一致")
ErrBackupUnavailable = errors.New("无法创建可独立恢复的生产预备份")
)
// ValidateGrant 在动生产之前把授权核对清楚:目标、快照、参数摘要、有效期,
// 任一项不符都直接拒绝,不做"先写一半再说"。
func ValidateGrant(request Request) error {
if request.Grant.Target != request.Target {
return fmt.Errorf("%w:授权 %q,请求 %q", ErrGrantTarget, request.Grant.Target, request.Target)
}
if request.Grant.SnapshotID != request.SnapshotID {
return fmt.Errorf("%w:授权 %q,请求 %q", ErrGrantSnapshot, request.Grant.SnapshotID, request.SnapshotID)
}
if request.Grant.ParamsDigest != request.ParamsDigest {
return ErrGrantParams
}
now := request.Now
if now.IsZero() {
now = time.Now()
}
if request.Grant.ExpiresAt.IsZero() || !now.Before(request.Grant.ExpiresAt) {
return ErrGrantExpired
}
return nil
}
// Run 执行完整链路。任何阶段失败都会尝试恢复;只有全部成功才返回 succeeded。
func Run(ctx context.Context, request Request, target Target, backups BackupStore, recorder Recorder) Outcome {
outcome := Outcome{State: "failed", Finished: time.Now().UTC()}
if recorder == nil {
recorder = NoopRecorder{}
}
if err := ValidateGrant(request); err != nil {
outcome.Error = err.Error()
recorder.Stage(ctx, "prebackup", "failed", err.Error())
return outcome
}
recorder.Stage(ctx, "prebackup", "running", "读取生产当前状态并创建预备份")
current, err := target.Current(ctx)
if err != nil {
// 读不到生产当前状态就不能写:否则回滚目标都没有。
outcome.Error = "读取生产当前状态失败:" + err.Error()
recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
return outcome
}
backup, err := backups.Prepare(ctx, request.SnapshotID, current)
if err != nil {
outcome.Error = fmt.Sprintf("%v:%v", ErrBackupUnavailable, err)
recorder.Stage(ctx, "prebackup", "failed", outcome.Error)
return outcome
}
outcome.Backup = backup
recorder.Stage(ctx, "prebackup", "succeeded", "预备份 "+backup.ID)
for _, stage := range Stages() {
recorder.Stage(ctx, string(stage), "running", "")
if err = target.Apply(ctx, stage, request.SnapshotID); err != nil {
return failAndRestore(ctx, outcome, target, recorder, stage, err)
}
recorder.Stage(ctx, string(stage), "succeeded", "")
}
recorder.Stage(ctx, "verify", "running", "")
expect := Expectation{SnapshotID: request.SnapshotID, Counts: current.Counts, Digests: current.Digests}
if err = target.Verify(ctx, expect); err != nil {
return failAndRestore(ctx, outcome, target, recorder, "verify", err)
}
recorder.Stage(ctx, "verify", "succeeded", "")
outcome.State = "succeeded"
outcome.Finished = time.Now().UTC()
return outcome
}
func failAndRestore(ctx context.Context, outcome Outcome, target Target, recorder Recorder, stage Stage, cause error) Outcome {
outcome.FailedAt = stage
outcome.Error = cause.Error()
outcome.Finished = time.Now().UTC()
recorder.Stage(ctx, string(stage), "failed", cause.Error())
recorder.Stage(ctx, "rollback", "running", "恢复到预备份 "+outcome.Backup.ID)
if restoreErr := target.Restore(ctx, outcome.Backup); restoreErr != nil {
// 恢复失败比同步失败更严重:明确标出,不能当作普通失败吞掉。
outcome.State = "rollback_failed"
outcome.Rollback = "恢复失败:" + restoreErr.Error()
recorder.Stage(ctx, "rollback", "failed", outcome.Rollback)
return outcome
}
outcome.State = "rolled_back"
outcome.Rollback = "已恢复到预备份 " + outcome.Backup.ID
recorder.Stage(ctx, "rollback", "succeeded", outcome.Rollback)
return outcome
}