开发排障笔记

深浅主题

环境变量与配置优先级 ​

问题现象 ​

配置文件已经修改但应用仍用旧值，本地与服务器行为不同，或容器重启后变量没有变化。

适用环境 ​

Spring Boot 3、Docker Compose；不同版本应核对对应文档。

本文是可复用的排障示例，不代表某次个人生产事故。命令中的名称、账号和数据均为示例，执行前请替换为已确认的目标。

复现或诊断步骤 ​

  1. 确认正在运行的镜像版本、启动参数、激活 profile 与配置挂载路径。
  2. 区分 Compose 的变量插值 .env 和实际注入容器的 environment/env_file。
  3. 在受控环境只检查目标配置项的来源；不要输出完整 env、docker inspect 环境或未脱敏 Actuator env。

原因分析 ​

Spring 外部配置存在优先级，命令行参数、环境变量和配置文件可能互相覆盖。Compose .env 默认用于插值，并不自动注入所有变量。修改宿主机文件后，只 restart 旧容器通常不会重新应用 Compose 环境声明。

修复示例 ​

yaml
services:
  api:
    image: example/api:1.0
    environment:
      SPRING_PROFILES_ACTIVE: prod
      APP_FEATURE_ENABLED: '${APP_FEATURE_ENABLED:-false}'
    volumes:
      - ./application-prod.yml:/config/application-prod.yml:ro
# APP_FEATURE_ENABLED 对应应用属性 app.feature.enabled
# 先检查目标项与有效配置，再按计划 docker compose up -d api

为配置建立明确来源和默认值，记录哪些需要重建容器、哪些由应用动态刷新。验证 Compose 展开结果时不要把包含秘密的完整输出留在报告中。变更前保存旧文件和镜像标识，按单服务更新；失败恢复旧配置并重新创建容器。

验证方法 ​

在测试环境给不同来源设置互异的非敏感值，验证最终取值。更新后确认容器创建时间、profile 和应用行为；检查重启后配置保持一致，不能只看文件内容。

常见误区 ​

把 .env 当秘密保险箱不安全。不要在排障时开启未鉴权的 env 端点；字符串 false 在某些脚本中仍是真值，必须按目标类型解析。

官方参考链接 ​

相关分类：部署与运维 · 全部笔记