Files
knowledge-governance/cmd/worker/library_finish.go
T
姚章浩 780ab988c4
build / build (push) Successful in 1m20s
fix(worker): 历史快照恢复接管按作业身份与新授权判定
真实现场 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 本地档案跳过)。
2026-10-30 08:51:07 +08:00

237 lines
13 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 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)
}