7b8cc0384b
build / build (push) Successful in 1m19s
为什么:同步入口此前只会拒绝;授权、预备份、四类写入、验证与失败恢复都没有代码。
本轮把编排与授权实现出来,真实生产执行仍按授权闸口关闭。
- internal/libraryrelease:预备份 → 数据库/资源/索引/Wiki → 验证 → 失败恢复;
授权过期/目标不符/快照不符/参数变化在动生产前拒绝;恢复失败单独上报。
- 迁移 000067 library_release_authorizations(目标+快照+参数摘要+有效期,可撤销)。
- POST/GET /api/v1/library/authorizations 与 /{id}/revoke,仅管理员签发,5–1440 分钟。
- worker library.sync 接编排:先闸口再授权,阶段落库,只有编排成功才标成功。
- 生产目标适配器未配置时显式失败(不返回零值状态),预备份存储同。
- overview 返回授权状态,页面"生产保护与恢复"显示签发人与有效期。
- 验收矩阵区分"已实现·隔离测试通过"与"真实执行未授权"。
206 lines
7.6 KiB
Go
206 lines
7.6 KiB
Go
// 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"`
|
||
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
|
||
}
|