feat(library): 维护窗口支持显式 no-gate 测试栈
build / build (push) Successful in 2m2s

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 证据位置如实写“无闸门(测试模式)”,不伪装“入口已排空”。
This commit is contained in:
姚章浩
2026-11-16 22:58:37 +08:00
parent 5f1a8f565c
commit 2066bedbbe
18 changed files with 1014 additions and 104 deletions
+27
View File
@@ -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
+2
View File
@@ -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(),
+8
View File
@@ -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,
@@ -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 与闸门服务同时存在却没有拒绝")
}
}
+8
View File
@@ -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 <URL>` 用来覆盖"源对象存储的访问入口":容器里写的
`MINIO_ENDPOINT` 往往是服务名(`langfuse-minio:9000`),封存跑在宿主机上时解析不到,
资源导出会失败(`read library resource`)。覆盖只换入口,桶与对象键不变;`status`
+63 -18
View File
@@ -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 {
+23 -5
View File
@@ -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 在作业内校验并执行",
}
+6 -2
View File
@@ -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;留空即页面不能发起封存。
+167 -11
View File
@@ -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("入口闸门缺失:不能确认目标已恢复"))
@@ -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[:]),
}
+233
View File
@@ -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 窗口伪造了闸门重开")
}
}
+8 -1
View File
@@ -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
+110 -44
View File
@@ -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++
+76 -11
View File
@@ -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 "取值不匹配"
}
}
@@ -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)
}
}
+118 -11
View File
@@ -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 {
+9 -1
View File
@@ -384,7 +384,15 @@ const stageLabel: Record<string, string> = {
}
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) => {
+3
View File
@@ -545,6 +545,9 @@ export interface LibraryMaintenanceCapability {
project?: string
writers?: string[]
ingress_service?: string
// gate(默认)或 none:没有闸门的测试栈必须显示"无闸门(测试模式)"。
ingress_mode?: string
ingress_state?: string
note?: string
}