跳转至

Spring Boot 外部配置

Spring Boot 支持在不重新构建 JAR 的情况下从配置文件、环境变量、JVM System Property 和命令行参数读取配置。同一个镜像可以部署到不同环境，但配置来源必须有明确规则，否则很容易出现“文件已经改了，应用却使用了另一个值”。

推荐分层

JAR 内 application.yml       通用且非敏感的默认值
外部 application-prod.yml   环境结构化配置
环境变量 / Secret           密码、令牌以及少量部署差异
命令行参数                   临时覆盖和故障验证，避免长期堆积

常见高优先级来源可以覆盖低优先级来源。命令行参数、Java System Property、环境变量和外部配置文件之间存在固定顺序；排障时必须同时检查启动命令、容器环境、挂载文件和 JAR 内默认值。

Profile

java -jar app.jar --spring.profiles.active=prod

# application.yml
spring:
  application:
    name: order-service

---
# application-prod.yml
server:
  port: 8080

Profile 用于选择环境配置，不是安全边界。不要在 application-prod.yml 中提交数据库密码或私钥。

外部配置目录

推荐“保留 JAR 默认配置，再增加外部覆盖目录”：

java -jar app.jar \
  --spring.profiles.active=prod \
  --spring.config.additional-location=optional:file:/app/config/
参数 行为
spring.config.additional-location 在默认搜索位置之外增加位置，外部值可覆盖默认值
spring.config.location 替换默认搜索位置，配置不完整时可能导致原有默认值消失
optional: 文件不存在时允许继续启动

目录位置应以 / 结尾。要求配置必须存在时不要加 optional:，让应用在缺失配置时直接失败，比带错误默认值启动更安全。

容器挂载示例

services:
  app:
    image: registry.example.com/team/app:1.4.0
    environment:
      SPRING_PROFILES_ACTIVE: prod
      SPRING_CONFIG_ADDITIONAL_LOCATION: file:/app/config/
      DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./config/application-prod.yml:/app/config/application-prod.yml:ro

Spring 属性转换成环境变量时通常改为大写、去掉短横线并用下划线连接，例如：

spring.datasource.url       → SPRING_DATASOURCE_URL
server.port                 → SERVER_PORT
management.server.port      → MANAGEMENT_SERVER_PORT

复杂列表和 Map 不适合大量使用环境变量表达，优先放到受控外部 YAML；Secret 由 Compose Secret、Kubernetes Secret、Vault 或 CI/CD 密钥变量提供。

如何确认实际生效值

  1. 查看完整启动命令和容器环境变量。
  2. 确认外部配置文件确实挂载到容器内部预期路径，并检查权限。
  3. 查看启动日志中的 active profiles 和配置加载异常。
  4. 如启用 Actuator，只在受控网络和鉴权下查看 env/configprops，避免泄露密码。
  5. 变更配置后确认是否需要重启；普通本地 YAML 不会自动热更新。

常见问题

现象 优先检查
修改 YAML 后没有生效 是否改错主机/文件；挂载路径；Profile；更高优先级环境变量或命令行参数
启动提示配置文件不存在 location 路径、目录结尾 /、容器内路径和文件权限
数据库仍连接旧地址 SPRING_DATASOURCE_URL、JVM -D、命令行参数是否覆盖文件
配置中心改了但实例没变化 客户端是否支持刷新；配置版本、监听机制和实例日志
密码出现在日志 禁止打印全量环境；限制 Actuator；轮换已泄露凭据

官方参考：Spring Boot Externalized Configuration。