Files
knowledge-governance/internal/libraryfreeze/window.go
T
姚章浩 98294b9583
build / build (push) Failing after 24s
fix(library): 统一执行身份、终态收尾、准入与数据身份
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
  · 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
    A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
  · 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
    upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
  · 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
    写业务状态、释放别人的维护锁;
  · 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
    服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
  · 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
    location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
  · 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。

what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
  · operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
    治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
  · 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
    心跳失租立刻取消 handler;
  · 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
    收尾;恢复成功登记 recovery 事件并推进 current;
  · worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
  · 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
    发布前核目标实时模型契约、容量门禁前置;
  · 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
  · 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。

how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
2026-10-30 16:14:54 +08:00

578 lines
20 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:在"还没写目标"的阶段失败——内容没被改过,可以安全恢复并结案。
//
// 判断"这个窗口有没有写过"必须读**持久** ContentRisk,而不是本进程是否调用过 Apply:
// 接管一个 held/stopping 窗口时本进程一笔都没写,但上一个进程可能已经写了一半。
// 那种情况下任何早退(入口关不掉、后台不静默、停写者失败)都只能保持关闭,
// 由恢复流程按预备份处理——把服务拉起来开门就是对外暴露半写内容(F03)。
func (c *Coordinator) abandonWindow(ctx context.Context, j *journal, cause error, code string) (Result, error) {
if j.ContentRisk {
j.State = "held"
j.RestoreBlocked = true
j.Code = code
saveErr := c.save(*j)
return j.Result, errors.Join(cause, errors.New(
"窗口内容有持久风险:目标保持维护,禁止重新开放;须按预备份恢复并逐类校验"), saveErr)
}
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)
}