Files
knowledge-governance/internal/appconfig/config.go
T
姚章浩 0a7c9f8510 feat(worker): 接线恢复派发台账并按激活登记启用
为什么:派发协议只在 worker 里装配却没人接,就等于只写了 store
mock。同步失败的自动 rollback 与维护恢复都必须拿到同一份台账;
baseline 只读装配永远不传,避免建基线顺带获得恢复写许可。

开关 LIBRARY_RESTORE_DISPATCH_V2 默认关闭,且只是"允许装配":
治理库没有该目标的未撤销激活登记时,Prepare/Acquire 直接 fail closed。

验证:cmd/worker 单测覆盖默认关闭/显式开启/无台账三态;
v071 真 ES 用例里自动 rollback 与手动恢复走的是同一个 Restore。
2026-11-02 16:28:01 +08:00

641 lines
32 KiB
Go

package appconfig
import (
"errors"
"fmt"
"path/filepath"
"strconv"
"strings"
"time"
"knowledge-governance/internal/governance"
)
type Config struct {
DatabaseURL string
AppAddr string
WorkerID string
PollInterval time.Duration
LeaseDuration time.Duration
RetryDelay time.Duration
SourceRefreshSchedulerInterval time.Duration
ReleaseWorkerEnabled bool
ReleaseConfigFile string
ProductionReleaseRequestsEnabled bool
ProductionBackupRestoreVerified bool
// LibraryRestoreDispatchEnabled 允许 worker 装配 DS01 派发台账;默认 false。
// 它不能单独证明独占:治理库里的目标激活登记同样必需。
LibraryRestoreDispatchEnabled bool
ProductionReleaseAuthorizerRef string
ProductionReleaseAuthTokenFile string
// Production WeKnora endpoint: the release target itself stays declared in
// the release runtime config (RELEASE_CONFIG_FILE); these settings only let
// the API probe that endpoint so the console can show its real state.
ProductionWeKnoraBaseURL string
ProductionWeKnoraAPIKeyFile string
ProductionWeKnoraAllowDockerHTTP bool
PPScanEnabled bool
PPScanAllowedRoot string
PPScanLedgerPath string
PPScanManifestPath string
TestWeKnoraEnabled bool
TestWeKnoraAllowDockerHTTP bool
TestWeKnoraBaseURL string
MinerUBaseURL string
TestWeKnoraKBID string
InternalRoutingKnowledgeBaseID string
ExternalRoutingKnowledgeBaseID string
TestWeKnoraAPIKeyFile string
GovernanceSpoolRoot string
IngestionSpoolRoot string
ArtifactFetchMaxBytes int64
WorkerLivenessStaleAfter time.Duration
TestWeKnoraHTTPTimeout time.Duration
TestWeKnoraPollInitial time.Duration
TestWeKnoraPollMax time.Duration
TestWeKnoraStalledAfter time.Duration
TestWeKnoraMaxUploadBytes int64
TestAcceptancePolicyVersion string
// TestAutoReviewPolicy:验收通过后是否自动批准(off|internal|all;默认 internal)。
TestAutoReviewPolicy string
// 目标库所在主机(整库逻辑备份真正执行的地方)。凭据是挂载进来的 0600 ssh
// 配置文件与私钥;三项同时给出才接线,缺任一项即"未接线"(页面降级展示)。
BackupHostSSHConfig string
BackupHostTarget string
BackupHostScriptDir string
BackupHostRoot string
// 版本记录(「版本记录」页):**匿名只读**远端仓库的提交与 tag。来源留空即"未接线"
// (页面降级展示,接口返回可用性=false)。只允许配置里批准的 origin 与仓库,
// 不接受任何调用方传入的 URL;本功能**不使用凭据**。
VersionHistoryGiteaBaseURL string
VersionHistoryRepo string
VersionHistoryAllowedOrigins []string
// VersionHistoryLinkOrigin 是**页面链接**用的 origin(给内网外的浏览器点开),
// 留空即与抓取 origin 相同。只用于拼展示链接,不参与任何请求。
// LibraryArchiveRoot 是整库封存产物的只读归档根(主机私有 0700 目录的只读挂载)。
// 留空即"未接线":页面只显示原因,不显示空表冒充没有快照。
LibraryArchiveRoot string
// 生产整库目标(只由部署注入;缺任何一项都视为未配置,生产执行保持关闭)。
LibraryProductionDatabaseURL string
LibraryProductionElasticURL string
LibraryProductionIndex string
LibraryProductionTenantID uint64
LibraryProductionInternalKB string
LibraryProductionExternalKB string
// LibraryProductionS3Provider 必须与生产库 resources.provider 的取值一致:
// 对象路径按 provider 路由,写错会在上传时被拒绝(而不是写错桶)。
LibraryProductionS3Provider string
LibraryProductionS3Endpoint string
LibraryProductionS3Region string
LibraryProductionS3Bucket string
LibraryProductionS3AccessKey string
LibraryProductionS3SecretKey string
LibraryObjectGatewayURL string
LibraryObjectGatewayToken string
LibraryObjectGatewayGrantDirectory string
// LibraryEmbeddingModel 是整库发布使用的向量模型声明(快照契约缺失时的回落值)。
LibraryEmbeddingModel string
// LibraryWorkerRole 决定这个进程消费哪一段队列(见 LibraryWorkerRole 说明)。
LibraryWorkerRole LibraryWorkerRole
LibraryEmbeddingDimension int
// LibraryCapacityBudgetBytes 是整库归档容量预算;0 表示未设置(容量门禁不放行)。
LibraryCapacityBudgetBytes int64
// LibraryRetentionVersions / Days 是保留策略;都为 0 表示未设置(不生成清理候选)。
LibraryRetentionVersions int
LibraryRetentionDays int
// 目标维护(实例级):同步/恢复期间关闭目标入口、停下写入者、排空在途请求。
// 任一项留空即"未接线",生产写入会被拒绝——只锁治理库 scope 不算维护。
LibraryTargetInstance string
// LibrarySourceInstance 是死信解除记录绑定的"来源实例"名字(封存源,不是同步目标)。
// 留空时回落到 LibraryTargetInstance,保持单实例部署的旧行为。
LibrarySourceInstance string
// LibrarySourceProject 是封存执行器应该指向的实例名(agent -project)。
// 留空时等于来源实例名:环境里两者本来就同名(kgmaint-weknora)。
LibrarySourceProject string
// LibrarySourceApp 是封存源容器名(agent -source-app)。project 可能同名而源接线
// 不同,所以配了就一起绑定进"期望执行器身份"。
LibrarySourceApp string
// 源绑定的知识库身份:封存快照的清单里写的是**源**的 tenant/KB,和目标知识库
// 本来就不是同一个(云测试验收用专用 KB)。搬运必须拿这份独立注入的源绑定去核对,
// 不能拿目标绑定去对,更不能信快照自报。
LibrarySourceTenantID uint64
LibrarySourceInternalKB string
LibrarySourceExternalKB string
LibraryTargetProject string
LibraryTargetWriters []string
LibraryTargetNonWriters map[string]string
LibraryTargetDockerSocket string
LibraryTargetIngressURL string
// 入口闸门:关入口与排空在它身上做(被代理服务自己不排空)。
LibraryTargetIngressService string
LibraryTargetIngressDrainFile string
// 后台静默检查:目标队列 + 目标库(HTTP 排空不等于后台任务排空)。
LibraryTargetRedisAddr string
LibraryTargetRedisPassword string
LibraryTargetRedisDB int
LibraryTargetJournalRoot string
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket(只由 worker 连接)。
// 留空即"未接线":页面不显示可用的封存入口,接口返回原因而不是假装已排队。
LibraryAgentSocket string
// LibraryExecutorStatusMaxAge 是执行器状态的有效期:超过它就是"无法确认",
// 不是"仍然可用"。worker 每 30 秒观测一次,默认 120 秒足够容错。
LibraryExecutorStatusMaxAge time.Duration
VersionHistoryLinkOrigin string
VersionHistoryHTTPTimeout time.Duration
VersionHistoryMaxPages int
}
func Load(getenv func(string) string) (Config, error) {
// 容量与保留策略:未设置一律 0(= 不做决定),由使用方按 fail-closed 处理。
capacityBudget, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_CAPACITY_BUDGET_BYTES")), 0)
if err != nil {
return Config{}, errors.New("LIBRARY_CAPACITY_BUDGET_BYTES must be a positive integer")
}
retentionVersions64, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_RETENTION_VERSIONS")), 0)
if err != nil {
return Config{}, errors.New("LIBRARY_RETENTION_VERSIONS must be a positive integer")
}
retentionDays64, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_RETENTION_DAYS")), 0)
if err != nil {
return Config{}, errors.New("LIBRARY_RETENTION_DAYS must be a positive integer")
}
retentionVersions, retentionDays := int(retentionVersions64), int(retentionDays64)
tenantID64, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_PRODUCTION_TENANT_ID")), 0)
if err != nil {
return Config{}, errors.New("LIBRARY_PRODUCTION_TENANT_ID must be a positive integer")
}
tenantID := uint64(tenantID64)
sourceTenant64, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_SOURCE_TENANT_ID")), 0)
if err != nil {
return Config{}, errors.New("LIBRARY_SOURCE_TENANT_ID must be a positive integer")
}
sourceTenantID := uint64(sourceTenant64)
embeddingDimension64, err := positiveInt64OrDefault(strings.TrimSpace(getenv("LIBRARY_EMBEDDING_DIMENSION")), 1024)
if err != nil {
return Config{}, errors.New("LIBRARY_EMBEDDING_DIMENSION must be a positive integer")
}
embeddingDimension := int(embeddingDimension64)
config := Config{
DatabaseURL: getenv("DATABASE_URL"),
AppAddr: valueOrDefault(getenv("APP_ADDR"), ":8080"),
WorkerID: valueOrDefault(getenv("WORKER_ID"), "worker-1"),
PollInterval: time.Second,
LeaseDuration: 30 * time.Second,
RetryDelay: 5 * time.Second,
SourceRefreshSchedulerInterval: 30 * time.Second,
ReleaseConfigFile: strings.TrimSpace(getenv("RELEASE_CONFIG_FILE")),
ProductionReleaseAuthorizerRef: strings.TrimSpace(getenv("PRODUCTION_RELEASE_AUTHORIZER_REF")),
ProductionReleaseAuthTokenFile: strings.TrimSpace(getenv("PRODUCTION_RELEASE_AUTH_TOKEN_FILE")),
ProductionWeKnoraBaseURL: strings.TrimSpace(getenv("PRODUCTION_WEKNORA_BASE_URL")),
ProductionWeKnoraAPIKeyFile: strings.TrimSpace(getenv("PRODUCTION_WEKNORA_API_KEY_FILE")),
PPScanAllowedRoot: strings.TrimSpace(getenv("PP_SCAN_ALLOWED_ROOT")),
PPScanLedgerPath: strings.TrimSpace(getenv("PP_SCAN_LEDGER_PATH")),
PPScanManifestPath: strings.TrimSpace(getenv("PP_SCAN_MANIFEST_PATH")),
TestWeKnoraBaseURL: strings.TrimSpace(getenv("TEST_WEKNORA_BASE_URL")),
MinerUBaseURL: strings.TrimSpace(getenv("MINERU_BASE_URL")),
TestWeKnoraKBID: strings.TrimSpace(getenv("TEST_WEKNORA_KB_ID")),
InternalRoutingKnowledgeBaseID: strings.TrimSpace(getenv("TEST_INTERNAL_WEKNORA_KB_ID")),
ExternalRoutingKnowledgeBaseID: strings.TrimSpace(getenv("TEST_EXTERNAL_WEKNORA_KB_ID")),
TestWeKnoraAPIKeyFile: valueOrDefault(getenv("TEST_WEKNORA_API_KEY_FILE"), "/run/secrets/test_weknora_api_key"),
GovernanceSpoolRoot: valueOrDefault(getenv("GOVERNANCE_SPOOL_ROOT"), "/var/lib/governance/spool"),
IngestionSpoolRoot: strings.TrimSpace(getenv("INGESTION_SPOOL_ROOT")),
ArtifactFetchMaxBytes: 200 * 1024 * 1024,
WorkerLivenessStaleAfter: 2 * time.Minute,
TestWeKnoraHTTPTimeout: 60 * time.Second,
TestWeKnoraPollInitial: 10 * time.Second,
TestWeKnoraPollMax: time.Minute,
TestWeKnoraStalledAfter: 30 * time.Minute,
TestWeKnoraMaxUploadBytes: 50 * 1024 * 1024,
TestAcceptancePolicyVersion: valueOrDefault(getenv("TEST_ACCEPTANCE_POLICY_VERSION"), "structural-v1"),
TestAutoReviewPolicy: valueOrDefault(getenv("TEST_AUTO_REVIEW_POLICY"), string(governance.AutoReviewInternal)),
// 整库逻辑备份的目标主机:三项同时给出才接线(脚本目录/备份根有默认值)。
BackupHostSSHConfig: strings.TrimSpace(getenv("BACKUP_HOST_SSH_CONFIG")),
BackupHostTarget: strings.TrimSpace(getenv("BACKUP_HOST_TARGET")),
BackupHostScriptDir: valueOrDefault(strings.TrimSpace(getenv("BACKUP_HOST_SCRIPT_DIR")), "/opt/weknora-test"),
BackupHostRoot: valueOrDefault(strings.TrimSpace(getenv("BACKUP_HOST_ROOT")), "/srv/kb-backups"),
VersionHistoryGiteaBaseURL: strings.TrimSpace(getenv("VERSION_HISTORY_GITEA_BASE_URL")),
VersionHistoryRepo: valueOrDefault(strings.TrimSpace(getenv("VERSION_HISTORY_REPO")), "Weknora/knowledge-governance"),
VersionHistoryAllowedOrigins: splitOrigins(getenv("VERSION_HISTORY_ALLOWED_ORIGINS")),
LibraryArchiveRoot: strings.TrimSpace(getenv("LIBRARY_ARCHIVE_ROOT")),
LibraryAgentSocket: strings.TrimSpace(getenv("LIBRARY_AGENT_SOCKET")),
LibraryProductionDatabaseURL: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_DATABASE_URL")),
LibraryProductionElasticURL: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_ELASTIC_URL")),
LibraryProductionIndex: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_PRODUCTION_INDEX")), "weknora_full_chunks"),
LibraryProductionTenantID: uint64(tenantID),
LibraryProductionInternalKB: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_KB_INTERNAL")),
LibraryProductionExternalKB: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_KB_EXTERNAL")),
LibraryProductionS3Provider: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_PROVIDER")), "s3"),
LibraryProductionS3Endpoint: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_ENDPOINT")),
LibraryProductionS3Region: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_REGION")), "us-east-1"),
LibraryProductionS3Bucket: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_BUCKET")),
LibraryProductionS3AccessKey: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_ACCESS_KEY")),
LibraryProductionS3SecretKey: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_SECRET_KEY")),
LibraryObjectGatewayURL: strings.TrimSpace(getenv("LIBRARY_OBJECT_GATEWAY_URL")),
LibraryObjectGatewayToken: strings.TrimSpace(getenv("LIBRARY_OBJECT_GATEWAY_TOKEN")),
LibraryObjectGatewayGrantDirectory: strings.TrimSpace(getenv("LIBRARY_OBJECT_GATEWAY_GRANT_DIRECTORY")),
LibraryTargetInstance: strings.TrimSpace(getenv("LIBRARY_TARGET_INSTANCE")),
LibrarySourceInstance: strings.TrimSpace(getenv("LIBRARY_SOURCE_INSTANCE")),
LibrarySourceProject: strings.TrimSpace(getenv("LIBRARY_SOURCE_PROJECT")),
LibrarySourceApp: strings.TrimSpace(getenv("LIBRARY_SOURCE_APP")),
LibrarySourceTenantID: uint64(sourceTenantID),
LibrarySourceInternalKB: strings.TrimSpace(getenv("LIBRARY_SOURCE_KB_INTERNAL")),
LibrarySourceExternalKB: strings.TrimSpace(getenv("LIBRARY_SOURCE_KB_EXTERNAL")),
LibraryTargetProject: strings.TrimSpace(getenv("LIBRARY_TARGET_PROJECT")),
LibraryTargetWriters: splitList(getenv("LIBRARY_TARGET_WRITERS")),
LibraryTargetNonWriters: splitDeclarations(getenv("LIBRARY_TARGET_NON_WRITERS")),
LibraryTargetDockerSocket: valueOrDefault(strings.TrimSpace(getenv("LIBRARY_TARGET_DOCKER_SOCKET")), "/var/run/docker.sock"),
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),
}
if config.DatabaseURL == "" {
return Config{}, errors.New("DATABASE_URL is required")
}
// 角色非法必须在启动时失败:一个拼错的角色会让进程悄悄回到"什么都消费"。
if config.LibraryWorkerRole, err = parseLibraryWorkerRole(getenv("LIBRARY_WORKER_ROLE")); err != nil {
return Config{}, err
}
if config.PollInterval, err = durationOrDefault(getenv("WORKER_POLL_INTERVAL"), config.PollInterval); err != nil {
return Config{}, fmt.Errorf("WORKER_POLL_INTERVAL: %w", err)
}
if config.LeaseDuration, err = durationOrDefault(getenv("WORKER_LEASE_DURATION"), config.LeaseDuration); err != nil {
return Config{}, fmt.Errorf("WORKER_LEASE_DURATION: %w", err)
}
if config.RetryDelay, err = durationOrDefault(getenv("WORKER_RETRY_DELAY"), config.RetryDelay); err != nil {
return Config{}, fmt.Errorf("WORKER_RETRY_DELAY: %w", err)
}
if config.SourceRefreshSchedulerInterval, err = durationOrDefault(getenv("SOURCE_REFRESH_SCHEDULER_INTERVAL"), config.SourceRefreshSchedulerInterval); err != nil {
return Config{}, fmt.Errorf("SOURCE_REFRESH_SCHEDULER_INTERVAL: %w", err)
}
if config.SourceRefreshSchedulerInterval < 5*time.Second {
return Config{}, errors.New("SOURCE_REFRESH_SCHEDULER_INTERVAL must be at least 5s")
}
if config.LibraryExecutorStatusMaxAge, err = durationOrDefault(getenv("LIBRARY_EXECUTOR_STATUS_MAX_AGE"), config.LibraryExecutorStatusMaxAge); err != nil {
return Config{}, fmt.Errorf("LIBRARY_EXECUTOR_STATUS_MAX_AGE: %w", err)
}
if raw := getenv("RELEASE_WORKER_ENABLED"); raw != "" {
config.ReleaseWorkerEnabled, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("RELEASE_WORKER_ENABLED: %w", err)
}
}
if config.ReleaseWorkerEnabled && (!filepath.IsAbs(config.ReleaseConfigFile) || filepath.Clean(config.ReleaseConfigFile) != config.ReleaseConfigFile) {
return Config{}, errors.New("RELEASE_CONFIG_FILE must be an absolute path when release worker is enabled")
}
if raw := getenv("PRODUCTION_RELEASE_REQUESTS_ENABLED"); raw != "" {
config.ProductionReleaseRequestsEnabled, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("PRODUCTION_RELEASE_REQUESTS_ENABLED: %w", err)
}
}
if raw := getenv("PRODUCTION_BACKUP_RESTORE_VERIFIED"); raw != "" {
config.ProductionBackupRestoreVerified, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("PRODUCTION_BACKUP_RESTORE_VERIFIED: %w", err)
}
}
// DS01 恢复标记派发协议:默认关闭。开关只是"允许装配"的意思,不是独占证明——
// 真正发放许可还要求治理库里对该目标存在未撤销的激活登记。
if raw := getenv("LIBRARY_RESTORE_DISPATCH_V2"); raw != "" {
config.LibraryRestoreDispatchEnabled, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("LIBRARY_RESTORE_DISPATCH_V2: %w", err)
}
}
if raw := getenv("PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP"); raw != "" {
config.ProductionWeKnoraAllowDockerHTTP, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP: %w", err)
}
}
if config.ProductionWeKnoraBaseURL != "" {
if err := validateHTTPBaseURL(config.ProductionWeKnoraBaseURL); err != nil {
return Config{}, fmt.Errorf("PRODUCTION_WEKNORA_BASE_URL: %w", err)
}
}
if config.ProductionWeKnoraAPIKeyFile != "" {
if config.ProductionWeKnoraBaseURL == "" {
return Config{}, errors.New("PRODUCTION_WEKNORA_API_KEY_FILE requires PRODUCTION_WEKNORA_BASE_URL")
}
if !filepath.IsAbs(config.ProductionWeKnoraAPIKeyFile) {
return Config{}, errors.New("PRODUCTION_WEKNORA_API_KEY_FILE must be an absolute path")
}
}
if raw := getenv("PP_SCAN_ENABLED"); raw != "" {
config.PPScanEnabled, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("PP_SCAN_ENABLED: %w", err)
}
}
if raw := getenv("TEST_WEKNORA_ENABLED"); raw != "" {
config.TestWeKnoraEnabled, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_ENABLED: %w", err)
}
}
if raw := getenv("TEST_WEKNORA_ALLOW_DOCKER_HTTP"); raw != "" {
config.TestWeKnoraAllowDockerHTTP, err = strconv.ParseBool(raw)
if err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_ALLOW_DOCKER_HTTP: %w", err)
}
}
if config.WorkerLivenessStaleAfter, err = durationOrDefault(getenv("WORKER_LIVENESS_STALE_AFTER"), config.WorkerLivenessStaleAfter); err != nil {
return Config{}, fmt.Errorf("WORKER_LIVENESS_STALE_AFTER: %w", err)
}
if config.VersionHistoryHTTPTimeout, err = durationOrDefault(getenv("VERSION_HISTORY_HTTP_TIMEOUT"), config.VersionHistoryHTTPTimeout); err != nil {
return Config{}, fmt.Errorf("VERSION_HISTORY_HTTP_TIMEOUT: %w", err)
}
// 版本记录来源:给了 origin 就必须是干净的 http(s) origin;白名单留空则默认只许自己。
if config.VersionHistoryGiteaBaseURL != "" {
if err := validateHTTPBaseURL(config.VersionHistoryGiteaBaseURL); err != nil {
return Config{}, fmt.Errorf("VERSION_HISTORY_GITEA_BASE_URL: %w%s", err,
envHint(config.VersionHistoryGiteaBaseURL))
}
if len(config.VersionHistoryAllowedOrigins) == 0 {
config.VersionHistoryAllowedOrigins = []string{config.VersionHistoryGiteaBaseURL}
}
for _, origin := range config.VersionHistoryAllowedOrigins {
if err := validateHTTPBaseURL(origin); err != nil {
return Config{}, fmt.Errorf("VERSION_HISTORY_ALLOWED_ORIGINS: %w", err)
}
}
if strings.Count(config.VersionHistoryRepo, "/") != 1 {
return Config{}, errors.New("VERSION_HISTORY_REPO 必须是 owner/name 形式")
}
if config.VersionHistoryLinkOrigin != "" {
if err := validateHTTPBaseURL(config.VersionHistoryLinkOrigin); err != nil {
return Config{}, fmt.Errorf("VERSION_HISTORY_LINK_ORIGIN: %w", err)
}
}
}
if config.LibraryArchiveRoot != "" && !filepath.IsAbs(config.LibraryArchiveRoot) {
return Config{}, errors.New("LIBRARY_ARCHIVE_ROOT 必须是绝对路径(归档根按只读目录挂载)")
}
if config.LibraryAgentSocket != "" && !filepath.IsAbs(config.LibraryAgentSocket) {
return Config{}, errors.New("LIBRARY_AGENT_SOCKET 必须是绝对路径(unix socket 由主机侧 agent 持有)")
}
// 目标维护要么完整配置,要么完全不配;半配置会让窗口"看起来存在"却挡不住目标。
targetSet := config.LibraryTargetInstance != "" || config.LibraryTargetProject != "" ||
len(config.LibraryTargetWriters) > 0 || config.LibraryTargetIngressURL != ""
if targetSet {
missing := make([]string, 0, 4)
if config.LibraryTargetInstance == "" {
missing = append(missing, "LIBRARY_TARGET_INSTANCE")
}
if config.LibraryTargetProject == "" {
missing = append(missing, "LIBRARY_TARGET_PROJECT")
}
if len(config.LibraryTargetWriters) == 0 {
missing = append(missing, "LIBRARY_TARGET_WRITERS")
}
if config.LibraryTargetIngressURL == "" {
missing = append(missing, "LIBRARY_TARGET_INGRESS_URL")
}
if config.LibraryTargetJournalRoot == "" {
missing = append(missing, "LIBRARY_TARGET_JOURNAL_ROOT")
}
if config.LibraryTargetIngressService == "" {
missing = append(missing, "LIBRARY_TARGET_INGRESS_SERVICE")
}
if config.LibraryTargetIngressDrainFile == "" {
missing = append(missing, "LIBRARY_TARGET_INGRESS_DRAIN_FILE")
}
if config.LibraryTargetRedisAddr == "" {
missing = append(missing, "LIBRARY_TARGET_REDIS_ADDR")
}
if len(missing) > 0 {
return Config{}, fmt.Errorf("目标维护配置不完整:缺少 %s", strings.Join(missing, "、"))
}
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) {
return Config{}, errors.New("LIBRARY_TARGET_INGRESS_DRAIN_FILE 必须是绝对路径")
}
if len(config.LibraryTargetNonWriters) == 0 {
return Config{}, errors.New("LIBRARY_TARGET_NON_WRITERS 必须逐项说明项目内非写入服务")
}
}
if config.TestWeKnoraHTTPTimeout, err = durationOrDefault(getenv("TEST_WEKNORA_HTTP_TIMEOUT"), config.TestWeKnoraHTTPTimeout); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_HTTP_TIMEOUT: %w", err)
}
if config.TestWeKnoraPollInitial, err = durationOrDefault(getenv("TEST_WEKNORA_POLL_INITIAL"), config.TestWeKnoraPollInitial); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_POLL_INITIAL: %w", err)
}
if config.TestWeKnoraPollMax, err = durationOrDefault(getenv("TEST_WEKNORA_POLL_MAX"), config.TestWeKnoraPollMax); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_POLL_MAX: %w", err)
}
if config.TestWeKnoraStalledAfter, err = durationOrDefault(getenv("TEST_WEKNORA_STALLED_AFTER"), config.TestWeKnoraStalledAfter); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_STALLED_AFTER: %w", err)
}
if config.TestWeKnoraMaxUploadBytes, err = positiveInt64OrDefault(getenv("TEST_WEKNORA_MAX_UPLOAD_BYTES"), config.TestWeKnoraMaxUploadBytes); err != nil {
return Config{}, fmt.Errorf("TEST_WEKNORA_MAX_UPLOAD_BYTES: %w", err)
}
if config.TestWeKnoraMaxUploadBytes > 50*1024*1024 {
return Config{}, errors.New("TEST_WEKNORA_MAX_UPLOAD_BYTES must not exceed 50 MiB")
}
if config.TestWeKnoraPollMax < config.TestWeKnoraPollInitial {
return Config{}, errors.New("TEST_WEKNORA_POLL_MAX must not be less than TEST_WEKNORA_POLL_INITIAL")
}
if config.TestWeKnoraStalledAfter <= config.TestWeKnoraPollMax {
return Config{}, errors.New("TEST_WEKNORA_STALLED_AFTER must be greater than TEST_WEKNORA_POLL_MAX")
}
config.TestAcceptancePolicyVersion = strings.TrimSpace(config.TestAcceptancePolicyVersion)
if config.TestAcceptancePolicyVersion == "" {
return Config{}, errors.New("TEST_ACCEPTANCE_POLICY_VERSION must not be empty")
}
// 审核策略:值不认识就拒绝启动,避免"写错一个词 → 静默变成另一种审核强度"。
normalizedPolicy, err := governance.ParseAutoReviewPolicy(config.TestAutoReviewPolicy)
if err != nil {
return Config{}, errors.New("TEST_AUTO_REVIEW_POLICY must be one of off, internal, all")
}
config.TestAutoReviewPolicy = string(normalizedPolicy)
if config.ProductionReleaseRequestsEnabled {
// 目标主机凭据要么都给要么都不给:只给一半会把"未接线"伪装成"已接线"。
if (config.BackupHostSSHConfig == "") != (config.BackupHostTarget == "") {
return Config{}, errors.New("BACKUP_HOST_SSH_CONFIG and BACKUP_HOST_TARGET must be set together")
}
if config.ProductionReleaseAuthorizerRef == "" || len(config.ProductionReleaseAuthorizerRef) > 128 || strings.ContainsAny(config.ProductionReleaseAuthorizerRef, "\x00\r\n ") {
return Config{}, errors.New("PRODUCTION_RELEASE_AUTHORIZER_REF is required and must be safe when production release requests are enabled")
}
if config.ProductionReleaseAuthTokenFile == "" || !filepath.IsAbs(config.ProductionReleaseAuthTokenFile) {
return Config{}, errors.New("PRODUCTION_RELEASE_AUTH_TOKEN_FILE must be an absolute path when production release requests are enabled")
}
}
if config.PPScanEnabled {
for key, value := range map[string]string{
"PP_SCAN_ALLOWED_ROOT": config.PPScanAllowedRoot,
"PP_SCAN_LEDGER_PATH": config.PPScanLedgerPath,
"PP_SCAN_MANIFEST_PATH": config.PPScanManifestPath,
} {
if value == "" {
return Config{}, fmt.Errorf("%s is required when PP scan is enabled", key)
}
if !filepath.IsAbs(value) {
return Config{}, fmt.Errorf("%s must be absolute", key)
}
}
}
if config.TestWeKnoraEnabled {
if config.TestWeKnoraBaseURL == "" {
return Config{}, errors.New("TEST_WEKNORA_BASE_URL is required when test WeKnora is enabled")
}
if config.TestWeKnoraKBID == "" {
return Config{}, errors.New("TEST_WEKNORA_KB_ID is required when test WeKnora is enabled")
}
if strings.TrimSpace(config.TestWeKnoraAPIKeyFile) == "" {
return Config{}, errors.New("TEST_WEKNORA_API_KEY_FILE is required when test WeKnora is enabled")
}
if strings.TrimSpace(config.GovernanceSpoolRoot) == "" {
return Config{}, errors.New("GOVERNANCE_SPOOL_ROOT is required when test WeKnora is enabled")
}
}
if (config.InternalRoutingKnowledgeBaseID == "") != (config.ExternalRoutingKnowledgeBaseID == "") {
return Config{}, errors.New("both internal and external routing knowledge bases must be configured together")
}
for _, knowledgeBaseID := range []string{config.InternalRoutingKnowledgeBaseID, config.ExternalRoutingKnowledgeBaseID} {
if len(knowledgeBaseID) > 128 || strings.ContainsAny(knowledgeBaseID, "\x00\r\n /?#\\") {
return Config{}, errors.New("routing knowledge base ID is invalid")
}
}
return config, nil
}
// validateHTTPBaseURL accepts only a bare http(s) origin: no credentials, query
// or fragment, so a probe address can never smuggle in secrets. The rule itself
// lives with the domain type because the web-configured endpoint must obey the
// exact same shape.
func validateHTTPBaseURL(value string) error {
if !governance.ValidHTTPOrigin(value) {
return errors.New("must be an http(s) origin without credentials, query or fragment")
}
return nil
}
// envHint 给"值明显不像一个地址"的情况补一句线索:最常见的成因是 `.env` 里两行粘在一起
// (新键被追加到没有结尾换行的上一行后面)—— 值里就会出现第二个 `KEY=`。
func envHint(value string) string {
if strings.Contains(value, "=") {
return "(值里出现了 `=`:`.env` 里两行可能粘成了一行,改成一行一值再上线)"
}
return ""
}
// splitOrigins 解析逗号分隔的 origin 白名单(空项丢弃)。
func splitOrigins(value string) []string {
parts := strings.Split(value, ",")
origins := make([]string, 0, len(parts))
for _, part := range parts {
if trimmed := strings.TrimSpace(part); trimmed != "" {
origins = append(origins, trimmed)
}
}
return origins
}
// splitList 把逗号分隔的声明拆成去空列表(顺序保留,便于日志对账)。
func splitList(value string) []string {
parts := strings.Split(value, ",")
out := make([]string, 0, len(parts))
for _, part := range parts {
if trimmed := strings.TrimSpace(part); trimmed != "" {
out = append(out, trimmed)
}
}
return out
}
// splitDeclarations 解析 "name=reason,name2=reason2"。
// 没有理由的声明直接丢空,由 Validate 拒绝——"忘记声明"不能变成"不用声明"。
func splitDeclarations(value string) map[string]string {
out := map[string]string{}
for _, item := range splitList(value) {
name, reason, ok := strings.Cut(item, "=")
name, reason = strings.TrimSpace(name), strings.TrimSpace(reason)
if !ok || name == "" || reason == "" {
continue
}
out[name] = reason
}
return out
}
// valueOrDefaultInt 解析正整数(非法/缺省都退回默认值)。
func valueOrDefaultInt(value string, fallback int) int {
parsed, err := strconv.Atoi(strings.TrimSpace(value))
if err != nil || parsed <= 0 {
return fallback
}
return parsed
}
func valueOrDefault(value, fallback string) string {
if value == "" {
return fallback
}
return value
}
func durationOrDefault(value string, fallback time.Duration) (time.Duration, error) {
if value == "" {
return fallback, nil
}
parsed, err := time.ParseDuration(value)
if err != nil {
return 0, err
}
if parsed <= 0 {
return 0, errors.New("must be positive")
}
return parsed, nil
}
func positiveInt64OrDefault(value string, fallback int64) (int64, error) {
if value == "" {
return fallback, nil
}
parsed, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return 0, err
}
if parsed <= 0 {
return 0, errors.New("must be positive")
}
return parsed, nil
}
// SourceInstance 是死信解除记录绑定的实例名:封存源与同步目标常常不是同一个实例,
// 用目标名去绑来源死信会让真实观测永远对不上(拒绝而不是误放行)。
func (config Config) SourceInstance() string {
if config.LibrarySourceInstance != "" {
return config.LibrarySourceInstance
}
return config.LibraryTargetInstance
}
// SourceProject 是封存执行器自报 project 的期望值。它描述的是**封存源**
// (agent 冻结哪一套写入者),不是同步目标:拿目标实例去比会把正确的执行器判成
// 不匹配(本机候选栈就是这种形状:源 kgmaint、目标 kgseal)。
func (config Config) SourceProject() string {
if config.LibrarySourceProject != "" {
return config.LibrarySourceProject
}
return config.SourceInstance()
}