Skip to content

feat: 生产配置 fail-fast 守卫(4.5) - #4

Merged
KDB-Wind merged 1 commit into
mainfrom
harness/4.5-credential-guard
Aug 10, 2026
Merged

feat: 生产配置 fail-fast 守卫(4.5)#4
KDB-Wind merged 1 commit into
mainfrom
harness/4.5-credential-guard

Conversation

@KDB-Wind

Copy link
Copy Markdown
Owner

背景

PR A(4.6 上游同步)已合并。本 PR 实现 4.5:生产 profile 下开发默认凭据的 fail-fast 守卫,避免弱凭据静默上线。

机制

ProductionCredentialGuard(bootstrap 模块,EnvironmentPostProcessor,Ordered.LOWEST_PRECEDENCE 保证晚于 ConfigData 加载、早于任何 bean 与连接建立):

  • profile 判定:未显式激活任何 profile,或激活集合含 local / dev / est 任一 → 完全放行,本地直接启动行为不变;其余 profile(如 prod)执行检查。
  • 三类检查(对每个敏感键取生效值,含占位符解析):
    1. 生效值命中已知开发默认值集合 → IllegalStateException(消息只含键名与提示,不含值);
    2. ${KEY} 无默认值且环境无法解析 → 抛异常(未配置);
    3. ${KEY:默认值} 的默认值命中开发默认凭据集合 → 抛异常(弱默认兜底,仅当环境变量缺失使默认值实际生效时触发)。
  • 注册:META-INF/spring.factories(Spring Boot 3 中 EnvironmentPostProcessor 只从 spring.factories 加载,auto-configuration 的 .imports 机制不适用;已用 spring-boot:run + prod profile 实测确认,守卫在 ~2 秒内于 prepareEnvironment 阶段拦截)。

敏感键清单(键名)

  • spring.datasource.username
  • spring.datasource.password
  • spring.data.redis.password

ag.storage.s3.access-key

ag.storage.s3.secret-key

模型 API key(BAILIAN_API_KEY / SILICONFLOW_API_KEY / AIHUBMIX_API_KEY / MINERU_API_KEY / OSS_* / YDC_API_KEY)走环境变量属正向机制,不参与守卫,文档已注明生产必须提供。

测试(ProductionCredentialGuardTest,9 个,纯逻辑 + MockEnvironment,无 Spring context、无外部依赖)

  1. 无 profile + 开发默认值 → 不抛
  2. dev profile + 开发默认值 → 不抛
  3. local profile + 开发默认值 → 不抛
  4. prod profile + 开发默认凭据 → 抛,消息含键名、不含值
  5. prod profile + 环境变量覆盖(非默认值)→ 不抛
  6. prod profile + 未解析占位符(无默认)→ 抛
  7. prod profile + 可解析占位符 → 不抛
  8. prod profile + ${KEY:postgres} 弱默认兜底 → 抛
  9. prod profile + ${KEY:} 空默认 → 不抛

本地验证

  • ./mvnw -B -ntp test:BUILD SUCCESS(bootstrap 229 测试全绿,含新测试 9/9)
  • ./mvnw -B -ntp -DskipTests package:BUILD SUCCESS
  • smoke(spring-boot:run):SPRING_PROFILES_ACTIVE=prod → 守卫在 prepareEnvironment 阶段拦截(配置键 [spring.datasource.username] 检测到开发默认值...);无 profile → 守卫放行,行为不变

文档

  • AGENTS.md 新增「配置与凭据」小节(本地放行条件、生产必覆盖键清单、fail-fast 行为、密钥轮换提醒)
  • 新增 docs/production-configuration.md(生产部署配置说明,示例全为占位符,无真实凭据)

非目标

  • 密钥轮换与托管(Vault/KMS 对接)属部署侧,需用户按供应商侧处理
  • 不做配置加密;守卫只做启动期 fail-fast,不参与运行期凭据刷新

@KDB-Wind
KDB-Wind merged commit e67cfa8 into main Aug 10, 2026
2 checks passed
@KDB-Wind
KDB-Wind deleted the harness/4.5-credential-guard branch August 10, 2026 17:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant