Files
knowledge-governance/internal/libraryhandoff/env.go
T
姚章浩 6400fd1bbe feat(library): 快照搬运先于维护、双向校验与云端版本回传
为什么改:云端 release-executor 与目标同机后,本机封存的快照必须"先到、先验证"
才允许开维护窗口。此前只有 pack/unpack 两条人工命令:UI 点发布时执行器读到的是
本机归档路径,云端根本没有这份快照,作业只能在装配阶段失败;而预备份落在云端,
本机页面也读不到。用户已批准补齐这条链路。

搬运(新包 internal/libraryhandoff):本机 Load 逐 blob 重算 → Pack → SSH 流式写入
云端暂存 → 原子改名 → 云端 snapshot-unpack 再逐 blob 校验 → 读回版本清单摘要自证 →
scope/tenant/知识库身份与治理库作业一致。只有全部通过才投递 library.sync|restore,
失败时发布作业根本不存在(目标不进维护、不写知识)。远端命令是固定 argv,容器名与
路径只来自部署配置;同 ID 异内容拒绝;同一快照本机 flock 串行化;暂存 bundle 用后即删,
归档本体永不自动清理。

回传:capture 角色按已成功作业的 snapshot_id 扫描,把本机缺失的云端快照 Fetch 回来
(云端 pack → SSH 流回 → 本机 Unpack 逐 blob 校验)。回传成功后 API/页面既有的列表、
详情、差异、存储与历史恢复路径读到的就是真实字节;失败则版本不出现在本机,不会被误报成可恢复。

角色:搬运与回传只注册在 capture;若接线到 full(同时消费发布作业)启动即失败,
避免与云端执行器抢同一批作业。release-executor 仍不拥有治理库 DDL,也不消费
QA/邮件/来源扫描。

验证:internal/libraryhandoff 全绿(跨进程 push/fetch、身份不符拒绝、幂等复用、
并发串行、篡改与未知快照不落版本、路径穿越拒绝、远端错误不当作"没有");
cmd/worker 在隔离 fixture 库(独立测试 PG)上验证"校验通过才入队发布、失败不入队";
httpapi 队列决策单测;相关包 go test 全绿;go vet 全仓通过。

未部署、未推送、未构建镜像:云端接线与验收仍由父执行。真实云链路(含 SSH 通道)
本轮没有云侧写操作,只有本机跨进程与隔离 fixture 证据。
2026-10-30 18:58:34 +08:00

106 lines
4.0 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 libraryhandoff
import (
"errors"
"strconv"
"strings"
"time"
)
// 环境变量名集中在这里:API(决定要不要先做搬运)与 capture worker(真正执行搬运)
// 必须看同一组名字,写两遍迟早分叉成"一边以为接线了、另一边没接线"。
const (
EnvSSHConfig = "LIBRARY_HANDOFF_SSH_CONFIG"
EnvTarget = "LIBRARY_HANDOFF_TARGET"
EnvExecutor = "LIBRARY_HANDOFF_EXECUTOR"
EnvBundleDir = "LIBRARY_HANDOFF_BUNDLE_DIR"
EnvRemoteArchive = "LIBRARY_HANDOFF_REMOTE_ARCHIVE"
EnvStagingDir = "LIBRARY_HANDOFF_STAGING_DIR"
EnvLocalArchive = "LIBRARY_HANDOFF_LOCAL_ARCHIVE"
EnvMaxBytes = "LIBRARY_HANDOFF_MAX_BYTES"
EnvTimeout = "LIBRARY_HANDOFF_TIMEOUT"
EnvTransport = "LIBRARY_HANDOFF_TRANSPORT"
EnvLocalRoot = "LIBRARY_HANDOFF_LOCAL_ROOT"
// EnvPullInterval 控制"云端版本回传本机"的扫描间隔(capture 角色)。
EnvPullInterval = "LIBRARY_HANDOFF_PULL_INTERVAL"
)
// FromEnv 解析搬运配置。
//
// 返回 configured=false 只表示"这项能力没接线",不是错误:未接线时 API 保持旧行为
// (直接投递 library.sync/restore),本机目标部署完全不受影响。
//
// 但一旦任何一项接线字段出现,就必须**全部齐备**,否则报错——半接线是最坏的情况:
// API 以为会搬运,worker 却搬不动,发布作业会以"快照不在执行器"失败。
func FromEnv(get func(string) string) (Config, bool, error) {
if get == nil {
return Config{}, false, errors.New("缺少配置读取入口")
}
value := func(key string) string { return strings.TrimSpace(get(key)) }
config := Config{
SSHConfig: value(EnvSSHConfig),
SSHTarget: value(EnvTarget),
ExecutorContainer: value(EnvExecutor),
BundleDir: value(EnvBundleDir),
RemoteArchive: value(EnvRemoteArchive),
StagingDir: value(EnvStagingDir),
LocalArchive: value(EnvLocalArchive),
Transport: value(EnvTransport),
LocalRoot: value(EnvLocalRoot),
OpTimeout: 10 * time.Minute,
PullInterval: 5 * time.Minute,
}
if config.Transport == "" {
config.Transport = TransportSSH
}
if raw := value(EnvMaxBytes); raw != "" {
parsed, err := strconv.ParseInt(raw, 10, 64)
if err != nil || parsed <= 0 {
return Config{}, false, errors.New("LIBRARY_HANDOFF_MAX_BYTES 必须是正整数")
}
config.MaxBundleBytes = parsed
}
if raw := value(EnvPullInterval); raw != "" {
parsed, err := time.ParseDuration(raw)
if err != nil || parsed <= 0 {
return Config{}, false, errors.New("LIBRARY_HANDOFF_PULL_INTERVAL 必须是正的时间长度(如 5m)")
}
config.PullInterval = parsed
}
if raw := value(EnvTimeout); raw != "" {
parsed, err := time.ParseDuration(raw)
if err != nil || parsed <= 0 {
return Config{}, false, errors.New("LIBRARY_HANDOFF_TIMEOUT 必须是正的时间长度(如 10m)")
}
config.OpTimeout = parsed
}
configuredFields := 0
for _, item := range []string{EnvSSHConfig, EnvTarget, EnvExecutor, EnvBundleDir, EnvRemoteArchive, EnvStagingDir} {
if value(item) != "" {
configuredFields++
}
}
if configuredFields == 0 && value(EnvTransport) != TransportLocal {
return Config{}, false, nil
}
if config.Transport == TransportLocal {
if value(EnvLocalRoot) == "" {
return Config{}, false, errors.New("LIBRARY_HANDOFF_TRANSPORT=local 必须同时给出 LIBRARY_HANDOFF_LOCAL_ROOT(仅限隔离 fixture)")
}
if value(EnvSSHConfig) != "" || value(EnvTarget) != "" {
return Config{}, false, errors.New("local 通道不允许同时配置 SSH 目标:fixture 不能冒充云端通道")
}
if config.LocalArchive == "" {
config.LocalArchive = value("LIBRARY_ARCHIVE_ROOT")
}
if config.ExecutorContainer == "" {
// fixture 不跑容器:给一个固定名字只为让配置校验完整,不会被执行。
config.ExecutorContainer = "fixture-executor"
}
}
if err := config.validate(); err != nil {
return Config{}, false, err
}
return config, true, nil
}