容器与云原生 / 系统课时

配置服务环境变量

配置服务环境变量

本课用一个可直接运行的 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 决定每个服务最终接收哪些值。

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:?...} 可在变量缺失时直接终止解析,避免容器带着空配置启动。

bash
# .env
ALPINE_TAG=3.20
APP_ENV=development
API_LOG_LEVEL=debug
bash
# worker.env
LOG_LEVEL=warn

.env 不应提交密码、令牌等敏感值。敏感信息应使用 Compose secrets、外部密钥服务或部署平台的机密变量管理能力。

检查插值结果

先让 Compose 输出解析后的模型,再运行两个一次性容器验证服务内的环境变量。config 适合在部署前发现缺失变量、路径错误和覆盖关系。

bash
docker compose config
docker compose run --rm api
docker compose run --rm worker

预期结果

text
配置输出中 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。

bash
docker compose --env-file .env.test config

预期结果

text
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 与健康检查编排服务依赖,让应用在数据库真正可用后再启动。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置服务环境变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通