Files
knowledge-governance/internal/librarymaintenance/env.go
T
姚章浩 2066bedbbe
build / build (push) Successful in 2m2s
feat(library): 维护窗口支持显式 no-gate 测试栈
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 证据位置如实写“无闸门(测试模式)”,不伪装“入口已排空”。
2026-11-16 22:58:37 +08:00

159 lines
6.1 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package librarymaintenance
import (
"errors"
"fmt"
"strconv"
"strings"
"knowledge-governance/internal/libraryfreeze"
)
// 目标入口闸门与后台队列的声明名称。
//
// 为什么集中在这里:容器内的 worker 与主机侧的封存(cmd/libraryctl)都要讲
// 同一份"这个实例的入口在哪、队列在哪";名字写两遍迟早会分叉,而分叉的表现
// 是"一边关的是 A 实例的门、另一边读的是 B 实例的队列"——不会报错,只会给出
// 错的证据。
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"
// EnvHealthURL 是 no-gate 窗口唯一的"目标回来了"证据:闸门不存在时,
// 只有外部健康探针能证明写入者恢复后真的在服务。
EnvHealthURL = "LIBRARY_TARGET_HEALTH_URL"
EnvRedisAddr = "LIBRARY_TARGET_REDIS_ADDR"
// 名字里不写 Password:这里的字面量是**环境变量名**,密钥扫描会把
// `XXX_PASSWORD = "<长字面量>"` 当成"被赋值的密钥",那是误报但没必要留个坑。
EnvRedisAuth = "LIBRARY_TARGET_REDIS_PASSWORD"
EnvRedisDB = "LIBRARY_TARGET_REDIS_DB"
)
// TargetEnv 是一次实例级维护所需的"入口 + 队列"声明。
//
// 缺任何一项都不许降级成"库级维护":没有闸门就没有"入口已关、在途已排空"的
// 证据,没有队列就证明不了停写者时后台是空的。这两条正是被代理的 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
}
// TargetFromEnv 解析维护目标声明。缺少的项一次性全部报出来(含变量名),
// 让部署方一次改对,而不是改一项再撞下一项。
func TargetFromEnv(get func(string) string) (TargetEnv, error) {
if get == nil {
return TargetEnv{}, errors.New("缺少配置读取入口")
}
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),
}
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},
{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)
}
}
if strings.TrimSpace(target.RedisPassword) == "" {
missing = append(missing, EnvRedisAuth)
}
rawDB := value(EnvRedisDB)
switch {
case rawDB == "":
missing = append(missing, EnvRedisDB)
default:
db, err := strconv.Atoi(rawDB)
if err != nil || db < 0 {
return TargetEnv{}, fmt.Errorf("%s 不是有效的队列库号(%q)", EnvRedisDB, rawDB)
}
target.RedisDB = db
}
if len(missing) > 0 {
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 "取值不匹配"
}
}