Files
knowledge-governance/internal/appconfig/config.go
T
姚章浩 6ed06357f9
build / build (push) Successful in 1m27s
fix(library): 期望执行器身份随 capture 请求送达并在执行前核对
原来 worker 先 health 再 capture,两次拨号之间 socket 可能被换成另一个实例的
执行器:错的 agent 已经把写入者停了、快照也出了,事后 postcheck 只能拒绝登记,
副作用无法撤销。

现在 capture 请求自带期望身份(治理侧配置生成:project 必填,source_app /
archive_root 配了就绑定)与覆盖三项的稳定指纹;接收方在操作互斥内、执行任何源
操作之前比对,缺字段、指纹与字段不一致、project/source_app 不符都直接拒绝,
**错的执行器一次 capture 都不跑**。封存结果回显该指纹,worker 事后复核按它对照,
postcheck 只作为证据防线。恢复路径不要求期望(它只把写入者恢复回来)。

负例是确定性的:两个真实 agent 各占一个 socket,把调用方指向错的那个,断言它的
capture 调用为 0 且仍能回答 health;同一份期望打到对的 socket 则只跑一次。
2026-10-29 13:23:56 +08:00

603 lines
30 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
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
LibraryEmbeddingModel string
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
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)
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")),
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")),
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.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)
}
}
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()
}