容器与云原生 / 系统课时
配置服务环境变量
配置服务环境变量
本课用一个可直接运行的 Compose 示例,为 API 与 Worker 分别注入环境变量,并通过 .env、env_file 和变量插值复用环境差异。完成后,你将能切换测试与生产参数,并在启动前检查最终配置。
学习目标
- 区分 Compose 插值变量与容器环境变量
- 使用
environment、env_file为不同服务传值 - 用默认值、必填校验和
docker compose config降低配置错误
先区分两类变量
Compose 中容易混淆的是“生成配置时使用的变量”和“容器启动后能够读取的变量”。项目目录中的 .env 默认参与 ${变量名} 插值,但变量不会因此自动进入容器;只有通过 environment 或 env_file 声明后,容器进程才能读取它。
environment 适合少量、明确且需要覆盖的配置,env_file 适合成组复用服务变量。若两处定义了同名变量,服务的 environment 值会覆盖 env_file 中的值。
编写可复用配置
在空目录中创建以下三个文件。.env 保存 Compose 插值值,worker.env 只为 Worker 提供容器环境变量,compose.yaml 决定每个服务最终接收哪些值。
# compose.yaml
services:
api:
image: alpine:${ALPINE_TAG:-3.20}
environment:
APP_ENV: ${APP_ENV:?请设置 APP_ENV}
LOG_LEVEL: ${API_LOG_LEVEL:-info}
command:
- sh
- -c
- printf 'api env=%s log=%s\n' "$$APP_ENV" "$$LOG_LEVEL"
worker:
image: alpine:${ALPINE_TAG:-3.20}
env_file:
- ./worker.env
environment:
APP_ENV: ${APP_ENV:?请设置 APP_ENV}
command:
- sh
- -c
- printf 'worker env=%s log=%s\n' "$$APP_ENV" "$$LOG_LEVEL"这里的 ${APP_ENV} 由 Compose 在解析文件时替换,$$APP_ENV 则会保留为 $APP_ENV,交给容器中的 Shell 展开。必填表达式 ${APP_ENV:?...} 可在变量缺失时直接终止解析,避免容器带着空配置启动。
# .env
ALPINE_TAG=3.20
APP_ENV=development
API_LOG_LEVEL=debug# worker.env
LOG_LEVEL=warn.env 不应提交密码、令牌等敏感值。敏感信息应使用 Compose secrets、外部密钥服务或部署平台的机密变量管理能力。
检查插值结果
先让 Compose 输出解析后的模型,再运行两个一次性容器验证服务内的环境变量。config 适合在部署前发现缺失变量、路径错误和覆盖关系。
docker compose config
docker compose run --rm api
docker compose run --rm worker预期结果
配置输出中 api 的 APP_ENV 为 development、LOG_LEVEL 为 debug;
配置输出中 worker 的 APP_ENV 为 development,并引用 ./worker.env;
api env=development log=debug
worker env=development log=warn首次运行可能先显示镜像拉取信息。镜像下载进度、容器名称和时间属于动态内容,实际输出可能不同,但最后两行变量值应保持一致。
切换不同环境
需要切换环境时,不必修改 compose.yaml。创建 .env.test 或 .env.prod,再通过 --env-file 指定插值来源。未显式指定时,Compose 默认读取项目目录中的 .env。
docker compose --env-file .env.test config预期结果
Compose 使用 .env.test 中的值完成变量插值,并输出解析后的服务配置。使用环境文件时应保持变量名稳定,只让值随环境变化。多个服务共用的非敏感参数放在统一文件中,服务专属参数放在各自的 env_file,可减少重复和误覆盖。
常见错误
- 把
.env当成自动注入容器的文件,导致程序读取不到变量 - 在命令中写
$APP_ENV,被 Compose 提前解释;需要交给容器展开时应写$$APP_ENV - 只写
${VAR}而不设置默认值或必填校验,变量缺失后得到空字符串 - 把密码直接提交到环境文件仓库,造成凭据泄露
本课总结
.env主要为 Compose 插值提供值,容器变量仍需通过environment或env_file注入environment可覆盖env_file的同名变量,适合服务级差异配置- 启动前执行
docker compose config,可以确认插值、必填变量与最终模型
下一课预告
下一课将使用 depends_on 与健康检查编排服务依赖,让应用在数据库真正可用后再启动。