Files
knowledge-governance/internal/libraryfreeze/window.go
T
姚章浩 0ef79846e8
build / build (push) Successful in 1m19s
fix(library): 后台静默必须在关入口之后证明,并在停写者后复核
原顺序先证明后台空、再关入口排空:排空期间还在服务的在途请求会派生新任务,
那一刻的空到停写者时已经失效,而 app 收到 SIGTERM 会 exit(1) 把任务腰斩。

现在固定为:关入口并排空 → 证明后台静默(连续为空 + 稳定窗口 + 任务指纹)→
停写入者 → 停完再复核(队列非空/指纹变化即判 background_truncated)。
scheduled/retry 自行产生任务或任务卡住时 fail closed;旧 journal 的
background_idle 布尔不再当证明;入口关到一半失败时恢复入口并保持维护。
2026-10-29 04:02:59 +08:00

565 lines
19 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 libraryfreeze
import (
"context"
"encoding/hex"
"errors"
"fmt"
"os"
"strings"
"time"
)
// Window 是一次维护窗口里"写目标"阶段的句柄。
//
// work 必须在第一笔目标写入之前调用 MarkContentRisk:它是一条持久证据,
// 记录"从这里开始目标内容可能已被改动"。进程在这之后死掉时,恢复器不会
// 自动把目标开放——半写目标只能由原作业接管或按预备份恢复。
type Window struct {
c *Coordinator
j *journal
}
func (w *Window) MarkContentRisk(ctx context.Context) error {
if w == nil || w.c == nil || w.j == nil {
return errors.New("invalid maintenance window")
}
if err := ctx.Err(); err != nil {
return err
}
if w.j.ContentRisk {
return nil
}
w.j.ContentRisk = true
return w.c.save(*w.j)
}
// SetBackupSnapshot 把"这次窗口的预备份身份"落盘。恢复只认它:
// 没有这份身份的窗口,之后既不能自动恢复,也不许被外部收尾。
func (w *Window) SetBackupSnapshot(ctx context.Context, snapshotID string) error {
if w == nil || w.c == nil || w.j == nil {
return errors.New("invalid maintenance window")
}
if err := ctx.Err(); err != nil {
return err
}
if !validDigest(snapshotID) {
return errors.New("invalid backup snapshot id")
}
if w.j.BackupSnapshotID != "" && w.j.BackupSnapshotID != snapshotID {
return errors.New("backup snapshot changed inside the same window")
}
w.j.BackupSnapshotID = snapshotID
return w.c.save(*w.j)
}
// Job 返回窗口所属作业 id(恢复器与调用方据此对账)。
func (w *Window) Job() string {
if w == nil || w.j == nil {
return ""
}
return w.j.Job
}
func (c *Coordinator) Run(ctx context.Context, job string, capture func(context.Context) (string, error)) (Result, error) {
return c.RunPrepared(ctx, job, func(context.Context) error { return nil }, capture)
}
// RunPrepared 是封存链路的入口:停止写入者 → 在窗口内取快照 → 恢复写入者。
// 它等价于 allowRestore 恒为 true 的 RunWindow。
func (c *Coordinator) RunPrepared(ctx context.Context, job string, prepare func(context.Context) error, capture func(context.Context) (string, error)) (Result, error) {
if capture == nil {
return Result{}, errors.New("invalid freeze request")
}
return c.RunWindow(ctx, job, prepare, func(ctx context.Context, _ *Window) (string, error) {
return capture(ctx)
}, func(error) bool { return true })
}
// RunWindow 是维护窗口的唯一实现:
//
// 关入口 + 停全部写入者 → 验证真的停了、在途真的排空了 → 跑 work
// → 恢复"原本在跑"的服务 → 验证入口回来
//
// allowRestore 在 work 失败后决定目标能否重新开放:返回 false 表示内容状态
// 未验证(半写)——此时服务保持停止、journal 保持非终态,崩溃恢复也不许
// 自动启动它们。同一个 job 可以接管未完成的窗口,别的 job 不行。
func (c *Coordinator) RunWindow(ctx context.Context, job string, prepare func(context.Context) error,
work func(context.Context, *Window) (string, error), allowRestore func(error) bool) (Result, error) {
if !validID(job) || work == nil || prepare == nil {
return Result{}, errors.New("invalid freeze request")
}
if allowRestore == nil {
allowRestore = func(error) bool { return true }
}
if err := ctx.Err(); err != nil {
return Result{}, err
}
lock, err := c.lock()
if err != nil {
return Result{}, err
}
defer unlock(lock)
// 实例级维护的入口必须由我们关:没有闸门就没有"入口已关"的证据,
// 后面拿什么证明后台静默都是空的。
if c.level == "instance" && c.gate == nil {
return Result{}, errors.New("实例级维护缺少入口闸门:不能证明入口已关闭")
}
previous, loadErr := c.load(job)
j := journal{}
switch {
case loadErr == nil && previous.State == "succeeded":
return previous.Result, nil
case loadErr == nil && (previous.State == "stopping" || previous.State == "held"):
// 接管:目标必须仍然停住。不重新"准备"、也不从零重来。
j = previous
if j.State == "held" && j.RestoreBlocked {
// 上一次窗口把内容判成半写:接管方必须自己重新证明,不许清掉风险。
j.RestoreBlocked = false
}
case loadErr == nil:
return previous.Result, errors.New("freeze request already exists; recovery or a new request is required")
case !errors.Is(loadErr, os.ErrNotExist):
return Result{}, loadErr
default:
if err = c.pending(); err != nil {
return Result{}, err
}
if err = prepare(ctx); err != nil {
return Result{}, err
}
if err = ctx.Err(); err != nil {
return Result{}, err
}
items, err := inventory(ctx, c.control)
if err != nil {
return Result{}, err
}
j = journal{Version: 1, Source: c.source, Job: job, Level: c.level, Ingress: c.ingress,
TargetFingerprint: c.fingerprint, Result: Result{State: "stopping"}, StartedAt: time.Now().UTC()}
for _, s := range items {
if s.Running && !s.Healthy {
return Result{}, errors.New("test writer is not ready")
}
j.Services = append(j.Services, serviceRecord{Service: s})
}
if err = c.save(j); err != nil {
return Result{}, err
}
}
// 顺序不能换:先把外部任务的生产入口关掉并排空,再证明后台静默,最后才停写入者。
// 先证明静默再关入口是错的——排空期间还在跑的在途请求随时会派生新的异步任务,
// 那一刻的"空"到停写者时早就失效了;而 app 一旦 SIGTERM 就 exit(1),会把任务腰斩。
if c.gate != nil && (j.Gate == nil || !j.Gate.Drained) {
evidence, gateErr := c.gate.CloseIngress(ctx)
if gateErr != nil {
return c.abandonWindow(ctx, &j, fmt.Errorf("关闭目标入口失败:%w", gateErr), "gate_failed")
}
if !evidence.Closed || !evidence.Drained {
return c.abandonWindow(ctx, &j, errors.New("目标入口未确认排空(仍有在途请求)"), "gate_not_drained")
}
j.Gate = &evidence
if err = c.save(j); err != nil {
return Result{}, err
}
}
// 入口关了才谈得上"稳定切点":连续为空 + 跨过稳定窗口 + 拿得到任务指纹。
proof, quietErr := c.awaitBackgroundQuiet(ctx, &j)
if quietErr != nil {
return c.abandonWindow(ctx, &j, quietErr, "background_busy")
}
// 停写入者:任何一步不成立都不许往下写。
if stopErr := c.stopAll(ctx, &j); stopErr != nil {
return c.abandonWindow(ctx, &j, stopErr, "stop_failed")
}
if stopErr := c.stopped(ctx, j); stopErr != nil {
return c.abandonWindow(ctx, &j, stopErr, "isolation_unverified")
}
if stopErr := c.verifyDrain(ctx, &j); stopErr != nil {
return c.abandonWindow(ctx, &j, stopErr, "drain_unverified")
}
// 停完再复核一次:入队/派发可能在"证明静默"和"停写者"之间发生。
// 队列仍有任务说明有任务被截断——这比同步失败严重,按切点不一致处理,绝不往下写。
if stopErr := c.verifyBackgroundAfterStop(ctx, &j, proof); stopErr != nil {
return c.abandonWindow(ctx, &j, stopErr, "background_truncated")
}
if c.ingressClosed != nil {
if stopErr := c.ingressClosed(ctx); stopErr != nil {
return c.abandonWindow(ctx, &j, fmt.Errorf("目标入口仍然可用:%w", stopErr), "ingress_open")
}
j.IngressClosed = true
}
j.State = "held"
if err = c.save(j); err != nil {
return Result{}, err
}
w := &Window{c: c, j: &j}
// work 里 panic 等同于失败:目标可能已被改过,必须走恢复分支,不能让
// 进程直接崩掉把写入者留在停止状态。
snapshotID, workErr := func() (id string, err error) {
defer func() {
if recover() != nil {
id, err = "", errors.New("维护窗口内的作业 panic")
}
}()
return work(ctx, w)
}()
if workErr != nil {
return c.closeWindow(ctx, &j, workErr, allowRestore(workErr), "")
}
if err = ctx.Err(); err != nil {
// 取消/超时发生在窗口内:内容状态未知,但写入者必须恢复(旧行为一致),
// 由上层把作业判失败;不把"没验证完"说成成功。
return c.closeWindow(ctx, &j, err, true, "")
}
if snapshotID != "" {
if !validDigest(snapshotID) {
return c.closeWindow(ctx, &j, errors.New("invalid candidate snapshot digest"), true, "")
}
}
// work 报成功但写入者已经不在停住状态 = 隔离被破坏,不能登记成功。
if err = c.stopped(ctx, j); err != nil {
return c.closeWindow(ctx, &j, err, true, "")
}
return c.closeWindow(ctx, &j, nil, true, snapshotID)
}
// abandonWindow:在"还没写目标"的阶段失败——内容没被改过,可以安全恢复并结案。
func (c *Coordinator) abandonWindow(ctx context.Context, j *journal, cause error, code string) (Result, error) {
recoveryCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Minute)
defer cancel()
if restoreErr := c.restore(recoveryCtx, j); restoreErr != nil {
// 恢复不了就保持非终态:下一次恢复/接管还要处理它。
j.Code = code
_ = c.save(*j)
return j.Result, errors.Join(cause, restoreErr)
}
// 入口必须真的回来了才算"安全放弃":服务在跑但入口关着,等于把目标静默下线。
if c.ingressReady != nil {
if readyErr := c.ingressReady(recoveryCtx); readyErr != nil {
j.Code = code
j.State = "held"
_ = c.save(*j)
return j.Result, errors.Join(cause, fmt.Errorf("目标入口没有恢复:%w", readyErr))
}
}
ended := time.Now().UTC()
j.State = "failed"
j.Code = code
j.FinishedAt = &ended
if err := c.save(*j); err != nil {
return j.Result, errors.Join(cause, err)
}
return j.Result, cause
}
// closeWindow:写完之后的收尾。allowRestore=false(半写且回滚失败)时
// 服务保持停止、journal 保持非终态,返回的是"目标仍在维护"这个结论。
func (c *Coordinator) closeWindow(ctx context.Context, j *journal, cause error, allowRestore bool, snapshotID string) (Result, error) {
if snapshotID != "" {
j.SnapshotID = snapshotID
}
if !allowRestore {
j.State = "held"
j.RestoreBlocked = true
if cause == nil {
cause = errors.New("目标内容状态未验证")
}
j.Code = "restore_blocked"
if err := c.save(*j); err != nil {
return j.Result, errors.Join(cause, err)
}
return j.Result, cause
}
recoveryCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Minute)
defer cancel()
if restoreErr := c.restore(recoveryCtx, j); restoreErr != nil {
// 服务没能恢复 = 入口没回来 = 目标仍在维护,不许报成功。
j.State = "held"
j.Code = "restore_failed"
if saveErr := c.save(*j); saveErr != nil {
return j.Result, errors.Join(cause, restoreErr, saveErr)
}
return j.Result, errors.Join(cause, restoreErr)
}
if c.ingressReady != nil {
if readyErr := c.ingressReady(recoveryCtx); readyErr != nil {
j.State = "held"
j.Code = "ingress_unverified"
_ = c.save(*j)
return j.Result, errors.Join(cause, fmt.Errorf("目标入口没有恢复:%w", readyErr))
}
}
ended := time.Now().UTC()
j.FinishedAt = &ended
if cause != nil {
j.State = "failed"
if j.Code == "" {
j.Code = "work_failed"
}
} else {
j.State = "succeeded"
j.Code = ""
}
if err := c.save(*j); err != nil {
return j.Result, errors.Join(cause, err)
}
return j.Result, cause
}
// awaitBackgroundQuiet 证明"入口关掉之后后台一直没任务",返回可复核证据。
//
// 关键点:
// - 必须在入口关闭且排空之后调用。排空期间在途请求还会派生任务,
// 在关入口之前取样得到的 0 到停写者时可能已失效。
// - 只认"连续为空 + 跨过稳定窗口 + 两次指纹一致",单次瞬时 0 不算证明。
// - 队列一直不空(scheduled/retry 自己冒任务、任务卡住)就失败:宁可不开窗口,
// 也不能把正在跑的任务留给 SIGTERM 腰斩。
func (c *Coordinator) awaitBackgroundQuiet(ctx context.Context, j *journal) (*QuiesceProof, error) {
if c.quiescer == nil {
if c.level == "instance" {
return nil, errors.New("没有后台任务静默检查:不能证明停写者时后台任务已结束")
}
return nil, nil
}
stable := c.quiesceStable
if stable <= 0 {
stable = 1500 * time.Millisecond
}
stall := c.quiesceStall
if stall <= 0 {
stall = 30 * time.Second
}
wait := c.quiesceWait
if wait <= 0 {
wait = 2 * time.Minute
}
st, stableOK := c.quiescer.(StableQuiescer)
if !stableOK {
if c.level == "instance" {
return nil, errors.New("后台任务检查不给任务集合指纹:无法证明稳定切点(scheduled/retry 可能自行产生)")
}
return nil, nil
}
if j.Gate == nil || !j.Gate.Drained {
return nil, errors.New("必须先关闭并排空入口,再证明后台静默")
}
started := time.Now().UTC()
deadline := started.Add(wait)
var anchor QuiesceSnapshot
var anchorAt time.Time
var lastDetail string
samples := 0
var busyDigest string
var busySince time.Time
for {
snapshot, err := st.Snapshot(ctx)
if err != nil {
return nil, fmt.Errorf("读不到后台任务状态:%w", err)
}
samples++
lastDetail = snapshot.Detail
now := time.Now().UTC()
if snapshot.Depth == 0 && snapshot.PendingOps == 0 && snapshot.Unsettled == 0 {
if anchorAt.IsZero() {
anchor, anchorAt = snapshot, now
} else if snapshot.Digest == anchor.Digest && now.Sub(anchorAt) >= stable {
proof := &QuiesceProof{
AfterIngress: started, Samples: samples, StableMS: now.Sub(anchorAt).Milliseconds(),
Depth: 0, PendingOps: 0, Unsettled: 0,
Digest: snapshot.Digest, Detail: snapshot.Detail, ProvenAt: now,
}
j.Quiesce = proof
j.BackgroundIdle = true
if err := c.save(*j); err != nil {
return nil, err
}
return proof, nil
}
} else {
anchor, anchorAt = QuiesceSnapshot{}, time.Time{}
if busyDigest != snapshot.Digest {
busyDigest, busySince = snapshot.Digest, now
} else if now.Sub(busySince) >= stall {
// 同一批任务长时间没有进展:被截断或需要外部处理,直接失败,不猜。
return nil, fmt.Errorf("后台任务没有进展(%s):先让它们结束再开窗口,否则会被 SIGTERM 切断", lastDetail)
}
}
if now.After(deadline) {
return nil, fmt.Errorf("后台任务仍在运行(%s):等它结束再开窗口,否则会被 SIGTERM 切断", lastDetail)
}
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(200 * time.Millisecond):
}
}
}
// verifyBackgroundAfterStop 复核"停写者那一刻没有任务在跑":
// 队列在停完之后仍为空、指纹不变,才算切点一致;否则说明有任务被截断。
func (c *Coordinator) verifyBackgroundAfterStop(ctx context.Context, j *journal, proof *QuiesceProof) error {
if c.quiescer == nil {
return nil
}
if proof == nil {
if c.level == "instance" {
return errors.New("没有后台静默证据:不能声称停写者时后台已空")
}
return nil
}
st, ok := c.quiescer.(StableQuiescer)
if !ok {
return nil
}
snapshot, err := st.Snapshot(ctx)
if err != nil {
return fmt.Errorf("停写者后读不到后台任务状态:%w", err)
}
if snapshot.Depth != 0 || snapshot.PendingOps != 0 || snapshot.Unsettled != 0 || snapshot.Digest != proof.Digest {
return fmt.Errorf("停写入者后后台任务集合变了(%s):切点不一致,按任务被截断处理", snapshot.Detail)
}
proof.PostStopDepth = snapshot.Depth
proof.PostStopDigest = snapshot.Digest
proof.PostStopAt = time.Now().UTC()
if err := c.save(*j); err != nil {
return err
}
return nil
}
// stopAll 只对"原本在跑"的服务发停止指令,每发一个都先落盘意图:
// 进程在停止过程中死掉时,磁盘上仍能看出"哪些服务被要求停过"。
func (c *Coordinator) stopAll(ctx context.Context, j *journal) error {
// 以"现在是否真的在跑"为准,而不是上次窗口留下的 StopRequested:
// 恢复阶段被人工拉起来的写入者必须再停一次,否则校验跑在半开的目标上。
items, err := inventory(ctx, c.control)
if err != nil {
return err
}
running := map[string]bool{}
for _, s := range items {
running[s.ID] = s.Running
}
var failures error
for i := range j.Services {
if !running[j.Services[i].ID] {
continue
}
if !j.Services[i].StopRequested {
j.Services[i].StopRequested = true
if err := c.save(*j); err != nil {
return err
}
}
if err := c.control.Stop(ctx, j.Services[i].ID); err != nil {
failures = errors.Join(failures, err)
break
}
}
return failures
}
// verifyDrain 用控制器报告的退出码判断"在途请求是否排空":
// 0 = 服务自己收尾退出;其它(143/137)= 被切断,不许当成排空。
// 声明了实例级维护时,拿不到退出码就是没有证据——按未排空处理。
func (c *Coordinator) verifyDrain(ctx context.Context, j *journal) error {
needed := 0
for _, s := range j.Services {
if s.Running && s.StopRequested {
needed++
}
}
if needed == 0 {
return nil
}
// 入口层已经证明"在途请求全部结束"时,写者的退出码只作为记录:
// 被代理的 WeKnora 收到 SIGTERM 会自己 exit(1)(upstream bug),
// 那不代表请求被切断——请求早在入口关闭时就已经跑完了。
gateDrained := j.Gate != nil && j.Gate.Closed && j.Gate.Drained
items, err := inventory(ctx, c.control)
if err != nil {
return err
}
actual := map[string]Service{}
for _, s := range items {
actual[s.ID] = s
}
verified := 0
for i := range j.Services {
s := &j.Services[i]
if !s.Running || !s.StopRequested {
continue
}
now, ok := actual[s.ID]
if !ok || now.Running {
return errors.New("test writer still running")
}
if now.ExitCode == nil {
if c.level == "instance" && !gateDrained {
return fmt.Errorf("无法证明 %s 的在途请求已排空(控制器没有退出码)", s.ID)
}
continue
}
s.ExitCode = now.ExitCode
if *now.ExitCode != 0 && !gateDrained {
return fmt.Errorf("写入者 %s 未优雅退出(exit=%d):在途请求没有完成排空", s.ID, *now.ExitCode)
}
verified++
}
j.DrainVerified = gateDrained || verified == needed
return nil
}
func validDigest(id string) bool {
decoded, err := hex.DecodeString(id)
return err == nil && len(decoded) == 32 && strings.ToLower(id) == id
}
// anyServiceRunning 判断这个窗口记录的写入者里是否还有在跑的。
func (c *Coordinator) anyServiceRunning(ctx context.Context, j journal) (bool, error) {
items, err := inventory(ctx, c.control)
if err != nil {
return false, err
}
running := map[string]bool{}
for _, s := range items {
running[s.ID] = s.Running
}
for _, s := range j.Services {
if running[s.ID] {
return true, nil
}
}
return false, nil
}
// checkBackgroundStuck 在"写入者已经停住"的前提下判断后台是否还有没跑完的任务:
// 这时候没人能消费队列,等下去没有意义,只能报出来交给外部处理。
func (c *Coordinator) checkBackgroundStuck(ctx context.Context) error {
if c.quiescer == nil {
return nil
}
st, ok := c.quiescer.(StableQuiescer)
if !ok {
if c.level == "instance" {
return errors.New("后台任务检查不给任务集合指纹:无法判断是否有被截断的任务")
}
return nil
}
snapshot, err := st.Snapshot(ctx)
if err != nil {
return fmt.Errorf("读不到后台任务状态:%w", err)
}
if snapshot.Depth == 0 && snapshot.PendingOps == 0 && snapshot.Unsettled == 0 {
return nil
}
return fmt.Errorf("写入者已停但后台仍有任务(%s):这些任务在上次中断时被截断,需要先把服务起来(入口保持关闭)让它们跑完,再重试恢复", snapshot.Detail)
}