@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/config/metadata.go

@@ -0,0 +1,717 @@
+package config
+
+import (
+	"fmt"
+	"net"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/spf13/viper"
+)
+
+const (
+	maxDocumentationBuildTimeout                  = 2 * time.Hour
+	maxAPIContractCompatibilityEvaluatorTimeout   = 10 * time.Minute
+	apiContractCompatibilityEvaluatorRuntimeGroup = "api_contract_compatibility_evaluator"
+)
+
+var environmentVariableNamePattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)
+
+// ConfigDefaultValue 以受约束的联合类型保存 Viper 默认值。
+type ConfigDefaultValue struct {
+	kind         uint8
+	stringValue  string
+	integerValue int
+}
+
+// IsSet 标识注册项是否声明了代码默认值。
+func (value ConfigDefaultValue) IsSet() bool {
+	return value.kind != configDefaultValueUnset
+}
+
+// DisplayValue 返回用于确定性文档生成的默认值文本。
+func (value ConfigDefaultValue) DisplayValue() (string, bool) {
+	switch value.kind {
+	case configDefaultValueString:
+		return value.stringValue, true
+	case configDefaultValueInteger:
+		return strconv.Itoa(value.integerValue), true
+	default:
+		return "", false
+	}
+}
+
+func stringConfigDefaultValue(value string) ConfigDefaultValue {
+	return ConfigDefaultValue{kind: configDefaultValueString, stringValue: value}
+}
+
+func integerConfigDefaultValue(value int) ConfigDefaultValue {
+	return ConfigDefaultValue{kind: configDefaultValueInteger, integerValue: value}
+}
+
+func (value ConfigDefaultValue) apply(v *viper.Viper, configKey string) {
+	switch value.kind {
+	case configDefaultValueString:
+		v.SetDefault(configKey, value.stringValue)
+	case configDefaultValueInteger:
+		v.SetDefault(configKey, value.integerValue)
+	}
+}
+
+type runtimeConfigValue func(*Config) (string, bool)
+
+// EnvironmentVariableMetadata 是运行时配置、部署样例和消费者归属的唯一元数据源。
+type EnvironmentVariableMetadata struct {
+	Name                          string
+	ConfigKey                     string
+	ValueType                     ConfigValueType
+	DefaultValue                  ConfigDefaultValue
+	Description                   string
+	RequiredSurfaces              []DeploymentSurface
+	RequiredConsumers             []string
+	AllowedConsumers              []string
+	Sensitive                     bool
+	ValuePattern                  string
+	RequiredSuffix                string
+	RequiredURLPath               string
+	MaximumInteger                int64
+	MaximumDuration               time.Duration
+	RequireAbsoluteRuntimePath    bool
+	RequireAbsoluteDeploymentPath bool
+	MountSourceVariable           string
+	MountReadOnly                 bool
+	runtimeGroup                  string
+	requiredApplications          []string
+	runtimeValue                  runtimeConfigValue
+}
+
+var allDocumentationDeploymentSurfaces = []DeploymentSurface{
+	DeploymentSurfaceDev,
+	DeploymentSurfaceTest,
+	DeploymentSurfaceProd,
+}
+
+func stringRuntimeConfigValue(selector func(*Config) string) runtimeConfigValue {
+	return func(cfg *Config) (string, bool) {
+		value := selector(cfg)
+		return value, strings.TrimSpace(value) != ""
+	}
+}
+
+func durationRuntimeConfigValue(selector func(*Config) time.Duration) runtimeConfigValue {
+	return func(cfg *Config) (string, bool) {
+		value := selector(cfg)
+		return value.String(), value != 0
+	}
+}
+
+func integerRuntimeConfigValue(selector func(*Config) int) runtimeConfigValue {
+	return func(cfg *Config) (string, bool) {
+		value := selector(cfg)
+		return strconv.Itoa(value), value != 0
+	}
+}
+
+var documentationEnvironmentVariables = []EnvironmentVariableMetadata{
+	{
+		Name: "DOCUMENTATION_NODE_EXECUTABLE", ConfigKey: "documentation.node_executable",
+		ValueType: ConfigValueTypeExecutable, DefaultValue: stringConfigDefaultValue("node"),
+		Description:       "文档编译器使用的 Node.js 可执行文件。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		runtimeGroup: documentationRuntimeGroupCompiler,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.NodeExecutable
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_SITE_ROOT", ConfigKey: "documentation.site_root",
+		ValueType: ConfigValueTypePath, DefaultValue: stringConfigDefaultValue("../docs-site"),
+		Description:       "文档站点源码与锁定工具链的根目录。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		RequireAbsoluteDeploymentPath: true,
+		runtimeGroup:                  documentationRuntimeGroupCompiler,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.SiteRoot
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_COMPILER_SCRIPT", ConfigKey: "documentation.compiler_script",
+		ValueType: ConfigValueTypePath, DefaultValue: stringConfigDefaultValue("../docs-site/scripts/compiler.mjs"),
+		Description:       "文档编译 CLI 的入口脚本。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		RequiredSuffix:                ".mjs",
+		RequireAbsoluteDeploymentPath: true,
+		runtimeGroup:                  documentationRuntimeGroupCompiler,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.CompilerScript
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_BUILD_TIMEOUT", ConfigKey: "documentation.build_timeout",
+		ValueType: ConfigValueTypeDuration, DefaultValue: stringConfigDefaultValue("30m"),
+		Description:       "单次文档编译任务的硬超时。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		MaximumDuration: maxDocumentationBuildTimeout,
+		runtimeGroup:    documentationRuntimeGroupCompiler,
+		runtimeValue: durationRuntimeConfigValue(func(cfg *Config) time.Duration {
+			return cfg.Documentation.BuildTimeout
+		}),
+	},
+	{
+		Name: "API_CONTRACT_COMPATIBILITY_EVALUATOR_EXECUTABLE", ConfigKey: "api_contract.compatibility_evaluator.executable",
+		ValueType: ConfigValueTypeExecutable, DefaultValue: stringConfigDefaultValue("oasdiff"),
+		Description:       "API 契约兼容性评估使用的 oasdiff 可执行文件。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		runtimeGroup:         apiContractCompatibilityEvaluatorRuntimeGroup,
+		requiredApplications: []string{"worker"},
+		runtimeValue: func(cfg *Config) (string, bool) {
+			return cfg.APIContract.CompatibilityEvaluator.Executable,
+				strings.EqualFold(strings.TrimSpace(cfg.App.Name), "worker")
+		},
+	},
+	{
+		Name: "API_CONTRACT_COMPATIBILITY_EVALUATOR_TIMEOUT", ConfigKey: "api_contract.compatibility_evaluator.timeout",
+		ValueType: ConfigValueTypeDuration, DefaultValue: stringConfigDefaultValue("2m"),
+		Description:       "单次 API 契约兼容性评估的硬超时。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"worker"}, AllowedConsumers: []string{"worker"},
+		MaximumDuration:      maxAPIContractCompatibilityEvaluatorTimeout,
+		runtimeGroup:         apiContractCompatibilityEvaluatorRuntimeGroup,
+		requiredApplications: []string{"worker"},
+		runtimeValue: func(cfg *Config) (string, bool) {
+			value := cfg.APIContract.CompatibilityEvaluator.Timeout
+			return value.String(), strings.EqualFold(strings.TrimSpace(cfg.App.Name), "worker") && value != 0
+		},
+	},
+	{
+		Name: "DOCUMENTATION_PRIVACY_HMAC_KEY_REF", ConfigKey: "documentation.privacy_hmac_key_ref",
+		ValueType: ConfigValueTypeSecretReference, DefaultValue: stringConfigDefaultValue("env://DOCUMENTATION_PRIVACY_HMAC_KEY"),
+		Description:          "搜索与主体伪名化密钥的引用。",
+		RequiredSurfaces:     allDocumentationDeploymentSurfaces,
+		RequiredConsumers:    []string{"platform-api", "documentation-api"},
+		AllowedConsumers:     []string{"platform-api", "documentation-api"},
+		runtimeGroup:         documentationRuntimeGroupPrivacy,
+		requiredApplications: []string{"platform-api", "documentation-api"},
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.PrivacyHMACKeyRef
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_BINDING_PROVIDER_KEY", ConfigKey: "documentation.domain_binding_provider_key",
+		ValueType: ConfigValueTypeString, DefaultValue: stringConfigDefaultValue("apisix"),
+		Description:       "文档自定义域名绑定 Provider 的注册键。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		ValuePattern: `^[a-z][a-z0-9_-]{0,63}$`,
+		runtimeGroup: documentationRuntimeGroupDomain,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.DomainBindingProviderKey
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_URL", ConfigKey: "documentation.domain_gateway_admin_url",
+		ValueType: ConfigValueTypeHTTPURL, DefaultValue: stringConfigDefaultValue("http://apisix:9180/apisix/admin"),
+		Description:       "文档域名绑定使用的 APISIX Admin API 根地址。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		RequiredURLPath: "/apisix/admin",
+		runtimeGroup:    documentationRuntimeGroupDomain,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.DomainGatewayAdminURL
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF", ConfigKey: "documentation.domain_gateway_admin_key_ref",
+		ValueType: ConfigValueTypeSecretReference, DefaultValue: stringConfigDefaultValue("env://APISIX_ADMIN_API_KEY"),
+		Description:       "APISIX Admin API 密钥引用。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		runtimeGroup: documentationRuntimeGroupDomain,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.DomainGatewayAdminKeyRef
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_ORIGIN_UPSTREAM_ID", ConfigKey: "documentation.domain_origin_upstream_id",
+		ValueType: ConfigValueTypeString, DefaultValue: stringConfigDefaultValue("12"),
+		Description:       "文档 Origin 在 APISIX 中的稳定 upstream 标识。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		ValuePattern: `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`,
+		runtimeGroup: documentationRuntimeGroupDomain,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.DomainOriginUpstreamID
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_CERTIFICATE_ROOT", ConfigKey: "documentation.domain_certificate_root",
+		ValueType: ConfigValueTypePath, DefaultValue: stringConfigDefaultValue("/run/secrets/documentation-domains"),
+		Description:       "文档自定义域名证书在容器内的只读根目录。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		RequireAbsoluteRuntimePath:    true,
+		RequireAbsoluteDeploymentPath: true,
+		MountSourceVariable:           "DOCUMENTATION_DOMAIN_CERTIFICATE_ROOT_HOST",
+		MountReadOnly:                 true,
+		runtimeGroup:                  documentationRuntimeGroupDomain,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.Documentation.DomainCertificateRoot
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_ROUTE_PRIORITY", ConfigKey: "documentation.domain_route_priority",
+		ValueType: ConfigValueTypeInteger, DefaultValue: integerConfigDefaultValue(20),
+		Description:       "文档自定义域名路由的 APISIX 优先级。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"admin-api", "worker"}, AllowedConsumers: []string{"admin-api", "worker"},
+		MaximumInteger: 1_000_000,
+		runtimeGroup:   documentationRuntimeGroupDomain,
+		runtimeValue: integerRuntimeConfigValue(func(cfg *Config) int {
+			return cfg.Documentation.DomainRoutePriority
+		}),
+	},
+	{
+		Name: "INTERNAL_SERVICE_DOCUMENTATION_BASE_URL", ConfigKey: "internal_service.documentation_base_url",
+		ValueType: ConfigValueTypeHTTPURL, DefaultValue: stringConfigDefaultValue("http://documentation-api:3010/api/v1/documentation"),
+		Description:       "平台 AI 文档读取端连接 documentation-api 的内部根地址。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"platform-api"}, AllowedConsumers: []string{"platform-api"},
+		RequiredURLPath: "/api/v1/documentation",
+		runtimeGroup:    documentationRuntimeGroupInternal,
+		runtimeValue: stringRuntimeConfigValue(func(cfg *Config) string {
+			return cfg.InternalService.DocumentationBaseURL
+		}),
+	},
+	{
+		Name: "DOCUMENTATION_PRIVACY_HMAC_KEY", ValueType: ConfigValueTypeSecret,
+		Description:       "文档搜索和主体伪名化使用的 32 字节以上密钥材料。",
+		RequiredSurfaces:  allDocumentationDeploymentSurfaces,
+		RequiredConsumers: []string{"platform-api", "documentation-api"},
+		AllowedConsumers:  []string{"platform-api", "documentation-api"},
+		Sensitive:         true,
+	},
+	{
+		Name: "DOCUMENTATION_DOMAIN_CERTIFICATE_ROOT_HOST", ValueType: ConfigValueTypePath,
+		Description:                   "宿主机上文档自定义域名证书的只读挂载根目录。",
+		RequiredSurfaces:              allDocumentationDeploymentSurfaces,
+		RequireAbsoluteDeploymentPath: true,
+	},
+	{
+		Name: "DOCUMENTATION_API_UPSTREAMS", ValueType: ConfigValueTypeEndpointList,
+		Description: "gateway-sync 管理的文档服务 upstream host:port 列表。",
+		RequiredSurfaces: []DeploymentSurface{
+			DeploymentSurfaceTest,
+			DeploymentSurfaceProd,
+		},
+		RequiredConsumers: []string{"gateway-sync"}, AllowedConsumers: []string{"gateway-sync"},
+	},
+}
+
+// ValidateDocumentationEnvironmentVariables 校验完整注册表的唯一性、类型和归属关系。
+func ValidateDocumentationEnvironmentVariables(metadata []EnvironmentVariableMetadata) error {
+	variablesByName := make(map[string]*EnvironmentVariableMetadata, len(metadata))
+	configKeys := make(map[string]struct{}, len(metadata))
+	for index := range metadata {
+		variable := &metadata[index]
+		if !environmentVariableNamePattern.MatchString(variable.Name) {
+			return fmt.Errorf("environment metadata name %q is invalid", variable.Name)
+		}
+		if _, duplicate := variablesByName[variable.Name]; duplicate {
+			return fmt.Errorf("environment metadata name %q is duplicated", variable.Name)
+		}
+		variablesByName[variable.Name] = variable
+		if variable.ConfigKey != "" {
+			if _, duplicate := configKeys[variable.ConfigKey]; duplicate {
+				return fmt.Errorf("config key %q is duplicated", variable.ConfigKey)
+			}
+			configKeys[variable.ConfigKey] = struct{}{}
+		}
+		if !isSupportedConfigValueType(variable.ValueType) {
+			return fmt.Errorf("environment metadata %s has unsupported type %q", variable.Name, variable.ValueType)
+		}
+		if strings.TrimSpace(variable.Description) == "" {
+			return fmt.Errorf("environment metadata %s has no description", variable.Name)
+		}
+		if err := variable.ValidateSchema(); err != nil {
+			return err
+		}
+
+		surfaces := make(map[DeploymentSurface]struct{}, len(variable.RequiredSurfaces))
+		for _, surface := range variable.RequiredSurfaces {
+			if !isSupportedDeploymentSurface(surface) {
+				return fmt.Errorf("environment metadata %s has unsupported surface %q", variable.Name, surface)
+			}
+			if _, duplicate := surfaces[surface]; duplicate {
+				return fmt.Errorf("environment metadata %s duplicates surface %q", variable.Name, surface)
+			}
+			surfaces[surface] = struct{}{}
+		}
+		allowed := toStringSet(variable.AllowedConsumers)
+		if len(allowed) != len(variable.AllowedConsumers) || containsString(variable.AllowedConsumers, "") {
+			return fmt.Errorf("environment metadata %s has invalid allowed consumers", variable.Name)
+		}
+		required := toStringSet(variable.RequiredConsumers)
+		if len(required) != len(variable.RequiredConsumers) || containsString(variable.RequiredConsumers, "") {
+			return fmt.Errorf("environment metadata %s has invalid required consumers", variable.Name)
+		}
+		for _, consumer := range variable.RequiredConsumers {
+			if _, exists := allowed[consumer]; !exists {
+				return fmt.Errorf("environment metadata %s requires consumer %s outside its allowlist", variable.Name, consumer)
+			}
+		}
+	}
+
+	for index := range metadata {
+		variable := &metadata[index]
+		if variable.MountSourceVariable == "" {
+			continue
+		}
+		source, exists := variablesByName[variable.MountSourceVariable]
+		if !exists {
+			return fmt.Errorf(
+				"environment metadata %s references unknown mount source %s",
+				variable.Name,
+				variable.MountSourceVariable,
+			)
+		}
+		if source.ValueType != ConfigValueTypePath {
+			return fmt.Errorf("environment metadata %s mount source %s is not a path", variable.Name, source.Name)
+		}
+		for _, surface := range variable.RequiredSurfaces {
+			if !containsDeploymentSurface(source.RequiredSurfaces, surface) {
+				return fmt.Errorf(
+					"environment metadata %s mount source %s is not required in %s",
+					variable.Name,
+					source.Name,
+					surface,
+				)
+			}
+		}
+	}
+	return nil
+}
+
+func isSupportedConfigValueType(valueType ConfigValueType) bool {
+	switch valueType {
+	case ConfigValueTypeString,
+		ConfigValueTypeExecutable,
+		ConfigValueTypeInteger,
+		ConfigValueTypeDuration,
+		ConfigValueTypeHTTPURL,
+		ConfigValueTypePath,
+		ConfigValueTypeSecretReference,
+		ConfigValueTypeSecret,
+		ConfigValueTypeEndpointList:
+		return true
+	default:
+		return false
+	}
+}
+
+func isSupportedDeploymentSurface(surface DeploymentSurface) bool {
+	switch surface {
+	case DeploymentSurfaceDev, DeploymentSurfaceTest, DeploymentSurfaceProd:
+		return true
+	default:
+		return false
+	}
+}
+
+func containsDeploymentSurface(surfaces []DeploymentSurface, target DeploymentSurface) bool {
+	for _, surface := range surfaces {
+		if surface == target {
+			return true
+		}
+	}
+	return false
+}
+
+func toStringSet(values []string) map[string]struct{} {
+	result := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		result[value] = struct{}{}
+	}
+	return result
+}
+
+// ValidateSchema 校验注册项自身的类型与默认值约束。
+func (variable *EnvironmentVariableMetadata) ValidateSchema() error {
+	if variable == nil || strings.TrimSpace(variable.Name) == "" {
+		return fmt.Errorf("environment metadata name is required")
+	}
+	if variable.ConfigKey != "" && !variable.DefaultValue.IsSet() {
+		return fmt.Errorf("config key %q has no default", variable.ConfigKey)
+	}
+	if variable.ConfigKey == "" && variable.DefaultValue.IsSet() {
+		return fmt.Errorf("environment metadata %s has a default without a config key", variable.Name)
+	}
+	if variable.ConfigKey != "" && variable.runtimeValue == nil {
+		return fmt.Errorf("environment metadata %s has no runtime value extractor", variable.Name)
+	}
+	if variable.Sensitive != (variable.ValueType == ConfigValueTypeSecret) {
+		return fmt.Errorf("environment metadata %s has inconsistent secret classification", variable.Name)
+	}
+	if variable.DefaultValue.IsSet() {
+		switch variable.ValueType {
+		case ConfigValueTypeInteger:
+			if variable.DefaultValue.kind != configDefaultValueInteger {
+				return fmt.Errorf("environment metadata %s has a non-integer default", variable.Name)
+			}
+		default:
+			if variable.DefaultValue.kind != configDefaultValueString {
+				return fmt.Errorf("environment metadata %s has a non-string default", variable.Name)
+			}
+		}
+		value, _ := variable.DefaultValue.DisplayValue()
+		if err := variable.ValidateValue(value, ConfigValueValidationRuntime); err != nil {
+			return fmt.Errorf("environment metadata %s has an invalid default: %w", variable.Name, err)
+		}
+	}
+	if variable.ValuePattern != "" {
+		if _, err := regexp.Compile(variable.ValuePattern); err != nil {
+			return fmt.Errorf("environment metadata %s has an invalid value pattern: %w", variable.Name, err)
+		}
+	}
+	if variable.MaximumInteger != 0 && variable.ValueType != ConfigValueTypeInteger {
+		return fmt.Errorf("environment metadata %s applies an integer limit to a non-integer value", variable.Name)
+	}
+	if variable.MaximumDuration != 0 && variable.ValueType != ConfigValueTypeDuration {
+		return fmt.Errorf("environment metadata %s applies a duration limit to a non-duration value", variable.Name)
+	}
+	if variable.RequiredURLPath != "" && variable.ValueType != ConfigValueTypeHTTPURL {
+		return fmt.Errorf("environment metadata %s applies a URL path to a non-URL value", variable.Name)
+	}
+	if (variable.RequireAbsoluteRuntimePath || variable.RequireAbsoluteDeploymentPath) &&
+		variable.ValueType != ConfigValueTypePath {
+		return fmt.Errorf("environment metadata %s applies path constraints to a non-path value", variable.Name)
+	}
+	if variable.MountSourceVariable != "" && variable.ValueType != ConfigValueTypePath {
+		return fmt.Errorf("environment metadata %s applies a mount contract to a non-path value", variable.Name)
+	}
+	if variable.runtimeValue != nil && variable.runtimeGroup == "" {
+		return fmt.Errorf("environment metadata %s has no runtime group", variable.Name)
+	}
+	return nil
+}
+
+// ValidateValue 对运行时和部署样例复用同一字段语义。
+func (variable *EnvironmentVariableMetadata) ValidateValue(
+	value string,
+	validationContext ConfigValueValidationContext,
+) error {
+	if variable == nil {
+		return fmt.Errorf("environment metadata is nil")
+	}
+	if validationContext != ConfigValueValidationRuntime && validationContext != ConfigValueValidationDeployment {
+		return fmt.Errorf("%s has unsupported validation context %q", variable.Name, validationContext)
+	}
+	if strings.TrimSpace(value) != value || strings.ContainsRune(value, '\x00') {
+		return fmt.Errorf("%s has invalid surrounding or null characters", variable.Name)
+	}
+
+	switch variable.ValueType {
+	case ConfigValueTypeString:
+		if value == "" {
+			return fmt.Errorf("%s must not be empty", variable.Name)
+		}
+	case ConfigValueTypeExecutable:
+		if err := validateExecutableValue(variable.Name, value); err != nil {
+			return err
+		}
+	case ConfigValueTypeInteger:
+		parsed, err := strconv.ParseInt(value, 10, 64)
+		if err != nil || parsed <= 0 {
+			return fmt.Errorf("%s must be a positive integer", variable.Name)
+		}
+		if variable.MaximumInteger > 0 && parsed > variable.MaximumInteger {
+			return fmt.Errorf("%s must be at most %d", variable.Name, variable.MaximumInteger)
+		}
+	case ConfigValueTypeDuration:
+		parsed, err := time.ParseDuration(value)
+		if err != nil || parsed <= 0 {
+			return fmt.Errorf("%s must be a positive Go duration", variable.Name)
+		}
+		if variable.MaximumDuration > 0 && parsed > variable.MaximumDuration {
+			return fmt.Errorf("%s must be at most %s", variable.Name, variable.MaximumDuration)
+		}
+	case ConfigValueTypeHTTPURL:
+		parsed, err := url.Parse(value)
+		if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") ||
+			parsed.Opaque != "" || parsed.User != nil || parsed.RawQuery != "" || parsed.Fragment != "" {
+			return fmt.Errorf("%s must be an absolute HTTP URL without credentials, query, or fragment", variable.Name)
+		}
+		if variable.RequiredURLPath != "" && parsed.Path != variable.RequiredURLPath {
+			return fmt.Errorf("%s must end at %s", variable.Name, variable.RequiredURLPath)
+		}
+	case ConfigValueTypePath:
+		requireAbsolute := variable.RequireAbsoluteRuntimePath
+		if validationContext == ConfigValueValidationDeployment {
+			requireAbsolute = variable.RequireAbsoluteDeploymentPath
+		}
+		if err := validatePathValue(variable.Name, value, requireAbsolute); err != nil {
+			return err
+		}
+	case ConfigValueTypeSecretReference:
+		if err := validateSecretReferenceValue(variable.Name, value); err != nil {
+			return err
+		}
+	case ConfigValueTypeSecret:
+		if value == "" {
+			return fmt.Errorf("%s must not be empty", variable.Name)
+		}
+	case ConfigValueTypeEndpointList:
+		if err := validateEndpointListValue(variable.Name, value); err != nil {
+			return err
+		}
+	default:
+		return fmt.Errorf("%s has unsupported value type %q", variable.Name, variable.ValueType)
+	}
+
+	if variable.RequiredSuffix != "" && !strings.HasSuffix(value, variable.RequiredSuffix) {
+		return fmt.Errorf("%s must end in %s", variable.Name, variable.RequiredSuffix)
+	}
+	if variable.ValuePattern != "" {
+		pattern, err := regexp.Compile(variable.ValuePattern)
+		if err != nil {
+			return fmt.Errorf("%s has an invalid metadata pattern: %w", variable.Name, err)
+		}
+		if !pattern.MatchString(value) {
+			return fmt.Errorf("%s has an invalid value", variable.Name)
+		}
+	}
+	return nil
+}
+
+func validateExecutableValue(name, value string) error {
+	if value == "" || strings.ContainsFunc(value, unicode.IsSpace) || filepath.Clean(value) != value ||
+		filepath.Clean(value) == "." || filepath.Clean(value) == string(filepath.Separator) {
+		return fmt.Errorf("%s must be a bare executable name or an absolute executable path", name)
+	}
+	if !filepath.IsAbs(value) && filepath.Base(value) != value {
+		return fmt.Errorf("%s must be a bare executable name or an absolute executable path", name)
+	}
+	return nil
+}
+
+func validatePathValue(name, value string, requireAbsolute bool) error {
+	cleaned := filepath.Clean(value)
+	if value == "" || cleaned == "." || cleaned == string(filepath.Separator) || cleaned != value {
+		return fmt.Errorf("%s must be a canonical non-root path", name)
+	}
+	if requireAbsolute && !filepath.IsAbs(value) {
+		return fmt.Errorf("%s must be an absolute non-root path", name)
+	}
+	return nil
+}
+
+func validateSecretReferenceValue(name, value string) error {
+	if err := validateReferenceConfig(name, value); err != nil {
+		return err
+	}
+	switch {
+	case strings.HasPrefix(value, "env://"):
+		if !environmentVariableNamePattern.MatchString(strings.TrimPrefix(value, "env://")) {
+			return fmt.Errorf("%s must contain a valid env:// reference", name)
+		}
+	case strings.HasPrefix(value, "file://"):
+		path := strings.TrimPrefix(value, "file://")
+		if strings.ContainsRune(path, '\x00') || !filepath.IsAbs(path) || filepath.Clean(path) != path ||
+			filepath.Clean(path) == string(filepath.Separator) {
+			return fmt.Errorf("%s must contain an absolute canonical file:// reference", name)
+		}
+	default:
+		return fmt.Errorf("%s must use env:// or file://", name)
+	}
+	return nil
+}
+
+func validateEndpointListValue(name, value string) error {
+	for _, endpoint := range strings.Split(value, ",") {
+		host, portValue, err := net.SplitHostPort(strings.TrimSpace(endpoint))
+		port, parseErr := strconv.Atoi(portValue)
+		if err != nil || parseErr != nil || strings.TrimSpace(host) == "" || port < 1 || port > 65535 {
+			return fmt.Errorf("%s must be a comma-separated host:port list", name)
+		}
+	}
+	return nil
+}
+
+func validateDocumentationConfig(cfg *Config) error {
+	activeGroups := make(map[string]bool)
+	values := make(map[string]string)
+	appName := strings.ToLower(strings.TrimSpace(cfg.App.Name))
+	for index := range documentationEnvironmentVariables {
+		variable := &documentationEnvironmentVariables[index]
+		if variable.runtimeValue == nil {
+			continue
+		}
+		value, configured := variable.runtimeValue(cfg)
+		values[variable.Name] = value
+		if configured || containsString(variable.requiredApplications, appName) {
+			activeGroups[variable.runtimeGroup] = true
+		}
+	}
+	for index := range documentationEnvironmentVariables {
+		variable := &documentationEnvironmentVariables[index]
+		if variable.runtimeValue == nil || !activeGroups[variable.runtimeGroup] {
+			continue
+		}
+		if err := variable.ValidateValue(values[variable.Name], ConfigValueValidationRuntime); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func containsString(values []string, target string) bool {
+	for _, value := range values {
+		if value == target {
+			return true
+		}
+	}
+	return false
+}
+
+// DocumentationEnvironmentVariables 返回不可变快照，防止工具修改运行时注册表。
+func DocumentationEnvironmentVariables() []EnvironmentVariableMetadata {
+	result := make([]EnvironmentVariableMetadata, len(documentationEnvironmentVariables))
+	for index := range documentationEnvironmentVariables {
+		item := documentationEnvironmentVariables[index]
+		item.RequiredSurfaces = append([]DeploymentSurface(nil), item.RequiredSurfaces...)
+		item.RequiredConsumers = append([]string(nil), item.RequiredConsumers...)
+		item.AllowedConsumers = append([]string(nil), item.AllowedConsumers...)
+		result[index] = item
+	}
+	return result
+}
+
+func applyDocumentationDefaults(v *viper.Viper) {
+	for index := range documentationEnvironmentVariables {
+		variable := &documentationEnvironmentVariables[index]
+		if variable.ConfigKey != "" {
+			variable.DefaultValue.apply(v, variable.ConfigKey)
+		}
+	}
+}
+
+func bindDocumentationEnvironment(v *viper.Viper) error {
+	for index := range documentationEnvironmentVariables {
+		variable := &documentationEnvironmentVariables[index]
+		if variable.ConfigKey != "" {
+			if err := v.BindEnv(variable.ConfigKey, variable.Name); err != nil {
+				return fmt.Errorf("bind environment variable %s: %w", variable.Name, err)
+			}
+		}
+	}
+	return nil
+}