780ab988c4
build / build (push) Successful in 1m20s
真实现场 2026-10-30T00:19Z:新恢复作业恢复历史快照 fc595511(已被 0d982f76 顶替),写入 database 后被 SIGKILL;重启接管时 classifyTakeover 只要看到 该快照有 SupersededAt 就判 superseded,没有判这行历史版本属于哪个作业, 把历史那次发布被顶替当成这次作业过期,作业 failed/prebackup,而恢复文案 又写"无需恢复",目标半写且维护锁未释放。 修法:被顶替分支先分清归属——本作业 finalize 成功或版本行属于本作业 ⇒ 仍 拒绝;历史行属于别的作业时,仅当本次是 restore、授权签发于顶替之后、scope 与 instance 两把锁仍由本作业独占且指纹一致、预备份登记属于本作业且清单字节 仍等于摘要,才按 fresh 继续重跑整条链路。任一证据缺失/读不到仍拒绝。 同时把续作早退统一走 failLibraryJobOrTakeover:有持久化预备份时保留 needs_restore 并点名 backup,不再写"无需恢复"。 验证: - 先写失败回归(历史行+新授权 ⇒ 期望 fresh,实得 superseded),修后绿; - 真实 PostgreSQL 正负例:授权撤销/实例锁释放/预备份归属被改/清单字节被改 均回到 superseded;续作早退保留备份与 needs_restore; - 本地 make verify 16 项必需检查全绿(identity 本地档案跳过)。
237 lines
13 KiB
Go
237 lines
13 KiB
Go
package main
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"fmt"
|
||
"time"
|
||
|
||
"knowledge-governance/internal/governance"
|
||
postgresstore "knowledge-governance/internal/platform/postgres"
|
||
)
|
||
|
||
// libraryMaintenanceStore 是"成功收尾"用到的存储能力。抽成接口是为了能在测试里
|
||
// 让某一步失败,验证"没全部完成就不许暴露成功"。
|
||
type libraryMaintenanceStore interface {
|
||
SetInstanceMaintenanceIngress(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error
|
||
SetLibraryMaintenanceIngress(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error
|
||
UpdateInstanceMaintenanceState(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error
|
||
UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error
|
||
ReleaseInstanceMaintenance(ctx context.Context, instance, ownerJobID string, now time.Time) error
|
||
ReleaseLibraryMaintenance(ctx context.Context, scope, ownerJobID string, now time.Time) error
|
||
AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error
|
||
}
|
||
|
||
// releaseWindowLocks 是唯一释放路径。
|
||
//
|
||
// 顺序刻意是"scope 先、instance 后":instance 行是跨 scope 的互斥来源,最后放它
|
||
// 才能保证任何新作业在全部记录落定之前都进不来。每一步的错误都必须向上暴露——
|
||
// 只丢日志会让"锁其实没放"这件事变成页面上的成功。
|
||
func releaseWindowLocks(ctx context.Context, store libraryMaintenanceStore, instance, scope, jobID, note string, now time.Time) error {
|
||
if err := store.SetLibraryMaintenanceIngress(ctx, scope, jobID, "open", note, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("记录入口已开放失败(scope):%w", err)
|
||
}
|
||
if err := store.SetInstanceMaintenanceIngress(ctx, instance, jobID, "open", note, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("记录入口已开放失败(instance):%w", err)
|
||
}
|
||
if err := store.UpdateLibraryMaintenanceState(ctx, scope, jobID, "verified", note, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("维护状态写入失败(scope):%w", err)
|
||
}
|
||
if err := store.ReleaseLibraryMaintenance(ctx, scope, jobID, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("维护占用释放失败(scope):%w", err)
|
||
}
|
||
if err := store.UpdateInstanceMaintenanceState(ctx, instance, jobID, "verified", note, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("维护状态写入失败(instance):%w", err)
|
||
}
|
||
if err := store.ReleaseInstanceMaintenance(ctx, instance, jobID, now); !releasedOrNil(err) {
|
||
return fmt.Errorf("实例占用释放失败(instance):%w", err)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// healthChecker 是"目标写入者与入口是否真的恢复健康"的判定口(测试可注入失败)。
|
||
type healthChecker interface {
|
||
VerifyRunning(ctx context.Context) error
|
||
}
|
||
|
||
// successBoundary 描述一次"内容已通过验证与版本登记,但还没到可以对外报成功"的作业。
|
||
type successBoundary struct {
|
||
Ready bool
|
||
Backup string
|
||
Target string
|
||
FinishedAt time.Time
|
||
}
|
||
|
||
// finishLibrarySuccess 是唯一的成功收尾入口:只有以下全部成立才暴露 succeeded——
|
||
// 目标服务健康、入口开放、scope 与 instance 两把维护锁都释放完成、终态写入成功。
|
||
//
|
||
// 为什么不能先标成功再释放:恢复/开入口/放锁都可能失败,先写 succeeded 会让外部
|
||
// (页面、API、重启后的接管逻辑)看到一条"成功了但目标仍在维护"的作业;而
|
||
// InterruptedLibraryJobs 只接管非终态,终态作业不会再被接管,锁就永远挂着。
|
||
func finishLibrarySuccess(ctx context.Context, store libraryMaintenanceStore, health healthChecker,
|
||
instance, scope, jobID string, boundary successBoundary) error {
|
||
// 释放与终态写入必须能在 ctx 取消后继续:停机不该留下"锁放了但作业还在跑"或
|
||
// 反过来"作业成功了锁还挂着"的任一半成品。
|
||
bounded, cancel := context.WithTimeout(context.WithoutCancel(ctx), 60*time.Second)
|
||
defer cancel()
|
||
|
||
holdForRepair := func(reason string) error {
|
||
note := "内容已验证,但收尾未完成,目标保持维护:" + reason
|
||
_ = store.UpdateLibraryMaintenanceState(bounded, scope, jobID, "needs_restore", note, time.Now().UTC())
|
||
_ = store.UpdateInstanceMaintenanceState(bounded, instance, jobID, "needs_restore", note, time.Now().UTC())
|
||
_ = store.AdvanceLibraryJob(bounded, jobID, governance.LibraryJobFailed, "finalize", note,
|
||
"生产内容已写入并校验;维护保持,按预备份或人工核验后再开放", boundary.Backup, boundary.Target, time.Now().UTC())
|
||
return errors.New(note)
|
||
}
|
||
|
||
if err := health.VerifyRunning(bounded); err != nil {
|
||
return holdForRepair("目标服务或入口未恢复健康:" + err.Error())
|
||
}
|
||
if err := releaseWindowLocks(bounded, store, instance, scope, jobID,
|
||
"写入与校验完成,目标已按原运行状态恢复", time.Now().UTC()); err != nil {
|
||
return holdForRepair(err.Error())
|
||
}
|
||
finishedAt := time.Now().UTC()
|
||
if err := store.AdvanceLibraryJob(bounded, jobID, governance.LibraryJobSucceeded, "finalize", "", "",
|
||
boundary.Backup, boundary.Target, finishedAt); err != nil {
|
||
// 锁已释放但终态没写下去:作业保持非终态,重启后会被接管(接管走
|
||
// finalize-only,只复核与登记,不重写生产)。
|
||
return fmt.Errorf("维护已释放但作业终态写入失败(等待接管):%w", err)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// takeoverKind 是接管时"这个作业走到哪一步"的分类。
|
||
//
|
||
// 四类必须分开:把"版本查不到"当成"没有收尾证据",就会把只差收尾的作业重新写一遍
|
||
// 目标;把"曾被顶替"当成正常重放,就会用旧快照覆盖更新的生产版本。
|
||
type takeoverKind string
|
||
|
||
const (
|
||
// takeoverFresh:没有任何收尾证据,按正常流程(有预备份则复用,写前仍备份)。
|
||
takeoverFresh takeoverKind = "fresh"
|
||
// takeoverPendingFinal:内容与版本已落定,只差收尾(只复核与登记,不重写)。
|
||
takeoverPendingFinal takeoverKind = "pending_final"
|
||
// takeoverSuperseded:本快照曾经生效、后来被别的快照顶替,不得自动覆盖。
|
||
takeoverSuperseded takeoverKind = "superseded"
|
||
// takeoverForeignEffective:当前生效的确实是本作业的目标快照,但那一行登记属于
|
||
// **别的作业**。快照相同不等于本作业写过:2026-10-29 的真实现场就是这样——
|
||
// 本作业只写完了第一个写入阶段(database),resources/index/wiki/verify 仍是
|
||
// pending,却因为"当前生效快照 == 我的目标快照"被当成只差收尾,直接登记成功,
|
||
// 并把生效版本归属改写成自己(同一 (scope, 快照) 的版本行是 upsert)。
|
||
takeoverForeignEffective takeoverKind = "foreign_effective"
|
||
// takeoverUnknown:版本状态读不到且没有阶段证据,属"未知",不得写入。
|
||
takeoverUnknown takeoverKind = "unknown"
|
||
)
|
||
|
||
// effectiveOwnedBy 回答"这一行生效登记是不是本作业为这个快照登记的"。
|
||
//
|
||
// 快照相等的判定共用于接管与基线两条链路(同一含义只准有一份实现):这两个
|
||
// 调用方都必须绑作业身份,否则"别的作业把同一个快照发布上线"会被误认成
|
||
// "本作业已经完成"。
|
||
func effectiveOwnedBy(version governance.LibraryVersion, jobID, snapshotID string) bool {
|
||
return jobID != "" && snapshotID != "" && version.SourceJobID == jobID && version.SnapshotID == snapshotID
|
||
}
|
||
|
||
// takeoverResumeFacts 是一次"接管继续"能否成立的外部约束。
|
||
//
|
||
// 一行生效版本被顶替只说明"那个快照曾经上线、后来被更新版本替换",并不说明
|
||
// **当前这个作业**已经过期。要把"新恢复历史快照"与"本作业完成后的旧版本"分开,
|
||
// 必须再证明三件事:授权是顶替之后新签的、维护窗口仍由本作业独占、预备份基线
|
||
// 还是本作业登记的那一份且字节未被改动。
|
||
type takeoverResumeFacts struct {
|
||
AuthorizedAt time.Time
|
||
MaintenanceOwned bool
|
||
BaselineRecorded bool
|
||
BaselineVerified bool
|
||
}
|
||
|
||
// authorizedRestoreAfterSupersede 回答"这是不是一次在顶替之后才获授权的恢复"。
|
||
// 只认恢复:同步没有"恢复历史版本"这个业务,不能借这条分支绕开覆盖保护。
|
||
func (r takeoverResumeFacts) authorizedRestoreAfterSupersede(job governance.LibraryJob, supersededAt time.Time) bool {
|
||
return job.Kind == governance.LibraryJobRestore && job.TargetSnapshotID != "" &&
|
||
!r.AuthorizedAt.IsZero() && r.AuthorizedAt.After(supersededAt) &&
|
||
r.MaintenanceOwned && r.BaselineRecorded && r.BaselineVerified
|
||
}
|
||
|
||
// classifyTakeover 只按证据分类:
|
||
// - finalize 阶段成功是独立证据(来自作业自己的阶段行),不因版本查询失败而丢弃;
|
||
// - 本快照存在 released/被顶替的版本 ⇒ superseded;例外是该行属于**别的作业**、
|
||
// 且本次是顶替之后新授权的恢复并仍独占维护窗口、基线未变 ⇒ fresh(恢复历史
|
||
// 快照是正常业务,历史那次发布被顶替不等于本作业过期);
|
||
// - 本快照存在未被顶掉的生效版本,且归属本作业 ⇒ pending_final;归属别的作业 ⇒
|
||
// foreign_effective(同快照不算本作业的完成证据);
|
||
// - 查询失败且无阶段证据 ⇒ unknown(可重试,不当成没有证据)。
|
||
//
|
||
// 事实来自两个精确查询(LibraryCurrentVersion / LibraryVersionOfSnapshot),**不是**
|
||
// "最近 N 条再在内存里筛":窗口一满,已生效的快照会被判成"没有证据",接管就会把
|
||
// 已经上线的内容重写一遍。
|
||
func classifyTakeover(job governance.LibraryJob, facts libraryVersionFacts, resume takeoverResumeFacts) takeoverKind {
|
||
finalized := false
|
||
for _, stage := range job.Stages {
|
||
if stage.Stage == "finalize" && stage.State == "succeeded" {
|
||
finalized = true
|
||
}
|
||
}
|
||
if facts.Err != nil && !finalized {
|
||
return takeoverUnknown
|
||
}
|
||
if facts.Err == nil {
|
||
// 本快照登记过生效版本:被顶替过就绝不能用它覆盖更新的生产版本。
|
||
if facts.HasSnapshot && facts.Snapshot.SupersededAt != nil {
|
||
// 台账自相矛盾(这一行说已顶替,当前生效的却还是它):状态不可判定。
|
||
if facts.HasCurrent && facts.Current.SnapshotID == job.TargetSnapshotID {
|
||
return takeoverUnknown
|
||
}
|
||
// 连"当前生效是哪一份"都读不到:无法证明生产上还有更新版本可保护,
|
||
// 也无法证明这次续写落在哪个基线上,一律拒绝。
|
||
if !facts.HasCurrent {
|
||
return takeoverSuperseded
|
||
}
|
||
// 本作业自己完成过(finalize 阶段成功,或这一行生效登记就是本作业写的):
|
||
// 生产已被后续版本替换,再写回旧快照就是覆盖更新的生产,必须拒绝。
|
||
if finalized || effectiveOwnedBy(facts.Snapshot, job.ID, job.TargetSnapshotID) {
|
||
return takeoverSuperseded
|
||
}
|
||
// 这一行属于**别的作业**:它说明的是那次历史发布被顶替,不是本作业过期。
|
||
// 新恢复对该历史快照有顶替之后的独立授权、仍独占本次维护窗口、预备份
|
||
// 基线未变时,恢复历史快照是正常业务,按 fresh 重跑整条写入链路
|
||
// (不能按 pending_final:内容还没写完)。
|
||
if resume.authorizedRestoreAfterSupersede(job, *facts.Snapshot.SupersededAt) {
|
||
return takeoverFresh
|
||
}
|
||
return takeoverSuperseded
|
||
}
|
||
if facts.HasSnapshot {
|
||
// 未顶替 ⇒ 必须就是当前生效的那一行;不是的话台账不一致,不许挑一条继续写。
|
||
if !facts.HasCurrent || facts.Current.SnapshotID != job.TargetSnapshotID {
|
||
return takeoverUnknown
|
||
}
|
||
if !finalized && !effectiveOwnedBy(facts.Snapshot, job.ID, job.TargetSnapshotID) {
|
||
return takeoverForeignEffective
|
||
}
|
||
return takeoverPendingFinal
|
||
}
|
||
// 本快照没有自己的生效登记,但当前生效的正是它:内容确实已经在生产上。
|
||
// 归属必须也是本作业,否则只能说明别的作业发布过同一快照。
|
||
if facts.HasCurrent && facts.Current.SnapshotID == job.TargetSnapshotID {
|
||
if !finalized && !effectiveOwnedBy(facts.Current, job.ID, job.TargetSnapshotID) {
|
||
return takeoverForeignEffective
|
||
}
|
||
return takeoverPendingFinal
|
||
}
|
||
}
|
||
if finalized {
|
||
return takeoverPendingFinal
|
||
}
|
||
return takeoverFresh
|
||
}
|
||
|
||
var _ libraryMaintenanceStore = (*postgresstore.Store)(nil)
|
||
|
||
// releasedOrNil:这一行已经由本作业释放过,说明该步在上一次尝试里已经完成。
|
||
// 部分成功后重试幂等靠它——否则"scope 放了、instance 没放"的作业永远重试不下去。
|
||
func releasedOrNil(err error) bool {
|
||
return err == nil || errors.Is(err, postgresstore.ErrMaintenanceReleased)
|
||
}
|