Files
knowledge-governance/internal/librarymaintenance/target.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

510 lines
17 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 把"目标维护窗口"落成一个可验证的实例级动作:
// 关闭目标入口 → 停下全部声明的写入者 → 验证在途排空 → 交给发布链路写目标
// → 恢复原本在跑的服务与入口。
//
// 它不产生授权、不读生产凭据,也不把"只锁了治理库 scope"当成系统维护。
package librarymaintenance
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"path/filepath"
"sort"
"strings"
"time"
"knowledge-governance/internal/libraryfreeze"
)
// LevelInstance 表示写入者被共享给整个实例:停它影响所有知识库,
// 因此窗口必须按"实例级维护"对外标注,而不是"某个库在维护"。
const LevelInstance = "instance"
// Target 是目标的精确身份:实例、入口、写入者、要写的库/索引/桶。
// Fingerprint 覆盖全部字段,用来发现"配置换了但作业还按旧目标跑"。
type Target struct {
Instance string `json:"instance"`
Level string `json:"level"`
Project string `json:"project,omitempty"`
Writers []string `json:"writers,omitempty"`
Ingress string `json:"ingress,omitempty"`
Database string `json:"database"`
Index string `json:"index"`
Bucket string `json:"bucket"`
Fingerprint string `json:"fingerprint,omitempty"`
}
// Config 来自部署注入的配置。任何一项缺失都不许"降级成库级维护"蒙过去。
type Config struct {
Instance string
Project string
Writers []string
NonWriters map[string]string
DockerSocket string
// IngressMode 是 gate(默认)或 none;none 只给整栈没有入口闸门的测试环境用,
// 必须同时给 IngressAck,且一次闸门动作都不做。
IngressMode string
IngressAck string
IngressURL string
// IngressService 是入口闸门在 compose 项目里的服务名;DrainFile 是它写
// 排空证据的宿主机文件。两者缺一,就只能说"停了写入者",不能说"排空了"。
IngressService string
IngressDrainFile string
// HealthURL 是 no-gate 模式下唯一的"目标回来了"证据(恢复后必须 200)。
HealthURL string
Database string
Index string
Bucket string
// 后台静默检查需要的运行时依赖(不写进维护记录)。
DatabaseURL string
RedisAddr string
RedisPassword string
RedisDB int
Timeout time.Duration
}
type Manager struct {
target Target
source string
docker string
writers []string
nonWriters map[string]string
timeout time.Duration
client *http.Client
gate *dockerGate
api *dockerAPI
quiescer *targetQuiescer
mode string
ack string
healthURL string
}
// Close 释放拓扑/静默检查持有的连接。
func (m *Manager) Close() {
if m.api != nil {
m.api.Close()
}
if m.quiescer != nil {
m.quiescer.Close()
}
}
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")
}
if len(cfg.Writers) == 0 {
return nil, errors.New("实例级维护配置缺少写入者声明 LIBRARY_TARGET_WRITERS")
}
if !filepath.IsAbs(cfg.DockerSocket) {
return nil, errors.New("Docker socket 必须是绝对路径")
}
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("目标身份不完整:需要数据库/索引/存储桶")
}
if cfg.Timeout <= 0 {
cfg.Timeout = 2 * time.Minute
}
writers := append([]string(nil), cfg.Writers...)
sort.Strings(writers)
target := Target{Instance: instance, Level: LevelInstance, Project: project, Writers: writers,
Ingress: ingress, Database: cfg.Database, Index: cfg.Index, Bucket: cfg.Bucket}
fingerprint, err := fingerprintOf(target)
if err != nil {
return nil, err
}
target.Fingerprint = fingerprint
api, err := newDockerAPI(cfg.DockerSocket, cfg.Timeout)
if err != nil {
return nil, err
}
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,
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
}
manager.gate = gate
}
if cfg.DatabaseURL != "" && cfg.RedisAddr != "" {
quiescer, err := newTargetQuiescer(context.Background(), cfg.DatabaseURL, cfg.RedisAddr,
cfg.RedisPassword, cfg.RedisDB, cfg.Timeout)
if err != nil {
return nil, err
}
manager.quiescer = quiescer
}
return manager, nil
}
func fingerprintOf(t Target) (string, error) {
canonical := struct {
Instance string `json:"instance"`
Level string `json:"level"`
Project string `json:"project"`
Writers []string `json:"writers"`
Ingress string `json:"ingress"`
Database string `json:"database"`
Index string `json:"index"`
Bucket string `json:"bucket"`
}{t.Instance, t.Level, t.Project, t.Writers, t.Ingress, t.Database, t.Index, t.Bucket}
raw, err := json.Marshal(canonical)
if err != nil {
return "", err
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:]), nil
}
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, "+"), ingress, t.Database, t.Index, t.Bucket, t.Fingerprint)
}
// Open 返回绑定到该目标的协调器与控制器。调用方负责 Close。
func (m *Manager) Open(root string) (*libraryfreeze.Coordinator, *libraryfreeze.ProjectController, error) {
control, err := libraryfreeze.NewProjectController(m.docker, m.source, m.writers, m.nonWriters, m.timeout)
if err != nil {
return nil, nil, err
}
coordinator, err := libraryfreeze.Open(root, m.source, control)
if err != nil {
control.Close()
return nil, nil, err
}
// 入口形态必须在绑定目标之前声明: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
}
if err := coordinator.SetTargetFingerprint(m.target.Fingerprint); err != nil {
coordinator.Close()
control.Close()
return nil, nil, err
}
if m.gate != nil {
if err := coordinator.SetGate(m.gate); err != nil {
coordinator.Close()
control.Close()
return nil, nil, err
}
}
// 后台静默检查是实例级窗口的必备条件:没有它就等于只排空了 HTTP。
if m.quiescer == nil {
coordinator.Close()
control.Close()
return nil, nil, errors.New("缺少后台静默检查(目标库/队列未配置),拒绝开实例级窗口")
}
if err := coordinator.SetQuiescer(m.quiescer); err != nil {
coordinator.Close()
control.Close()
return nil, nil, err
}
return coordinator, control, nil
}
// OriginalState 是"动之前"的原服务状态,落在维护记录里:
// 只按它恢复,绝不顺手把原本没跑的服务拉起来。
func (m *Manager) OriginalState(ctx context.Context) (string, error) {
control, err := libraryfreeze.NewProjectController(m.docker, m.source, m.writers, m.nonWriters, m.timeout)
if err != nil {
return "", err
}
defer control.Close()
items, err := control.Inventory(ctx)
if err != nil {
return "", err
}
parts := make([]string, 0, len(items))
for _, item := range items {
parts = append(parts, fmt.Sprintf("%s=%s running=%t healthy=%t", m.serviceOf(item.ID), item.ID, item.Running, item.Healthy))
}
sort.Strings(parts)
return strings.Join(parts, "; "), nil
}
func (m *Manager) serviceOf(id string) string {
return "container:" + id
}
// VerifyRunning 确认目标入口真的在服务(部署与恢复后都要看,不看容器状态)。
// no-gate 栈没有入口:用健康探针回答"目标回来了没有"。
func (m *Manager) VerifyRunning(ctx context.Context) error {
if m.mode == libraryfreeze.IngressModeNone {
return m.healthReady(ctx)
}
return m.ingressReady(ctx)
}
// ingressClosed:入口关掉的证据是"连不上",不是"返回错误页"——
// 502/503 说明还有一层代理在对外服务,那不是维护窗口。
func (m *Manager) ingressClosed(ctx context.Context) error {
deadline := time.Now().Add(m.timeout)
var last error
for {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, m.target.Ingress, nil)
if err != nil {
return err
}
// Maintenance probes must not leave keep-alive connections in the TCP
// ingress: the probe itself would otherwise prevent draining.
req.Close = true
resp, err := m.client.Do(req)
if err != nil {
return nil
}
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
resp.Body.Close()
last = fmt.Errorf("入口仍返回 HTTP %d", resp.StatusCode)
if time.Now().After(deadline) {
return last
}
select {
case <-ctx.Done():
return last
case <-time.After(200 * time.Millisecond):
}
}
}
// ingressReady:入口回来 = 真的能返回 200,而不是"容器起来了"。
func (m *Manager) ingressReady(ctx context.Context) error {
deadline := time.Now().Add(m.timeout)
var last error
for {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, m.target.Ingress, nil)
if err != nil {
return err
}
// Maintenance probes must not leave keep-alive connections in the TCP
// ingress: the probe itself would otherwise prevent draining.
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):
}
}
}
// 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) {
parsed, err := url.Parse(strings.TrimSpace(raw))
if err != nil || parsed.Host == "" {
return "", errors.New("目标数据库连接串无效")
}
database := strings.TrimPrefix(parsed.Path, "/")
if database == "" {
return "", errors.New("目标数据库连接串缺少库名")
}
return parsed.Host + "/" + database, nil
}
const composeServiceLabel = "com.docker.compose.service"
// VerifyTopology 强制"入口唯一":
// - 写入者不许发布任何宿主机端口(否则就存在绕闸直连,维护窗口覆盖不到);
// - 入口闸门必须存在、必须是独立服务,并且发布了入口 URL 用的那个端口。
//
// 任何一条不满足都拒绝开窗口——拓扑错了,"维护"就只是关了一半的门。
func (m *Manager) VerifyTopology(ctx context.Context) error {
items, err := m.api.listProject(ctx, m.target.Project)
if err != nil {
return err
}
byService := make(map[string]containerSummary, len(items))
for _, item := range items {
name := item.Labels[composeServiceLabel]
if name == "" {
return errors.New("项目里有容器缺少 compose service 标签,无法确认写入者边界")
}
if _, duplicated := byService[name]; duplicated {
return fmt.Errorf("项目里服务 %s 有多个实例,无法确认写入者边界", name)
}
byService[name] = item
}
for _, writer := range m.writers {
item, ok := byService[writer]
if !ok {
return fmt.Errorf("声明的写入者 %s 不存在", writer)
}
state, err := m.api.inspect(ctx, item.ID)
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 {
if writer == m.gate.service {
return errors.New("入口闸门不能同时被声明为写入者")
}
}
gateItem, ok := byService[m.gate.service]
if !ok {
return fmt.Errorf("声明的入口闸门 %s 不存在", m.gate.service)
}
gateState, err := m.api.inspect(ctx, gateItem.ID)
if err != nil {
return err
}
published := gateState.publishedPorts()
if len(published) == 0 {
return fmt.Errorf("入口闸门 %s 没有发布任何端口:外部无法访问,入口定义不成立", m.gate.service)
}
// 入口 URL 的端口必须真的是这个闸门发布的端口。
parsed, err := url.Parse(m.target.Ingress)
if err != nil || parsed.Host == "" {
return errors.New("目标入口地址无效")
}
hostPort := parsed.Port()
if hostPort == "" {
if parsed.Scheme == "https" {
hostPort = "443"
} else {
hostPort = "80"
}
}
for _, entry := range published {
if strings.Contains(entry, ":"+hostPort+"->") {
return nil
}
}
return fmt.Errorf("入口 %s 的端口 %s 不是闸门发布的端口(%s):入口指向了别的服务",
m.target.Ingress, hostPort, strings.Join(published, ","))
}