// 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) } // BackupObserver 让调用方在预备份完成时立刻持久化快照身份: // worker 被杀后重启必须能接管这份预备份,而不是重新备份覆盖它。 type BackupObserver interface { // 必须返回错误:预备份引用没能持久化时,worker 被杀就没有恢复基线, // 这种情况下一个字节都不许写目标。调用方据此直接失败。 BackupPrepared(ctx context.Context, backup BackupRef) error } // FinalizeStages 是"写入完成之后的收尾":先登记权威版本,再把作业标成功。 // 收尾失败不能报告整体成功,否则版本登记与作业状态会分叉。 func FinalizeStages() []string { return []string{"finalize"} } 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"` Recovery string `json:"recovery,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 if observer, ok := recorder.(BackupObserver); ok { if err := observer.BackupPrepared(ctx, backup); err != nil { // 硬门禁:持久化失败 = 没有可恢复基线 = 绝不写目标。 outcome.State = "failed" outcome.Error = "预备份已生成但引用无法持久化,未对生产执行任何写入:" + err.Error() outcome.Recovery = "预备份 " + backup.SnapshotID + " 已落盘,先修复治理库再重试" recorder.Stage(ctx, "prebackup", "failed", outcome.Error) return outcome } } 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 }