From 2066bedbbe88ecba00b6862c38c65200ef4ba861 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Mon, 16 Nov 2026 22:58:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(library):=20=E7=BB=B4=E6=8A=A4=E7=AA=97?= =?UTF-8?q?=E5=8F=A3=E6=94=AF=E6=8C=81=E6=98=BE=E5=BC=8F=20no-gate=20?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=A0=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 0.9.0 测试栈没有入口闸门容器(只有 app/frontend/docreader/es/redis), 实例级维护窗口因此开不了。新增 LIBRARY_TARGET_INGRESS_MODE=none, 必须同时给 LIBRARY_NO_INGRESS_ACK=test-only 且不得声明半套闸门; 默认仍是 gate,行为与文案不变。 no-gate 下不调用任何闸门动作,改为要求 LIBRARY_TARGET_HEALTH_URL 并在 恢复后探测 200;维护记录、冻结日志与快照写入 ingress_mode/ingress_ack, gate 证据位置如实写“无闸门(测试模式)”,不伪装“入口已排空”。 --- CHANGELOG.md | 27 ++ cmd/api/main.go | 2 + cmd/libraryctl/main.go | 8 + cmd/libraryctl/no_gate_maintenance_test.go | 59 +++++ docs/library-capture.md | 8 + internal/appconfig/config.go | 81 ++++-- internal/httpapi/library_flow.go | 28 ++- internal/httpapi/server.go | 8 +- internal/libraryfreeze/freeze.go | 178 ++++++++++++- internal/libraryfreeze/journal_evidence.go | 6 + internal/libraryfreeze/no_gate_mode_test.go | 233 ++++++++++++++++++ internal/libraryfreeze/recovery.go | 9 +- internal/libraryfreeze/window.go | 154 ++++++++---- internal/librarymaintenance/env.go | 87 ++++++- .../librarymaintenance/no_gate_env_test.go | 88 +++++++ internal/librarymaintenance/target.go | 129 +++++++++- web/src/ReleaseTargets.tsx | 10 +- web/src/librarySnapshots.ts | 3 + 18 files changed, 1014 insertions(+), 104 deletions(-) create mode 100644 cmd/libraryctl/no_gate_maintenance_test.go create mode 100644 internal/libraryfreeze/no_gate_mode_test.go create mode 100644 internal/librarymaintenance/no_gate_env_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index d2fe654..8e78d16 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,32 @@ # Changelog +## 开发快照 0.1.381(维护窗口支持显式 no-gate 测试模式) + +### Added + +- 维护窗口新增显式入口形态 `LIBRARY_TARGET_INGRESS_MODE=gate|none`,缺省 `gate`: + 不写这个变量时行为与之前完全一致(缺任何闸门项照原文案拒绝)。`none` 只给 + "整栈没有入口闸门"的 0.9.0 测试栈,且必须同时给 `LIBRARY_NO_INGRESS_ACK=test-only` + (逐字符相等,空值/大小写/前后空格都不算确认,拒绝并点名该变量)。 +- `none` 下允许缺 `LIBRARY_TARGET_INGRESS_URL/SERVICE/DRAIN_FILE`,但 + `LIBRARY_TARGET_INSTANCE`、`LIBRARY_TARGET_REDIS_ADDR/PASSWORD/DB` 与新增的 + `LIBRARY_TARGET_HEALTH_URL` 仍必需;半套闸门声明(mode=none 又给了闸门项)直接拒绝。 + 窗口内一笔闸门动作都不做,开窗顺序为"停写者 → 队列排空 → 导出",恢复后重启写者并等 + 健康探针返回 200 才算目标回来;崩溃恢复同样不会假装开过闸门。 +- 维护记录/冻结日志写入 `ingress_mode`、`ingress_ack`,`gate` 证据位置写 + `{"mode":"none","reason":"stack has no ingress gate (test-only)"}`(不写 closed/drained=false + 这种"关了但没排空"的假象),健康探针地址与"已验证"另记;恢复/接管要求记录的入口形态与 + 当前配置一致,否则拒绝。接口/页面的入口状态在 `none` 下显示"无闸门(测试模式)"。 + +### Tests + +- `internal/libraryfreeze`:no-gate 窗口可开且记录含 `ingress_mode=none`、无 `gate_reopened`、 + 健康探针在恢复后被调用;写者退出码非 0(被代理服务 SIGTERM 的常态)不再被当作排空依据, + 排空由"写者全停 + 队列静默"证明;健康探针不过 → `held/ingress_unverified`。 + gate 模式的记录仍写 `ingress_mode=gate` 且保留 closed/drained 原形状。 +- `internal/librarymaintenance` / `cmd/libraryctl`:缺确认串、确认串含空格、未知形态都拒绝并点名; + `none` + 确认串时可解析且不再要求入口三项;gate 缺入口项仍是原拒绝行为。 + ## 开发快照 0.1.380(采集绑定允许对外库未配置) ### Fixed diff --git a/cmd/api/main.go b/cmd/api/main.go index 06bda53..701ef82 100644 --- a/cmd/api/main.go +++ b/cmd/api/main.go @@ -233,6 +233,8 @@ func run(ctx context.Context, getenv func(string) string) error { LibraryTargetWriters: config.LibraryTargetWriters, LibraryTargetIngressURL: config.LibraryTargetIngressURL, LibraryTargetIngressService: config.LibraryTargetIngressService, + LibraryTargetIngressMode: config.LibraryTargetIngressMode, + LibraryTargetHealthURL: config.LibraryTargetHealthURL, LibraryTargetDockerSocket: config.LibraryTargetDockerSocket, LibraryTargetJournalRoot: config.LibraryTargetJournalRoot, LibrarySourceInstance: config.SourceInstance(), diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go index acfe440..71d5ca9 100644 --- a/cmd/libraryctl/main.go +++ b/cmd/libraryctl/main.go @@ -623,6 +623,11 @@ func openFreeze(ctx context.Context, opts options) (*libraryfreeze.Coordinator, // // 入口/队列的声明与容器内 worker 共用同一组 LIBRARY_TARGET_* 名称, // 数据库/索引/桶则取自本次真实发现的源,避免"关的是 A 的门、读的是 B 的队列"。 +// +// LIBRARY_TARGET_INGRESS_MODE=none 只给整栈没有闸门的测试环境(0.9.0 测试栈): +// 必须同时给 LIBRARY_NO_INGRESS_ACK=test-only,窗口里一笔闸门动作都不做, +// 排空证据降为"写者全停 + 队列静默",恢复由 LIBRARY_TARGET_HEALTH_URL 的 200 证明。 +// 缺省仍是 gate:没有显式确认就照旧要求闸门。 func captureMaintenanceConfig(opts options, source sourceConfig, get func(string) string) (librarymaintenance.Config, error) { target, err := librarymaintenance.TargetFromEnv(get) if err != nil { @@ -642,9 +647,12 @@ func captureMaintenanceConfig(opts options, source sourceConfig, get func(string Writers: writers, NonWriters: nonWriters, DockerSocket: opts.dockerSocket, + IngressMode: target.Mode, + IngressAck: target.Ack, IngressURL: target.IngressURL, IngressService: target.IngressService, IngressDrainFile: target.IngressDrainFile, + HealthURL: target.HealthURL, Database: identity, Index: source.SearchIndex, Bucket: source.Object.Bucket, diff --git a/cmd/libraryctl/no_gate_maintenance_test.go b/cmd/libraryctl/no_gate_maintenance_test.go new file mode 100644 index 0000000..7dbbe8b --- /dev/null +++ b/cmd/libraryctl/no_gate_maintenance_test.go @@ -0,0 +1,59 @@ +package main + +import ( + "strings" + "testing" + + "knowledge-governance/internal/libraryfreeze" +) + +// noGateMaintenanceEnv 是 0.9.0 测试栈:没有闸门,用显式确认 + 健康探针代替。 +func noGateMaintenanceEnv() map[string]string { + env := maintenanceEnv() + delete(env, "LIBRARY_TARGET_INGRESS_URL") + delete(env, "LIBRARY_TARGET_INGRESS_SERVICE") + delete(env, "LIBRARY_TARGET_INGRESS_DRAIN_FILE") + env["LIBRARY_TARGET_INGRESS_MODE"] = libraryfreeze.IngressModeNone + env["LIBRARY_NO_INGRESS_ACK"] = libraryfreeze.NoIngressAck + env["LIBRARY_TARGET_HEALTH_URL"] = "http://127.0.0.1:18081/health" + return env +} + +func TestCaptureMaintenanceConfigNoGateWithAck(t *testing.T) { + env := noGateMaintenanceEnv() + config, err := captureMaintenanceConfig(captureOptions(), captureSource(), func(name string) string { return env[name] }) + if err != nil { + t.Fatalf("no-gate 声明被拒:%v", err) + } + if config.IngressMode != libraryfreeze.IngressModeNone || config.IngressAck != libraryfreeze.NoIngressAck { + t.Fatalf("入口形态没透传:%+v", config) + } + if config.IngressURL != "" || config.IngressService != "" || config.IngressDrainFile != "" { + t.Fatalf("no-gate 配置里出现了闸门项:%+v", config) + } + if config.HealthURL != "http://127.0.0.1:18081/health" || config.RedisAddr != "127.0.0.1:26379" { + t.Fatalf("健康探针/队列没透传:%+v", config) + } + // 目标身份仍取自本次真实发现的源:no-gate 只改证据形态,不改动的是谁。 + if config.Database != "127.0.0.1:25432/kgmaint_target" || config.Index != "kgmaint_1028a_chunks" { + t.Fatalf("目标身份不对:%+v", config) + } +} + +func TestCaptureMaintenanceConfigNoGateWithoutAckIsRefused(t *testing.T) { + env := noGateMaintenanceEnv() + delete(env, "LIBRARY_NO_INGRESS_ACK") + _, err := captureMaintenanceConfig(captureOptions(), captureSource(), func(name string) string { return env[name] }) + if err == nil || !strings.Contains(err.Error(), "LIBRARY_NO_INGRESS_ACK") { + t.Fatalf("没有显式确认却放过了 no-gate:%v", err) + } +} + +// no-gate 不得悄悄接受半套闸门声明:要么有闸门,要么明确没有。 +func TestCaptureMaintenanceConfigNoGateRejectsPartialGate(t *testing.T) { + env := noGateMaintenanceEnv() + env["LIBRARY_TARGET_INGRESS_SERVICE"] = "ingress" + if _, err := captureMaintenanceConfig(captureOptions(), captureSource(), func(name string) string { return env[name] }); err == nil { + t.Fatal("no-gate 与闸门服务同时存在却没有拒绝") + } +} diff --git a/docs/library-capture.md b/docs/library-capture.md index 5972a0d..3ee2579 100644 --- a/docs/library-capture.md +++ b/docs/library-capture.md @@ -56,8 +56,16 @@ LIBRARY_TARGET_INGRESS_URL 入口地址(恢复后要能 200) LIBRARY_TARGET_INGRESS_SERVICE Compose 里的入口闸门服务名 LIBRARY_TARGET_INGRESS_DRAIN_FILE 闸门写排空证据的宿主机文件 LIBRARY_TARGET_REDIS_ADDR/_PASSWORD/_DB 后台队列(asynq)地址 +LIBRARY_TARGET_INGRESS_MODE gate(缺省)或 none;none 只给没有闸门的测试栈 +LIBRARY_NO_INGRESS_ACK mode=none 时必须逐字符等于 test-only +LIBRARY_TARGET_HEALTH_URL mode=none 时的健康探针(恢复后必须 200) ``` +`none` 是显式降档,不是默认:整栈(如 0.9.0 测试栈)没有入口闸门时,`none` + 确认串 +才允许缺入口三项,窗口里不调用任何闸门动作,`gate` 证据位置写 +`{"mode":"none","reason":"stack has no ingress gate (test-only)"}`;恢复以 +`LIBRARY_TARGET_HEALTH_URL` 返回 200 为准。缺省 `gate` 的行为与文案不变。 + 另外 `-source-s3-endpoint ` 用来覆盖"源对象存储的访问入口":容器里写的 `MINIO_ENDPOINT` 往往是服务名(`langfuse-minio:9000`),封存跑在宿主机上时解析不到, 资源导出会失败(`read library resource`)。覆盖只换入口,桶与对象键不变;`status` diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go index ad256fd..990fbb6 100644 --- a/internal/appconfig/config.go +++ b/internal/appconfig/config.go @@ -3,6 +3,7 @@ package appconfig import ( "errors" "fmt" + "net/url" "path/filepath" "strconv" "strings" @@ -129,6 +130,11 @@ type Config struct { // 入口闸门:关入口与排空在它身上做(被代理服务自己不排空)。 LibraryTargetIngressService string LibraryTargetIngressDrainFile string + // 入口形态:gate(默认)或 none。none 只给整栈没有入口闸门的测试环境用, + // 必须同时给 LibraryTargetNoIngressAck,且证据等级降一档并如实记录。 + LibraryTargetIngressMode string + LibraryTargetNoIngressAck string + LibraryTargetHealthURL string // 后台静默检查:目标队列 + 目标库(HTTP 排空不等于后台任务排空)。 LibraryTargetRedisAddr string LibraryTargetRedisPassword string @@ -247,19 +253,23 @@ func Load(getenv func(string) string) (Config, error) { LibraryTargetIngressURL: strings.TrimSpace(getenv("LIBRARY_TARGET_INGRESS_URL")), LibraryTargetIngressService: strings.TrimSpace(getenv("LIBRARY_TARGET_INGRESS_SERVICE")), LibraryTargetIngressDrainFile: strings.TrimSpace(getenv("LIBRARY_TARGET_INGRESS_DRAIN_FILE")), - LibraryTargetRedisAddr: strings.TrimSpace(getenv("LIBRARY_TARGET_REDIS_ADDR")), - LibraryTargetRedisPassword: strings.TrimSpace(getenv("LIBRARY_TARGET_REDIS_PASSWORD")), - LibraryTargetRedisDB: valueOrDefaultInt(getenv("LIBRARY_TARGET_REDIS_DB"), 0), - LibraryTargetJournalRoot: strings.TrimSpace(getenv("LIBRARY_TARGET_JOURNAL_ROOT")), - LibraryEmbeddingModel: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_EMBEDDING_MODEL")), "text-embedding-v4"), - LibraryEmbeddingDimension: embeddingDimension, - LibraryCapacityBudgetBytes: capacityBudget, - LibraryRetentionVersions: retentionVersions, - LibraryRetentionDays: retentionDays, - LibraryExecutorStatusMaxAge: 2 * time.Minute, - VersionHistoryLinkOrigin: strings.TrimSpace(getenv("VERSION_HISTORY_LINK_ORIGIN")), - VersionHistoryHTTPTimeout: 15 * time.Second, - VersionHistoryMaxPages: valueOrDefaultInt(getenv("VERSION_HISTORY_MAX_PAGES"), 200), + LibraryTargetIngressMode: strings.TrimSpace(getenv("LIBRARY_TARGET_INGRESS_MODE")), + // 确认串不 Trim:必须逐字符相等,多一个空格都算没确认。 + LibraryTargetNoIngressAck: getenv("LIBRARY_NO_INGRESS_ACK"), + LibraryTargetHealthURL: strings.TrimSpace(getenv("LIBRARY_TARGET_HEALTH_URL")), + LibraryTargetRedisAddr: strings.TrimSpace(getenv("LIBRARY_TARGET_REDIS_ADDR")), + LibraryTargetRedisPassword: strings.TrimSpace(getenv("LIBRARY_TARGET_REDIS_PASSWORD")), + LibraryTargetRedisDB: valueOrDefaultInt(getenv("LIBRARY_TARGET_REDIS_DB"), 0), + LibraryTargetJournalRoot: strings.TrimSpace(getenv("LIBRARY_TARGET_JOURNAL_ROOT")), + LibraryEmbeddingModel: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_EMBEDDING_MODEL")), "text-embedding-v4"), + LibraryEmbeddingDimension: embeddingDimension, + LibraryCapacityBudgetBytes: capacityBudget, + LibraryRetentionVersions: retentionVersions, + LibraryRetentionDays: retentionDays, + LibraryExecutorStatusMaxAge: 2 * time.Minute, + VersionHistoryLinkOrigin: strings.TrimSpace(getenv("VERSION_HISTORY_LINK_ORIGIN")), + VersionHistoryHTTPTimeout: 15 * time.Second, + VersionHistoryMaxPages: valueOrDefaultInt(getenv("VERSION_HISTORY_MAX_PAGES"), 200), } if config.DatabaseURL == "" { return Config{}, errors.New("DATABASE_URL is required") @@ -387,9 +397,35 @@ func Load(getenv func(string) string) (Config, error) { if config.LibraryAgentSocket != "" && !filepath.IsAbs(config.LibraryAgentSocket) { return Config{}, errors.New("LIBRARY_AGENT_SOCKET 必须是绝对路径(unix socket 由主机侧 agent 持有)") } + // 入口形态:缺省 gate,行为与之前完全一致。none 只给整栈没有入口闸门的 + // 测试环境用,必须显式确认;确认串逐字符相等,多一个空格都算没确认。 + if config.LibraryTargetIngressMode == "" { + config.LibraryTargetIngressMode = "gate" + } + switch config.LibraryTargetIngressMode { + case "gate", "none": + default: + return Config{}, fmt.Errorf("LIBRARY_TARGET_INGRESS_MODE 无效(%q):只能是 gate 或 none", + config.LibraryTargetIngressMode) + } + noGate := config.LibraryTargetIngressMode == "none" + if noGate && config.LibraryTargetNoIngressAck != "test-only" { + return Config{}, errors.New("no-gate 维护必须显式确认:LIBRARY_NO_INGRESS_ACK 必须逐字符等于 test-only,拒绝启动") + } + if !noGate && config.LibraryTargetNoIngressAck != "" { + return Config{}, errors.New("LIBRARY_NO_INGRESS_ACK 只在 LIBRARY_TARGET_INGRESS_MODE=none 下有效") + } + if config.LibraryTargetHealthURL != "" { + parsed, err := url.Parse(config.LibraryTargetHealthURL) + if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || + parsed.Host == "" || parsed.User != nil { + return Config{}, errors.New("LIBRARY_TARGET_HEALTH_URL 必须是 http(s) 地址且不带凭据") + } + } // 目标维护要么完整配置,要么完全不配;半配置会让窗口"看起来存在"却挡不住目标。 targetSet := config.LibraryTargetInstance != "" || config.LibraryTargetProject != "" || - len(config.LibraryTargetWriters) > 0 || config.LibraryTargetIngressURL != "" + len(config.LibraryTargetWriters) > 0 || config.LibraryTargetIngressURL != "" || + noGate || config.LibraryTargetHealthURL != "" if targetSet { missing := make([]string, 0, 4) if config.LibraryTargetInstance == "" { @@ -401,16 +437,21 @@ func Load(getenv func(string) string) (Config, error) { if len(config.LibraryTargetWriters) == 0 { missing = append(missing, "LIBRARY_TARGET_WRITERS") } - if config.LibraryTargetIngressURL == "" { + if noGate { + // 没有闸门可声明:健康探针是唯一能证明"目标回来了"的必需项。 + if config.LibraryTargetHealthURL == "" { + missing = append(missing, "LIBRARY_TARGET_HEALTH_URL") + } + } else if config.LibraryTargetIngressURL == "" { missing = append(missing, "LIBRARY_TARGET_INGRESS_URL") } if config.LibraryTargetJournalRoot == "" { missing = append(missing, "LIBRARY_TARGET_JOURNAL_ROOT") } - if config.LibraryTargetIngressService == "" { + if !noGate && config.LibraryTargetIngressService == "" { missing = append(missing, "LIBRARY_TARGET_INGRESS_SERVICE") } - if config.LibraryTargetIngressDrainFile == "" { + if !noGate && config.LibraryTargetIngressDrainFile == "" { missing = append(missing, "LIBRARY_TARGET_INGRESS_DRAIN_FILE") } if config.LibraryTargetRedisAddr == "" { @@ -419,13 +460,17 @@ func Load(getenv func(string) string) (Config, error) { if len(missing) > 0 { return Config{}, fmt.Errorf("目标维护配置不完整:缺少 %s", strings.Join(missing, "、")) } + if noGate && (config.LibraryTargetIngressURL != "" || config.LibraryTargetIngressService != "" || + config.LibraryTargetIngressDrainFile != "") { + return Config{}, errors.New("no-gate 维护不得同时配置入口地址/闸门服务/排空文件:要么有闸门,要么明确没有") + } if !filepath.IsAbs(config.LibraryTargetJournalRoot) { return Config{}, errors.New("LIBRARY_TARGET_JOURNAL_ROOT 必须是绝对路径") } if !filepath.IsAbs(config.LibraryTargetDockerSocket) { return Config{}, errors.New("LIBRARY_TARGET_DOCKER_SOCKET 必须是绝对路径") } - if !filepath.IsAbs(config.LibraryTargetIngressDrainFile) { + if !noGate && !filepath.IsAbs(config.LibraryTargetIngressDrainFile) { return Config{}, errors.New("LIBRARY_TARGET_INGRESS_DRAIN_FILE 必须是绝对路径") } if len(config.LibraryTargetNonWriters) == 0 { diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go index 257ef96..af8e9da 100644 --- a/internal/httpapi/library_flow.go +++ b/internal/httpapi/library_flow.go @@ -599,6 +599,11 @@ func testSealedOf(versions []governance.LibraryVersion, byID map[string]libraryS // 它刻意只说配置:能停写入者/关入口/证明排空的真实能力在 worker 侧(docker socket、 // 闸门、排空文件),API 若声称"能力可用"就是拿配置字符串冒充执行证据。 func libraryMaintenanceCapability(config Config) map[string]any { + mode := strings.TrimSpace(config.LibraryTargetIngressMode) + if mode == "" { + mode = "gate" + } + noGate := mode == "none" missing := make([]string, 0, 6) if config.LibraryTargetInstance == "" { missing = append(missing, "LIBRARY_TARGET_INSTANCE") @@ -609,11 +614,18 @@ func libraryMaintenanceCapability(config Config) map[string]any { if len(config.LibraryTargetWriters) == 0 { missing = append(missing, "LIBRARY_TARGET_WRITERS") } - if config.LibraryTargetIngressURL == "" { - missing = append(missing, "LIBRARY_TARGET_INGRESS_URL") - } - if config.LibraryTargetIngressService == "" { - missing = append(missing, "LIBRARY_TARGET_INGRESS_SERVICE") + if noGate { + // 没有闸门:页面必须如实说"无闸门(测试模式)",不能显示"打开"。 + if config.LibraryTargetHealthURL == "" { + missing = append(missing, "LIBRARY_TARGET_HEALTH_URL") + } + } else { + if config.LibraryTargetIngressURL == "" { + missing = append(missing, "LIBRARY_TARGET_INGRESS_URL") + } + if config.LibraryTargetIngressService == "" { + missing = append(missing, "LIBRARY_TARGET_INGRESS_SERVICE") + } } if config.LibraryTargetJournalRoot == "" { missing = append(missing, "LIBRARY_TARGET_JOURNAL_ROOT") @@ -621,12 +633,18 @@ func libraryMaintenanceCapability(config Config) map[string]any { if config.LibraryTargetDockerSocket == "" { missing = append(missing, "LIBRARY_TARGET_DOCKER_SOCKET") } + ingressState := "闸门" + if noGate { + ingressState = "无闸门(测试模式)" + } return map[string]any{ "configured": len(missing) == 0, "missing": missing, "instance": config.LibraryTargetInstance, "project": config.LibraryTargetProject, "writers": config.LibraryTargetWriters, + "ingress_mode": mode, + "ingress_state": ingressState, "ingress_service": config.LibraryTargetIngressService, "note": "配置齐全只说明治理侧接线完整;停写入者、关入口与排空由 worker 在作业内校验并执行", } diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index 10229ef..9cc9090 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -159,8 +159,12 @@ type Config struct { LibraryTargetWriters []string LibraryTargetIngressURL string LibraryTargetIngressService string - LibraryTargetDockerSocket string - LibraryTargetJournalRoot string + // 入口形态与健康探针只用于如实展示"有没有闸门":none 显示"无闸门(测试模式)", + // 不能把没有闸门的测试栈说成"打开"。 + LibraryTargetIngressMode string + LibraryTargetHealthURL string + LibraryTargetDockerSocket string + LibraryTargetJournalRoot string // LibrarySourceInstance 是死信解除记录的来源实例名(封存源),留空回落到目标实例名。 LibrarySourceInstance string // LibraryAgentSocket 是主机侧封存 agent 的 unix socket;留空即页面不能发起封存。 diff --git a/internal/libraryfreeze/freeze.go b/internal/libraryfreeze/freeze.go index 703d8ff..9706fb2 100644 --- a/internal/libraryfreeze/freeze.go +++ b/internal/libraryfreeze/freeze.go @@ -29,6 +29,18 @@ type Service struct { ExitCode *int `json:"exit_code,omitempty"` } +// 入口形态。gate 是唯一默认值:必须真的关掉闸门、拿到排空证据才算窗口成立。 +// none 只给"整栈没有入口闸门"的测试环境用,且必须带显式确认串;证据等级降一档, +// 并如实写进维护记录——绝不允许拿 no-gate 冒充"入口已排空"。 +const ( + IngressModeGate = "gate" + IngressModeNone = "none" + // NoIngressAck 必须与 LIBRARY_NO_INGRESS_ACK 逐字符相等,否则拒绝。 + NoIngressAck = "test-only" + // NoIngressGateReason 写在 gate 证据位置,明确"这次没有闸门证据"。 + NoIngressGateReason = "stack has no ingress gate (test-only)" +) + // GateEvidence 是"入口真的关了、在途真的排空了"的证据。 // 只有被代理的服务自己不会优雅退出时,才知道为什么要在入口这一层排空。 type GateEvidence struct { @@ -37,6 +49,23 @@ type GateEvidence struct { ActiveAtClose int `json:"active_at_close"` Served int `json:"served"` Detail string `json:"detail,omitempty"` + // Mode 为空表示真实闸门证据;Mode=none 表示这个栈没有闸门(仅测试), + // 此时 Closed/Drained 恒为 false,ReadJournal 能读出"本次没有闸门证据"。 + Mode string `json:"mode,omitempty"` + Reason string `json:"reason,omitempty"` +} + +// MarshalJSON 让 no-gate 证据在 gate 位置只写形态与理由, +// 不写出 closed/drained=false 这种看起来像"关了但没排空"的假象。 +func (g GateEvidence) MarshalJSON() ([]byte, error) { + if g.Mode == IngressModeNone { + return json.Marshal(struct { + Mode string `json:"mode"` + Reason string `json:"reason"` + }{Mode: g.Mode, Reason: g.Reason}) + } + type plain GateEvidence + return json.Marshal(plain(g)) } // Gate 是目标的唯一对外入口:维护窗口先关它、等在途请求结束,再停写入者。 @@ -124,8 +153,12 @@ type journal struct { Result // Level 区分"实例级维护"(写入者/入口被真的关掉)与"仅治理库互斥"。 // 没有 Level 的旧 journal 来自封存链路,按实例级处理但不冒充已验证。 - Level string `json:"level,omitempty"` - Ingress string `json:"ingress,omitempty"` + Level string `json:"level,omitempty"` + Ingress string `json:"ingress,omitempty"` + // IngressMode 记录这次窗口的入口形态:gate(默认)或 none(测试栈没有闸门, + // 证据降一档)。IngressAck 只在 none 下非空,值是显式确认串。 + IngressMode string `json:"ingress_mode,omitempty"` + IngressAck string `json:"ingress_ack,omitempty"` IngressClosed bool `json:"ingress_closed,omitempty"` DrainVerified bool `json:"drain_verified,omitempty"` ContentRisk bool `json:"content_risk,omitempty"` @@ -140,6 +173,10 @@ type journal struct { // "关的时候还有几个在途请求"。 Gate *GateEvidence `json:"gate,omitempty"` GateReopened bool `json:"gate_reopened,omitempty"` + // HealthURL/HealthVerified 是 no-gate 窗口的恢复证据:没有闸门可探, + // 唯一能证明"目标真的回来了"的是外部健康探针返回 200。地址不许带凭据。 + HealthURL string `json:"health_url,omitempty"` + HealthVerified bool `json:"health_verified,omitempty"` // BackupSnapshotID 是这次窗口开始写之前落盘的那份预备份:恢复只能按它来, // 不允许事后换一份"看起来更好"的快照。 BackupSnapshotID string `json:"backup_snapshot_id,omitempty"` @@ -172,7 +209,12 @@ type Coordinator struct { gate Gate quiescer Quiescer fingerprint string - quiesceWait time.Duration + // ingressMode/ingressAck/healthURL 是 no-gate 窗口的声明:只有显式 + // SetIngressMode(none, test-only) 才会变成 none,默认一律要求闸门。 + ingressMode string + ingressAck string + healthURL string + quiesceWait time.Duration // quiesceStable 是"连续为空必须跨过的时间窗":单次瞬时 0 不算证明。 quiesceStable time.Duration // quiesceStall 是"同一批任务多久没有进展就判定卡住/被截断"。 @@ -195,16 +237,69 @@ func Open(root, source string, c Controller) (*Coordinator, error) { if err != nil { return nil, err } - return &Coordinator{root: r, source: source, control: c}, nil + return &Coordinator{root: r, source: source, control: c, ingressMode: IngressModeGate}, nil } func (c *Coordinator) Close() error { return c.root.Close() } +// SetIngressMode 声明这次维护的入口形态。默认(未调用)是 gate:必须真的关闸门。 +// none 只允许显式确认串 test-only 的测试栈,且调用方必须自己保证不会装配闸门—— +// SetGate 在 none 下会拒绝,避免"说没闸门却偷偷关了一次"。 +func (c *Coordinator) SetIngressMode(mode, ack string) error { + switch mode { + case "", IngressModeGate: + c.ingressMode = IngressModeGate + c.ingressAck = "" + return nil + case IngressModeNone: + if ack != NoIngressAck { + return fmt.Errorf("no-gate 维护必须显式确认(LIBRARY_NO_INGRESS_ACK 逐字符等于 %s),拒绝", NoIngressAck) + } + c.ingressMode, c.ingressAck = IngressModeNone, ack + return nil + default: + return fmt.Errorf("无效的入口形态 %q(只能是 %s 或 %s)", mode, IngressModeGate, IngressModeNone) + } +} + +// SetHealthURL 绑定 no-gate 窗口的唯一恢复证据:外部健康探针地址。 +// 只用于记录与探针,地址里不许出现凭据。 +func (c *Coordinator) SetHealthURL(raw string) error { + if raw == "" { + return nil + } + if !validHealthURL(raw) { + return errors.New("目标健康探针地址无效(LIBRARY_TARGET_HEALTH_URL)") + } + c.healthURL = raw + return nil +} + +func (c *Coordinator) ingressModeOrDefault() string { + if c.ingressMode == "" { + return IngressModeGate + } + return c.ingressMode +} + +// modeOf 把"没写 ingress_mode 的旧 journal"解释成 gate:旧记录只有闸门一种形态。 +func modeOf(raw string) string { + if raw == "" { + return IngressModeGate + } + return raw +} + // SetTarget 声明这次维护的层级与入口。实例级维护必须指名入口地址; // 只锁治理 scope 的维护不许带入口,否则就是拿"库级"冒充"实例级"。 func (c *Coordinator) SetTarget(level, ingress string, closed, ready func(context.Context) error) error { switch level { case "instance": - if !validIngress(ingress) { + if c.ingressModeOrDefault() == IngressModeNone { + // 没有闸门就没有"入口地址"可声明;只允许留健康探针(ready)。 + if ingress != "" || closed != nil { + return errors.New("no-gate 维护不得声明入口地址或入口关闭探针") + } + } else if !validIngress(ingress) { return errors.New("instance maintenance requires the target ingress address") } case "library": @@ -219,10 +314,14 @@ func (c *Coordinator) SetTarget(level, ingress string, closed, ready func(contex } // SetGate 声明目标入口闸门:实例级维护里"关入口"就是关它、并从它拿到排空证据。 +// no-gate 维护下拒绝装配闸门:那条路径一笔闸门动作都不许发生。 func (c *Coordinator) SetGate(g Gate) error { if g == nil { return errors.New("invalid ingress gate") } + if c.ingressModeOrDefault() == IngressModeNone { + return errors.New("no-gate 维护不得装配入口闸门") + } c.gate = g return nil } @@ -272,6 +371,12 @@ func validIngress(raw string) bool { return err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") && parsed.Host != "" && parsed.Path != "" && parsed.User == nil } +// validHealthURL 是健康探针地址:和入口同一套约束,但允许根路径("http://host:port/")。 +func validHealthURL(raw string) bool { + parsed, err := url.Parse(raw) + return err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") && parsed.Host != "" && parsed.User == nil +} + func (c *Coordinator) Recover(ctx context.Context) error { lock, err := c.lock() if err != nil { @@ -306,6 +411,14 @@ func (c *Coordinator) Recover(ctx context.Context) error { pending = append(pending, j) } } + // 入口形态必须与当前配置一致:拿 gate 配置去收尾一个 no-gate 窗口, + // 会凭空"打开"一扇这次根本没关过的门(或反过来把有闸门的窗口当没闸门放掉)。 + for _, j := range pending { + if modeOf(j.IngressMode) != modeOf(c.ingressMode) { + return fmt.Errorf("维护窗口 %s 的入口形态(%s)与当前配置(%s)不一致:需人工核对后再恢复", + j.Job, modeOf(j.IngressMode), modeOf(c.ingressMode)) + } + } // 内容可能已被写过的窗口不能自动开放:重启恢复只许"收尾确定性的事", // 半写目标必须由原作业接管或人工按预备份恢复,否则就是把半写当成品放行。 for _, j := range pending { @@ -320,6 +433,16 @@ func (c *Coordinator) Recover(ctx context.Context) error { if err = c.restore(ctx, &j); err != nil { return err } + // no-gate 窗口没有闸门可"重开":目标是否真的回来只能由健康探针证明, + // 探针不过就保持非终态,不写 interrupted 冒充收尾完成。 + if modeOf(j.IngressMode) == IngressModeNone { + if c.ingressReady != nil { + if readyErr := c.ingressReady(ctx); readyErr != nil { + return fmt.Errorf("no-gate 维护窗口 %s 恢复后健康探针未通过:%w", j.Job, readyErr) + } + } + j.HealthVerified = true + } j.State = "failed" j.Code = "interrupted" ended := time.Now().UTC() @@ -455,21 +578,52 @@ func parseJournal(data []byte, job, source string) (journal, error) { return journal{}, errors.New("invalid freeze maintenance level") } // 声明了实例级维护就必须留下入口证据;只锁库的窗口不许带入口。 - if j.Level == "instance" && !validIngress(j.Ingress) { - return journal{}, errors.New("invalid freeze ingress evidence") + // no-gate(测试栈)是唯一例外:必须同时带显式确认串、空入口、以及 + // mode=none 的证据占位,读记录的人能看出"本次没有闸门证据"。 + mode := modeOf(j.IngressMode) + if j.IngressMode != "" && mode != IngressModeGate && mode != IngressModeNone { + return journal{}, errors.New("invalid freeze ingress mode") } - if j.Level == "library" && (j.Ingress != "" || j.IngressClosed) { - return journal{}, errors.New("library scope lock claims ingress control") + if mode == IngressModeNone { + if j.Level != "instance" || j.IngressAck != NoIngressAck { + return journal{}, errors.New("invalid no-gate maintenance evidence") + } + if j.Ingress != "" || j.IngressClosed || j.GateReopened { + return journal{}, errors.New("no-gate maintenance claims ingress control") + } + if j.Gate == nil || j.Gate.Mode != IngressModeNone || j.Gate.Closed || j.Gate.Drained || j.Gate.Reason == "" { + return journal{}, errors.New("invalid no-gate maintenance evidence") + } + } else { + if j.Level == "instance" && !validIngress(j.Ingress) { + return journal{}, errors.New("invalid freeze ingress evidence") + } + if j.Level == "library" && (j.Ingress != "" || j.IngressClosed) { + return journal{}, errors.New("library scope lock claims ingress control") + } + if j.Gate != nil && (!j.Gate.Closed || j.Gate.ActiveAtClose < 0 || j.Gate.Served < 0) { + return journal{}, errors.New("invalid freeze ingress evidence") + } + } + if j.Level == "library" && j.IngressMode != "" { + return journal{}, errors.New("library scope lock claims ingress mode") } if j.RestoreBlocked && !j.ContentRisk { return journal{}, errors.New("invalid freeze restore block") } - if j.Gate != nil && (!j.Gate.Closed || j.Gate.ActiveAtClose < 0 || j.Gate.Served < 0) { + if mode == IngressModeGate && j.Gate != nil && (!j.Gate.Closed || j.Gate.ActiveAtClose < 0 || j.Gate.Served < 0) { return journal{}, errors.New("invalid freeze ingress evidence") } if j.GateReopened && j.Gate == nil { return journal{}, errors.New("ingress reopened without close evidence") } + // no-gate 窗口的恢复证据只能是外部健康探针:写了"已验证"就必须有可核验的地址。 + if j.HealthVerified && !validHealthURL(j.HealthURL) { + return journal{}, errors.New("invalid health probe evidence") + } + if mode == IngressModeNone && j.HealthURL == "" && !terminal(j.State) { + return journal{}, errors.New("no-gate maintenance requires a health probe") + } if j.BackupSnapshotID != "" && !validDigest(j.BackupSnapshotID) { return journal{}, errors.New("invalid backup snapshot id") } @@ -638,11 +792,13 @@ func (c *Coordinator) restore(ctx context.Context, j *journal) error { // 注意:入口关到一半失败(闸门已被停、排空超时)时 j.Gate 可能还是 nil, // 但入口确实已经不在了。所以实例级维护一律重新打开入口,而不是只看 // "有没有成功关闭的证据"——否则会出现"维护已释放、服务在跑、入口却是关的"。 - // 但只要**任何一个写入者没回到健康**,这里的 else 分支就不执行:入口保持关闭, + // 但**任何写入者没回到健康**,这里的 else 分支就不执行:入口保持关闭, // 由调用方按 held 处理并走恢复(宁可不可用,也不对外暴露没准备好的目标)。 + // no-gate(测试模式)根本没有闸门:一笔闸门动作都不做,也不写"入口已重开"。 switch { case serviceFailures != nil: serviceFailures = errors.Join(serviceFailures, errors.New("目标入口保持关闭:写入者未全部恢复健康")) + case modeOf(j.IngressMode) == IngressModeNone: case c.level == "instance" || j.Gate != nil: if c.gate == nil { persistFailures = errors.Join(persistFailures, errors.New("入口闸门缺失:不能确认目标已恢复")) diff --git a/internal/libraryfreeze/journal_evidence.go b/internal/libraryfreeze/journal_evidence.go index f20e3ec..3e9b7d0 100644 --- a/internal/libraryfreeze/journal_evidence.go +++ b/internal/libraryfreeze/journal_evidence.go @@ -27,10 +27,14 @@ type JournalEvidence struct { State string TargetFingerprint string Ingress string + IngressMode string + IngressAck string IngressClosed bool DrainVerified bool ContentRisk bool RestoreBlocked bool + HealthURL string + HealthVerified bool Gate *GateEvidence Quiesce *QuiesceProof Services []JournalService @@ -94,8 +98,10 @@ func ReadJournal(dir, job string) (JournalEvidence, error) { evidence = JournalEvidence{ Job: job, Source: j.Source, Level: j.Level, State: j.State, TargetFingerprint: j.TargetFingerprint, Ingress: j.Ingress, + IngressMode: modeOf(j.IngressMode), IngressAck: j.IngressAck, IngressClosed: j.IngressClosed, DrainVerified: j.DrainVerified, ContentRisk: j.ContentRisk, RestoreBlocked: j.RestoreBlocked, + HealthURL: j.HealthURL, HealthVerified: j.HealthVerified, Gate: j.Gate, Quiesce: j.Quiesce, Services: services, StartedAt: j.StartedAt.UTC(), Digest: hex.EncodeToString(sum[:]), } diff --git a/internal/libraryfreeze/no_gate_mode_test.go b/internal/libraryfreeze/no_gate_mode_test.go new file mode 100644 index 0000000..d1ceea8 --- /dev/null +++ b/internal/libraryfreeze/no_gate_mode_test.go @@ -0,0 +1,233 @@ +package libraryfreeze + +import ( + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + "time" +) + +// noGateFixture 是"整栈没有入口闸门"的测试栈:只有写者与队列, +// 入口可用性由外部健康探针证明,闸门一个都不装配。 +func noGateFixture(t *testing.T, probes *int) (string, *exitControl, *Coordinator) { + t.Helper() + root := t.TempDir() + if err := os.Chmod(root, 0700); err != nil { + t.Fatal(err) + } + // 真实 0.9.0 栈里被代理服务收到 SIGTERM 会 exit(1):no-gate 路径不能靠退出码判排空。 + c := &exitControl{fixtureControl: &fixtureControl{services: []Service{ + {ID: "app", Running: true, Healthy: true}}}, exit: map[string]int{"app": 1}} + engine, err := Open(root, "target-instance", c) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { engine.Close() }) + if err := engine.SetIngressMode(IngressModeNone, NoIngressAck); err != nil { + t.Fatal(err) + } + if err := engine.SetHealthURL("http://127.0.0.1:1/health"); err != nil { + t.Fatal(err) + } + if err := engine.SetTarget("instance", "", nil, func(context.Context) error { + (*probes)++ + return nil + }); err != nil { + t.Fatal(err) + } + if err := engine.SetQuiescer(&idleQuiescer{}); err != nil { + t.Fatal(err) + } + if err := engine.SetQuiesceStability(5*time.Millisecond, 200*time.Millisecond); err != nil { + t.Fatal(err) + } + return root, c, engine +} + +// 没有显式确认串就不许进 no-gate:确认串必须逐字符相等。 +func TestNoGateModeRequiresExactAck(t *testing.T) { + root := t.TempDir() + if err := os.Chmod(root, 0700); err != nil { + t.Fatal(err) + } + engine, err := Open(root, "target-instance", &fixtureControl{services: []Service{{ID: "app", Running: true, Healthy: true}}}) + if err != nil { + t.Fatal(err) + } + defer engine.Close() + for _, ack := range []string{"", "test_only", "TEST-ONLY", " test-only", "test-only "} { + if err := engine.SetIngressMode(IngressModeNone, ack); err == nil || + !strings.Contains(err.Error(), "LIBRARY_NO_INGRESS_ACK") { + t.Fatalf("ack=%q 没有被拒并点名:%v", ack, err) + } + } + if err := engine.SetIngressMode("no", NoIngressAck); err == nil { + t.Fatal("未知入口形态被接受") + } + // gate 是默认:不调用 SetIngressMode 时仍然是 gate。 + if err := engine.SetIngressMode(IngressModeGate, ""); err != nil { + t.Fatalf("gate 被拒:%v", err) + } +} + +// no-gate 下不许装配闸门:那条路径一笔闸门动作都不能发生。 +func TestNoGateModeRefusesGateAndIngressClaim(t *testing.T) { + root := t.TempDir() + if err := os.Chmod(root, 0700); err != nil { + t.Fatal(err) + } + engine, err := Open(root, "target-instance", &fixtureControl{services: []Service{{ID: "app", Running: true, Healthy: true}}}) + if err != nil { + t.Fatal(err) + } + defer engine.Close() + if err := engine.SetIngressMode(IngressModeNone, NoIngressAck); err != nil { + t.Fatal(err) + } + calls := []string{} + if err := engine.SetGate(&fakeGate{calls: &calls, drain: true, active: 1}); err == nil { + t.Fatal("no-gate 模式接受了闸门") + } + if len(calls) != 0 { + t.Fatalf("闸门被调用:%v", calls) + } + if err := engine.SetTarget("instance", "http://127.0.0.1:1/health", nil, nil); err == nil { + t.Fatal("no-gate 模式接受了入口地址") + } + if err := engine.SetTarget("instance", "", func(context.Context) error { return nil }, nil); err == nil { + t.Fatal("no-gate 模式接受了入口关闭探针") + } +} + +// no-gate + 显式确认:窗口能开、记录写明 ingress_mode=none 与"无闸门"理由、 +// 恢复后健康探针被调用、闸门一次都没被调用。 +func TestNoGateWindowRecordsDowngradedEvidence(t *testing.T) { + probes := 0 + root, c, engine := noGateFixture(t, &probes) + result, err := engine.RunWindow(context.Background(), "job-nogate", func(context.Context) error { return nil }, + func(_ context.Context, w *Window) (string, error) { + for _, s := range c.services { + if s.Running { + t.Fatal("work started while a writer was still running") + } + } + // 记一笔内容风险,恢复/收尾也要能在 none 模式下跑完。 + if err := w.SetBackupSnapshot(context.Background(), strings.Repeat("a", 64)); err != nil { + t.Fatal(err) + } + return strings.Repeat("b", 64), nil + }, func(error) bool { return true }) + if err != nil { + t.Fatalf("no-gate 窗口失败:%v", err) + } + if result.State != "succeeded" { + t.Fatalf("result=%+v", result) + } + // 闸门从未被调用:调用记录里只有写者的 stop/start。 + if got := strings.Join(c.calls, ","); got != "stop:app,start:app" { + t.Fatalf("calls=%v", c.calls) + } + if probes == 0 { + t.Fatal("恢复后没有调用健康探针") + } + raw, err := os.ReadFile(filepath.Join(root, "job-nogate.json")) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(raw), `"ingress_mode":"none"`) { + t.Fatalf("记录没有 ingress_mode=none:%s", raw) + } + j, err := engine.load("job-nogate") + if err != nil { + t.Fatalf("维护记录读不回来:%v(raw=%s)", err, raw) + } + if j.IngressMode != IngressModeNone || j.IngressAck != NoIngressAck { + t.Fatalf("入口形态没写进记录:%+v", j) + } + if j.Gate == nil || j.Gate.Mode != IngressModeNone || j.Gate.Closed || j.Gate.Drained || + j.Gate.Reason != NoIngressGateReason { + t.Fatalf("gate 证据位置不是 no-gate 占位:%+v", j.Gate) + } + if !j.HealthVerified || j.HealthURL == "" { + t.Fatalf("健康探针证据缺失:%+v", j) + } + if j.GateReopened || j.IngressClosed { + t.Fatalf("no-gate 窗口冒充了入口开关:reopened=%v closed=%v", j.GateReopened, j.IngressClosed) + } + if !j.DrainVerified { + t.Fatal("写者全停 + 队列静默没有记为排空证据") + } + // 原始 JSON 也必须能读出"本次没有闸门证据"。 + for _, want := range []string{ + `"ingress_mode":"none"`, + `"ingress_ack":"test-only"`, + `"gate":{"mode":"none","reason":"stack has no ingress gate (test-only)"}`, + } { + if !strings.Contains(string(raw), want) { + t.Fatalf("记录缺少 %s:%s", want, raw) + } + } + if strings.Contains(string(raw), `"gate_reopened":true`) { + t.Fatalf("记录声称重开过闸门:%s", raw) + } +} + +// gate 模式的记录必须照旧写 ingress_mode=gate,且仍然要求真实排空证据。 +func TestGateWindowRecordsGateMode(t *testing.T) { + root, c, engine := instanceFixture(t) + gate := &fakeGate{calls: &c.calls, drain: true, active: 1} + if err := engine.SetGate(gate); err != nil { + t.Fatal(err) + } + if _, err := engine.RunWindow(context.Background(), "job-gate-mode", func(context.Context) error { return nil }, + func(context.Context, *Window) (string, error) { return "", nil }, func(error) bool { return true }); err != nil { + t.Fatal(err) + } + raw, err := os.ReadFile(filepath.Join(root, "job-gate-mode.json")) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(raw), `"ingress_mode":"gate"`) { + t.Fatalf("gate 记录没有写入口形态:%s", raw) + } + if strings.Contains(string(raw), `"mode":"none"`) { + t.Fatalf("gate 记录写成了 no-gate:%s", raw) + } + // gate 模式的 JSON 仍然是老形状:closed/drained 都在。 + var decoded struct { + Gate map[string]any `json:"gate"` + } + if err := json.Unmarshal(raw, &decoded); err != nil { + t.Fatal(err) + } + if decoded.Gate["closed"] != true || decoded.Gate["drained"] != true { + t.Fatalf("gate 证据被改写:%+v", decoded.Gate) + } +} + +// no-gate 下健康探针不通过 = 服务没回来:窗口不得报成功,也不许冒充"入口已开"。 +func TestNoGateWindowFailsWhenHealthProbeNeverRecovers(t *testing.T) { + probes := 0 + _, _, engine := noGateFixture(t, &probes) + // 把探针换成永远失败的:模拟写完内容后服务起不来。 + engine.ingressReady = func(context.Context) error { return errors.New("health 503") } + _, err := engine.RunWindow(context.Background(), "job-nogate-sick", func(context.Context) error { return nil }, + func(context.Context, *Window) (string, error) { return "", nil }, func(error) bool { return true }) + if err == nil { + t.Fatal("健康探针失败却报成功") + } + j, loadErr := engine.load("job-nogate-sick") + if loadErr != nil { + t.Fatal(loadErr) + } + if j.State != "held" || j.Code != "ingress_unverified" { + t.Fatalf("状态不是 held/ingress_unverified:state=%s code=%s", j.State, j.Code) + } + if j.GateReopened { + t.Fatal("no-gate 窗口伪造了闸门重开") + } +} diff --git a/internal/libraryfreeze/recovery.go b/internal/libraryfreeze/recovery.go index facdc4c..c940a55 100644 --- a/internal/libraryfreeze/recovery.go +++ b/internal/libraryfreeze/recovery.go @@ -37,13 +37,19 @@ func (c *Coordinator) RecoverWindow(ctx context.Context, job string, restorer Re } defer unlock(lock) - if c.level == "instance" && c.gate == nil { + if c.level == "instance" && c.gate == nil && c.ingressModeOrDefault() != IngressModeNone { return Result{}, errors.New("实例级恢复缺少入口闸门:不能证明入口已关闭") } j, err := c.load(job) if err != nil { return Result{}, err } + // 恢复只能用与窗口一致的入口形态:拿 no-gate 去收尾一扇真门,或反向, + // 都会假装"这次开过/没开过闸门"。 + if modeOf(j.IngressMode) != c.ingressModeOrDefault() { + return Result{}, fmt.Errorf("维护记录的入口形态(%s)与当前配置(%s)不一致:拒绝恢复", + modeOf(j.IngressMode), c.ingressModeOrDefault()) + } if terminal(j.State) { // 终态重放(F05 路径二):journal 已经是 recovered,说明数据恢复与服务/入口 // 恢复都已完成。这时再拒绝会让"journal recovered → PG 维护释放"之间的崩溃 @@ -150,6 +156,7 @@ func (c *Coordinator) RecoverWindow(ctx context.Context, job string, restorer Re return c.failRecovery(&j, "ingress_unverified", fmt.Errorf("入口未恢复:%w", readyErr)) } } + c.markHealth(&j) j.State = "recovered" j.Code = "" j.FinishedAt = &ended diff --git a/internal/libraryfreeze/window.go b/internal/libraryfreeze/window.go index 27f831d..c0c3ad3 100644 --- a/internal/libraryfreeze/window.go +++ b/internal/libraryfreeze/window.go @@ -103,8 +103,8 @@ func (c *Coordinator) RunWindow(ctx context.Context, job string, prepare func(co } defer unlock(lock) // 实例级维护的入口必须由我们关:没有闸门就没有"入口已关"的证据, - // 后面拿什么证明后台静默都是空的。 - if c.level == "instance" && c.gate == nil { + // 后面拿什么证明后台静默都是空的。唯一例外是显式确认过的 no-gate 测试栈。 + if c.level == "instance" && c.gate == nil && c.ingressModeOrDefault() != IngressModeNone { return Result{}, errors.New("实例级维护缺少入口闸门:不能证明入口已关闭") } @@ -141,6 +141,7 @@ func (c *Coordinator) RunWindow(ctx context.Context, job string, prepare func(co } j = journal{Version: 1, Source: c.source, Job: job, Level: c.level, Ingress: c.ingress, Attempt: attempt, SupersededFrom: superseded, + IngressMode: c.ingressModeOrDefault(), IngressAck: c.ingressAck, HealthURL: c.healthURL, TargetFingerprint: c.fingerprint, Result: Result{State: "stopping"}, StartedAt: time.Now().UTC()} for _, s := range items { if s.Running && !s.Healthy { @@ -177,7 +178,8 @@ func (c *Coordinator) RunWindow(ctx context.Context, job string, prepare func(co return Result{}, err } j = journal{Version: 1, Source: c.source, Job: job, Level: c.level, Ingress: c.ingress, - Attempt: 1, TargetFingerprint: c.fingerprint, Result: Result{State: "stopping"}, StartedAt: time.Now().UTC()} + Attempt: 1, IngressMode: c.ingressModeOrDefault(), IngressAck: c.ingressAck, HealthURL: c.healthURL, + 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") @@ -192,50 +194,98 @@ func (c *Coordinator) RunWindow(ctx context.Context, job string, prepare func(co // 顺序不能换:先把外部任务的生产入口关掉并排空,再证明后台静默,最后才停写入者。 // 先证明静默再关入口是错的——排空期间还在跑的在途请求随时会派生新的异步任务, // 那一刻的"空"到停写者时早就失效了;而 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") + // + // no-gate(测试栈)没有闸门可关:顺序改成"先停写者 → 再证明队列排空 → 导出", + // 并且一笔闸门动作都不做;gate 证据位置只留 mode=none 的说明,不冒充排空。 + mode := modeOf(j.IngressMode) + if mode != c.ingressModeOrDefault() { + return Result{}, fmt.Errorf("维护记录与当前配置的入口形态不一致(记录 %s,配置 %s),拒绝接管", + mode, c.ingressModeOrDefault()) + } + if mode == IngressModeNone { + if j.Gate == nil || j.Gate.Mode != IngressModeNone { + evidence := GateEvidence{Mode: IngressModeNone, Reason: NoIngressGateReason} + j.Gate = &evidence } - if !evidence.Closed || !evidence.Drained { - return c.abandonWindow(ctx, &j, errors.New("目标入口未确认排空(仍有在途请求)"), "gate_not_drained") + if j.IngressAck == "" { + j.IngressAck = c.ingressAck + } + if j.HealthURL == "" { + j.HealthURL = c.healthURL } - 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") + 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") + } + // 写者全停之后队列必须一直为空:这一刻的"空"就是这次窗口的排空证据。 + proof, quietErr := c.awaitBackgroundQuiet(ctx, &j) + if quietErr != nil { + return c.abandonWindow(ctx, &j, quietErr, "background_busy") + } + if stopErr := c.verifyBackgroundAfterStop(ctx, &j, proof); stopErr != nil { + return c.abandonWindow(ctx, &j, stopErr, "background_truncated") + } + // 没有闸门排空证据,也没有退出码可作凭据:排空只由"写者全停 + 队列静默" + // 共同证明——证据等级降一档,且已写进 ingress_mode=none。 + j.DrainVerified = true + j.State = "held" + if err = c.save(j); err != nil { + return Result{}, err + } + } else { + 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 } - j.IngressClosed = true - } - j.State = "held" - if err = c.save(j); err != nil { - return Result{}, err } w := &Window{c: c, j: &j} @@ -301,6 +351,7 @@ func (c *Coordinator) abandonWindow(ctx context.Context, j *journal, cause error return j.Result, errors.Join(cause, fmt.Errorf("目标入口没有恢复:%w", readyErr)) } } + c.markHealth(j) ended := time.Now().UTC() j.State = "failed" j.Code = code @@ -311,6 +362,17 @@ func (c *Coordinator) abandonWindow(ctx context.Context, j *journal, cause error return j.Result, cause } +// markHealth 记录 no-gate 窗口的恢复证据:只有健康探针真的通过才写 verified。 +func (c *Coordinator) markHealth(j *journal) { + if c.ingressModeOrDefault() != IngressModeNone { + return + } + j.HealthVerified = true + if j.HealthURL == "" { + j.HealthURL = c.healthURL + } +} + // closeWindow:写完之后的收尾。allowRestore=false(半写且回滚失败)时 // 服务保持停止、journal 保持非终态,返回的是"目标仍在维护"这个结论。 func (c *Coordinator) closeWindow(ctx context.Context, j *journal, cause error, allowRestore bool, snapshotID string) (Result, error) { @@ -348,6 +410,7 @@ func (c *Coordinator) closeWindow(ctx context.Context, j *journal, cause error, return j.Result, errors.Join(cause, fmt.Errorf("目标入口没有恢复:%w", readyErr)) } } + c.markHealth(j) ended := time.Now().UTC() j.FinishedAt = &ended if cause != nil { @@ -399,7 +462,8 @@ func (c *Coordinator) awaitBackgroundQuiet(ctx context.Context, j *journal) (*Qu } return nil, nil } - if j.Gate == nil || !j.Gate.Drained { + // no-gate 窗口没有"入口已关"这个前提:静默证明只对队列负责(写者已全停)。 + if c.ingressModeOrDefault() != IngressModeNone && (j.Gate == nil || !j.Gate.Drained) { return nil, errors.New("必须先关闭并排空入口,再证明后台静默") } @@ -555,13 +619,15 @@ func (c *Coordinator) verifyDrain(ctx context.Context, j *journal) error { return errors.New("test writer still running") } if now.ExitCode == nil { - if c.level == "instance" && !gateDrained { + // no-gate 窗口:没有闸门排空证据,也不把退出码当唯一凭据 + //(被代理服务收到 SIGTERM 会 exit(1));排空由"写者全停 + 队列静默"证明。 + if c.level == "instance" && !gateDrained && c.ingressModeOrDefault() != IngressModeNone { return fmt.Errorf("无法证明 %s 的在途请求已排空(控制器没有退出码)", s.ID) } continue } s.ExitCode = now.ExitCode - if *now.ExitCode != 0 && !gateDrained { + if *now.ExitCode != 0 && !gateDrained && c.ingressModeOrDefault() != IngressModeNone { return fmt.Errorf("写入者 %s 未优雅退出(exit=%d):在途请求没有完成排空", s.ID, *now.ExitCode) } verified++ diff --git a/internal/librarymaintenance/env.go b/internal/librarymaintenance/env.go index 25970cc..a12205a 100644 --- a/internal/librarymaintenance/env.go +++ b/internal/librarymaintenance/env.go @@ -5,6 +5,8 @@ import ( "fmt" "strconv" "strings" + + "knowledge-governance/internal/libraryfreeze" ) // 目标入口闸门与后台队列的声明名称。 @@ -15,10 +17,15 @@ import ( // 错的证据。 const ( EnvInstance = "LIBRARY_TARGET_INSTANCE" + EnvIngressMode = "LIBRARY_TARGET_INGRESS_MODE" + EnvNoIngressAck = "LIBRARY_NO_INGRESS_ACK" EnvIngressURL = "LIBRARY_TARGET_INGRESS_URL" EnvIngressService = "LIBRARY_TARGET_INGRESS_SERVICE" EnvIngressDrainFile = "LIBRARY_TARGET_INGRESS_DRAIN_FILE" - EnvRedisAddr = "LIBRARY_TARGET_REDIS_ADDR" + // EnvHealthURL 是 no-gate 窗口唯一的"目标回来了"证据:闸门不存在时, + // 只有外部健康探针能证明写入者恢复后真的在服务。 + EnvHealthURL = "LIBRARY_TARGET_HEALTH_URL" + EnvRedisAddr = "LIBRARY_TARGET_REDIS_ADDR" // 名字里不写 Password:这里的字面量是**环境变量名**,密钥扫描会把 // `XXX_PASSWORD = "<长字面量>"` 当成"被赋值的密钥",那是误报但没必要留个坑。 EnvRedisAuth = "LIBRARY_TARGET_REDIS_PASSWORD" @@ -27,14 +34,20 @@ const ( // TargetEnv 是一次实例级维护所需的"入口 + 队列"声明。 // -// 缺任何一项都不许降级成"库级维护":没有闸门就没有"入口已关、在途已排空" -// 的证据,没有队列就证明不了停写者时后台是空的。这两条正是被代理的 WeKnora +// 缺任何一项都不许降级成"库级维护":没有闸门就没有"入口已关、在途已排空"的 +// 证据,没有队列就证明不了停写者时后台是空的。这两条正是被代理的 WeKnora // 收到 SIGTERM 就 exit(1) 之后唯一还能证明"请求没被截断"的东西。 +// +// Mode=none 只给"整栈没有入口闸门"的测试环境用,且必须带显式确认串: +// 那条路径不允许调用任何闸门动作,证据等级降一档并写进维护记录。 type TargetEnv struct { Instance string + Mode string + Ack string IngressURL string IngressService string IngressDrainFile string + HealthURL string RedisAddr string RedisPassword string RedisDB int @@ -49,24 +62,59 @@ func TargetFromEnv(get func(string) string) (TargetEnv, error) { value := func(name string) string { return strings.TrimSpace(get(name)) } target := TargetEnv{ Instance: value(EnvInstance), + Mode: value(EnvIngressMode), IngressURL: value(EnvIngressURL), IngressService: value(EnvIngressService), IngressDrainFile: value(EnvIngressDrainFile), + HealthURL: value(EnvHealthURL), RedisAddr: value(EnvRedisAddr), // 口令不 Trim:前后空格也是口令的一部分,Trim 会把能连上的配置变成连不上。 RedisPassword: get(EnvRedisAuth), } - missing := make([]string, 0, 5) - for _, item := range []struct { + if target.Mode == "" { + target.Mode = libraryfreeze.IngressModeGate + } + switch target.Mode { + case libraryfreeze.IngressModeGate: + target.Ack = "" + case libraryfreeze.IngressModeNone: + // 确认串逐字符相等:不 Trim、不忽略大小写。没写对就是没确认。 + ack := get(EnvNoIngressAck) + if ack != libraryfreeze.NoIngressAck { + return TargetEnv{}, fmt.Errorf( + "no-gate 维护必须显式确认:%s 必须逐字符等于 %s(当前%s),拒绝开窗口", + EnvNoIngressAck, libraryfreeze.NoIngressAck, describeAck(ack)) + } + target.Ack = ack + // 半套闸门声明最危险:既关不掉门,又容易被当成"有门"。要么有,要么明确没有。 + if target.IngressURL != "" || target.IngressService != "" || target.IngressDrainFile != "" { + return TargetEnv{}, fmt.Errorf( + "no-gate 维护不得同时声明 %s/%s/%s:要么有闸门,要么明确没有", + EnvIngressURL, EnvIngressService, EnvIngressDrainFile) + } + default: + return TargetEnv{}, fmt.Errorf("%s 无效(%q):只能是 %s 或 %s", + EnvIngressMode, target.Mode, libraryfreeze.IngressModeGate, libraryfreeze.IngressModeNone) + } + + required := []struct { name string current string }{ {EnvInstance, target.Instance}, - {EnvIngressURL, target.IngressURL}, - {EnvIngressService, target.IngressService}, - {EnvIngressDrainFile, target.IngressDrainFile}, {EnvRedisAddr, target.RedisAddr}, - } { + } + if target.Mode == libraryfreeze.IngressModeNone { + // 没有闸门可声明:改由健康探针证明"目标真的回来了",它因此是必需的。 + required = append(required, struct{ name, current string }{EnvHealthURL, target.HealthURL}) + } else { + required = append(required, + struct{ name, current string }{EnvIngressURL, target.IngressURL}, + struct{ name, current string }{EnvIngressService, target.IngressService}, + struct{ name, current string }{EnvIngressDrainFile, target.IngressDrainFile}) + } + missing := make([]string, 0, 5) + for _, item := range required { if item.current == "" { missing = append(missing, item.name) } @@ -86,8 +134,25 @@ func TargetFromEnv(get func(string) string) (TargetEnv, error) { target.RedisDB = db } if len(missing) > 0 { - return TargetEnv{}, fmt.Errorf("实例级维护未接线:缺少 %s(没有入口闸门与队列就无法证明入口已排空、后台已静默)", - strings.Join(missing, "、")) + hint := "没有入口闸门与队列就无法证明入口已排空、后台已静默" + if target.Mode == libraryfreeze.IngressModeNone { + hint = "no-gate 测试模式仍需要实例、队列与健康探针" + } + return TargetEnv{}, fmt.Errorf("实例级维护未接线:缺少 %s(%s)", + strings.Join(missing, "、"), hint) } return target, nil } + +// describeAck 只描述"确认串有没有写对",不回显内容:写错时也可能是一段 +// 看起来像凭据的东西,错误信息里没必要复制它。 +func describeAck(ack string) string { + switch { + case ack == "": + return "为空" + case strings.TrimSpace(ack) == libraryfreeze.NoIngressAck: + return "含多余空白" + default: + return "取值不匹配" + } +} diff --git a/internal/librarymaintenance/no_gate_env_test.go b/internal/librarymaintenance/no_gate_env_test.go new file mode 100644 index 0000000..712b8ed --- /dev/null +++ b/internal/librarymaintenance/no_gate_env_test.go @@ -0,0 +1,88 @@ +package librarymaintenance + +import ( + "strings" + "testing" + + "knowledge-governance/internal/libraryfreeze" +) + +// noGateEnv 是 0.9.0 测试栈的声明:没有闸门,只有实例、队列与健康探针。 +func noGateEnv() map[string]string { + return map[string]string{ + EnvInstance: "kgmaint-v090", + EnvIngressMode: libraryfreeze.IngressModeNone, + EnvNoIngressAck: libraryfreeze.NoIngressAck, + EnvHealthURL: "http://127.0.0.1:18081/health", + EnvRedisAddr: "127.0.0.1:26379", + EnvRedisAuth: "secret", + EnvRedisDB: "0", + } +} + +func TestTargetFromEnvNoGateNeedsExplicitAck(t *testing.T) { + values := noGateEnv() + delete(values, EnvNoIngressAck) + _, err := TargetFromEnv(lookup(values)) + if err == nil || !strings.Contains(err.Error(), EnvNoIngressAck) { + t.Fatalf("缺确认串没有被拒并点名:%v", err) + } + for _, ack := range []string{"", "test_only", "TEST-ONLY", " test-only", "test-only "} { + values := noGateEnv() + values[EnvNoIngressAck] = ack + if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvNoIngressAck) { + t.Fatalf("ack=%q 没有被拒:%v", ack, err) + } + } +} + +func TestTargetFromEnvNoGateAcceptsMissingIngressItems(t *testing.T) { + target, err := TargetFromEnv(lookup(noGateEnv())) + if err != nil { + t.Fatalf("no-gate 声明被拒:%v", err) + } + if target.Mode != libraryfreeze.IngressModeNone || target.Ack != libraryfreeze.NoIngressAck { + t.Fatalf("入口形态没解析对:%+v", target) + } + if target.IngressURL != "" || target.IngressService != "" || target.IngressDrainFile != "" { + t.Fatalf("no-gate 声明里出现了闸门项:%+v", target) + } + if target.HealthURL != "http://127.0.0.1:18081/health" || target.RedisDB != 0 { + t.Fatalf("健康探针/队列没解析对:%+v", target) + } +} + +// 证据降一档不等于什么都不需要:健康探针与队列仍必须给。 +func TestTargetFromEnvNoGateStillNeedsHealthAndQueue(t *testing.T) { + for _, name := range []string{EnvInstance, EnvHealthURL, EnvRedisAddr, EnvRedisAuth, EnvRedisDB} { + values := noGateEnv() + delete(values, name) + if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), name) { + t.Fatalf("缺 %s 没有被点名:%v", name, err) + } + } +} + +// 缺省仍是 gate:没有 mode 变量时照旧要求三项闸门声明(原行为不变)。 +func TestTargetFromEnvDefaultsToGate(t *testing.T) { + values := completeEnv() + target, err := TargetFromEnv(lookup(values)) + if err != nil { + t.Fatalf("gate 声明被拒:%v", err) + } + if target.Mode != libraryfreeze.IngressModeGate || target.Ack != "" { + t.Fatalf("缺省不是 gate:%+v", target) + } + values[EnvIngressURL] = "" + if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvIngressURL) { + t.Fatalf("gate 模式缺入口没有被拒:%v", err) + } +} + +func TestTargetFromEnvRejectsUnknownMode(t *testing.T) { + values := completeEnv() + values[EnvIngressMode] = "open" + if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvIngressMode) { + t.Fatalf("未知入口形态没有被拒:%v", err) + } +} diff --git a/internal/librarymaintenance/target.go b/internal/librarymaintenance/target.go index 00afc52..1451514 100644 --- a/internal/librarymaintenance/target.go +++ b/internal/librarymaintenance/target.go @@ -48,14 +48,20 @@ type Config struct { Writers []string NonWriters map[string]string DockerSocket string - IngressURL string + // IngressMode 是 gate(默认)或 none;none 只给整栈没有入口闸门的测试环境用, + // 必须同时给 IngressAck,且一次闸门动作都不做。 + IngressMode string + IngressAck string + IngressURL string // IngressService 是入口闸门在 compose 项目里的服务名;DrainFile 是它写 // 排空证据的宿主机文件。两者缺一,就只能说"停了写入者",不能说"排空了"。 IngressService string IngressDrainFile string - Database string - Index string - Bucket string + // HealthURL 是 no-gate 模式下唯一的"目标回来了"证据(恢复后必须 200)。 + HealthURL string + Database string + Index string + Bucket string // 后台静默检查需要的运行时依赖(不写进维护记录)。 DatabaseURL string RedisAddr string @@ -75,6 +81,9 @@ type Manager struct { gate *dockerGate api *dockerAPI quiescer *targetQuiescer + mode string + ack string + healthURL string } // Close 释放拓扑/静默检查持有的连接。 @@ -91,6 +100,11 @@ func New(cfg Config) (*Manager, error) { instance := strings.TrimSpace(cfg.Instance) project := strings.TrimSpace(cfg.Project) ingress := strings.TrimSpace(cfg.IngressURL) + health := strings.TrimSpace(cfg.HealthURL) + mode := strings.TrimSpace(cfg.IngressMode) + if mode == "" { + mode = libraryfreeze.IngressModeGate + } if instance == "" || project == "" { return nil, errors.New("实例级维护配置缺少 LIBRARY_TARGET_INSTANCE/PROJECT") } @@ -100,9 +114,27 @@ func New(cfg Config) (*Manager, error) { if !filepath.IsAbs(cfg.DockerSocket) { return nil, errors.New("Docker socket 必须是绝对路径") } - parsed, err := url.Parse(ingress) - if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" || parsed.Path == "" || parsed.User != nil { - return nil, errors.New("目标入口地址无效(LIBRARY_TARGET_INGRESS_URL)") + switch mode { + case libraryfreeze.IngressModeGate: + parsed, err := url.Parse(ingress) + if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Host == "" || parsed.Path == "" || parsed.User != nil { + return nil, errors.New("目标入口地址无效(LIBRARY_TARGET_INGRESS_URL)") + } + case libraryfreeze.IngressModeNone: + // 显式确认是这道口子的唯一开关:没有它,no-gate 一律拒绝。 + if cfg.IngressAck != libraryfreeze.NoIngressAck { + return nil, fmt.Errorf("no-gate 维护必须显式确认(LIBRARY_NO_INGRESS_ACK 逐字符等于 %s),拒绝", + libraryfreeze.NoIngressAck) + } + if ingress != "" || cfg.IngressService != "" || cfg.IngressDrainFile != "" { + return nil, errors.New("no-gate 维护不得同时声明入口地址/闸门服务/排空文件:要么有闸门,要么明确没有") + } + if !validHealthURL(health) { + return nil, errors.New("no-gate 维护必须给有效的健康探针(LIBRARY_TARGET_HEALTH_URL)") + } + default: + return nil, fmt.Errorf("LIBRARY_TARGET_INGRESS_MODE 无效(%q):只能是 %s 或 %s", + mode, libraryfreeze.IngressModeGate, libraryfreeze.IngressModeNone) } if cfg.Database == "" || cfg.Index == "" || cfg.Bucket == "" { return nil, errors.New("目标身份不完整:需要数据库/索引/存储桶") @@ -125,8 +157,9 @@ func New(cfg Config) (*Manager, error) { } manager := &Manager{target: target, source: project, docker: cfg.DockerSocket, writers: writers, nonWriters: cfg.NonWriters, timeout: cfg.Timeout, - client: &http.Client{Timeout: 5 * time.Second}, api: api} - if cfg.IngressService != "" || cfg.IngressDrainFile != "" { + client: &http.Client{Timeout: 5 * time.Second}, api: api, + mode: mode, ack: cfg.IngressAck, healthURL: health} + if mode == libraryfreeze.IngressModeGate && (cfg.IngressService != "" || cfg.IngressDrainFile != "") { gate, err := newDockerGate(cfg.DockerSocket, project, cfg.IngressService, cfg.IngressDrainFile, cfg.Timeout) if err != nil { return nil, err @@ -168,8 +201,12 @@ func (m *Manager) Target() Target { return m.target } // Description 是写进维护记录的一句话身份,含指纹,便于事后核对"当时动的是谁"。 func (m *Manager) Description() string { t := m.target + ingress := t.Ingress + if m.mode == libraryfreeze.IngressModeNone { + ingress = "none(test-only)" + } return fmt.Sprintf("level=%s instance=%s project=%s writers=%s ingress=%s db=%s index=%s bucket=%s fingerprint=%s", - t.Level, t.Instance, t.Project, strings.Join(t.Writers, "+"), t.Ingress, t.Database, t.Index, t.Bucket, t.Fingerprint) + t.Level, t.Instance, t.Project, strings.Join(t.Writers, "+"), ingress, t.Database, t.Index, t.Bucket, t.Fingerprint) } // Open 返回绑定到该目标的协调器与控制器。调用方负责 Close。 @@ -183,7 +220,23 @@ func (m *Manager) Open(root string) (*libraryfreeze.Coordinator, *libraryfreeze. control.Close() return nil, nil, err } - if err := coordinator.SetTarget(LevelInstance, m.target.Ingress, m.ingressClosed, m.ingressReady); err != nil { + // 入口形态必须在绑定目标之前声明:default 是 gate,只有显式 no-gate 才降档。 + if err := coordinator.SetIngressMode(m.mode, m.ack); err != nil { + coordinator.Close() + control.Close() + return nil, nil, err + } + closed, ready := m.ingressClosed, m.ingressReady + if m.mode == libraryfreeze.IngressModeNone { + // 没有闸门:不声明任何入口关闭探针,恢复证据改由健康探针承担。 + closed, ready = nil, m.healthReady + if err := coordinator.SetHealthURL(m.healthURL); err != nil { + coordinator.Close() + control.Close() + return nil, nil, err + } + } + if err := coordinator.SetTarget(LevelInstance, m.target.Ingress, closed, ready); err != nil { coordinator.Close() control.Close() return nil, nil, err @@ -239,7 +292,11 @@ func (m *Manager) serviceOf(id string) string { } // VerifyRunning 确认目标入口真的在服务(部署与恢复后都要看,不看容器状态)。 +// no-gate 栈没有入口:用健康探针回答"目标回来了没有"。 func (m *Manager) VerifyRunning(ctx context.Context) error { + if m.mode == libraryfreeze.IngressModeNone { + return m.healthReady(ctx) + } return m.ingressReady(ctx) } @@ -308,6 +365,47 @@ func (m *Manager) ingressReady(ctx context.Context) error { } } +// healthReady 是 no-gate 栈的恢复判据:健康探针返回 200 才算"目标真的回来了"。 +// 和入口探针同一条规则——不看容器状态、不看 HTTP 5xx 的"像活着"。 +func (m *Manager) healthReady(ctx context.Context) error { + deadline := time.Now().Add(m.timeout) + var last error + for { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, m.healthURL, nil) + if err != nil { + return err + } + // 探针不能留下 keep-alive 连接:那会让"排空"永远等不到。 + req.Close = true + resp, err := m.client.Do(req) + if err == nil { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096)) + resp.Body.Close() + if resp.StatusCode == http.StatusOK { + return nil + } + last = fmt.Errorf("健康探针返回 HTTP %d:%s", resp.StatusCode, strings.TrimSpace(string(body))) + } else { + last = err + } + if time.Now().After(deadline) { + return fmt.Errorf("目标健康探针没有恢复:%w", last) + } + select { + case <-ctx.Done(): + return last + case <-time.After(500 * time.Millisecond): + } + } +} + +// validHealthURL 是健康探针地址的本地校验:http(s)、有主机、不带凭据。 +func validHealthURL(raw string) bool { + parsed, err := url.Parse(strings.TrimSpace(raw)) + return err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") && + parsed.Host != "" && parsed.User == nil +} + // DatabaseIdentity 把连接串收敛成"host:port/db"这种可以写进维护记录的身份: // 维护记录里不落库凭据,但必须能说清动的是哪个库。 func DatabaseIdentity(raw string) (string, error) { @@ -354,12 +452,21 @@ func (m *Manager) VerifyTopology(ctx context.Context) error { if err != nil { return err } + // no-gate 栈没有闸门可绕:写入者发布端口是它的正常对外形态, + // "绕闸直连"这条判据在这里不成立(有闸门时才必须唯一入口)。 + if m.mode == libraryfreeze.IngressModeNone { + continue + } if ports := state.publishedPorts(); len(ports) > 0 { return fmt.Errorf("写入者 %s 直接发布了端口 %s:存在绕开入口闸门的直连通道,拒绝开维护窗口", writer, strings.Join(ports, ",")) } } if m.gate == nil { + if m.mode == libraryfreeze.IngressModeNone { + // 没有闸门可核验端口归属:拓扑检查到此为止,证据降档由维护记录承担。 + return nil + } return errors.New("实例级维护必须声明入口闸门") } for _, writer := range m.writers { diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx index 2af5e0a..1902533 100644 --- a/web/src/ReleaseTargets.tsx +++ b/web/src/ReleaseTargets.tsx @@ -384,7 +384,15 @@ const stageLabel: Record = { } const ingressText = (state?: string) => - state === 'closed' ? '已关闭(排空后等待写入)' : state === 'open' ? '打开' : state ? state : '未知' + state === 'closed' + ? '已关闭(排空后等待写入)' + : state === 'none' + ? '无闸门(测试模式)' + : state === 'open' + ? '打开' + : state + ? state + : '未知' // 持有作业详情没读到时只写未读取/未知,绝不拿同 scope 最新作业顶替。 const ownerJobText = (lookup: LibraryJobLookup | undefined, ownerJobID: string) => { diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts index 8375b2f..b0d4646 100644 --- a/web/src/librarySnapshots.ts +++ b/web/src/librarySnapshots.ts @@ -545,6 +545,9 @@ export interface LibraryMaintenanceCapability { project?: string writers?: string[] ingress_service?: string + // gate(默认)或 none:没有闸门的测试栈必须显示"无闸门(测试模式)"。 + ingress_mode?: string + ingress_state?: string note?: string }