15.8.8 多环境与扩展文件（override、profiles）

多环境与扩展文件（override、profiles）#

在实际运维中，开发、测试、预生产、生产环境的配置差异较大。Compose 通过多文件叠加与 profiles 实现环境化编排，形成“基础配置 + 环境差异”的模式，便于复用与维护。

原理草图：多文件叠加与 profiles 生效路径

1. 安装与版本检查（Docker Compose Plugin）

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y docker-compose-plugin

# 版本检查
docker compose version

• 预期：输出 Docker Compose version v2.x
• 若无 compose 子命令，检查 Docker 版本并重新安装插件。

2. 基础文件与环境覆盖文件示例（完整可执行）
目录结构：

/opt/compose-demo/
├── docker-compose.yml
├── docker-compose.dev.yml
└── docker-compose.prod.yml

基础文件 /opt/compose-demo/docker-compose.yml：

services:
  web:
    image: nginx:1.25
    ports:
      - "8080:80"
    environment:
      NGINX_ENV: base
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost/ || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3

  app:
    image: busybox:1.36
    command: ["sh","-c","echo APP_ENV=$APP_ENV; sleep 3600"]
    environment:
      APP_ENV: base

开发覆盖文件 /opt/compose-demo/docker-compose.dev.yml：

services:
  web:
    ports:
      - "8081:80"         # 覆盖端口映射
    environment:
      NGINX_ENV: dev      # 按键覆盖

  app:
    environment:
      APP_ENV: dev

生产覆盖文件 /opt/compose-demo/docker-compose.prod.yml：

services:
  web:
    ports:
      - "80:80"
    environment:
      NGINX_ENV: prod
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

3. 覆盖规则与命令示例
- 后加载文件覆盖前文件的同名服务字段：

cd /opt/compose-demo
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

• 关键字段解释：
• -f：指定多个 Compose 文件，按顺序合并
• up -d：创建并后台启动服务
• 验证生效：

docker compose ps
docker compose exec app sh -c 'echo $APP_ENV'

• 预期：输出 dev，端口为 8081:80

4. profiles 条件化启用示例
在基础文件中追加可选服务：

services:
  debug:
    image: alpine:3.19
    command: ["sh","-c","sleep 3600"]
    profiles: ["debug"]

启动命令：

# 不带 profile 不会启动 debug
docker compose up -d

# 指定 profile 才启动
docker compose --profile debug up -d

• 关键参数解释：
• --profile debug：仅启用标记为 debug 的服务

5. 组合策略（开发/生产）

# 开发：基础 + dev 覆盖 + debug profile
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile debug up -d

# 生产：基础 + prod 覆盖（不启用 debug）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

6. 排错与常见问题定位
- 端口重复（列表合并导致）
- 现象：bind: address already in use
- 排查：检查多个文件对 ports 的合并
- 处理：在覆盖文件中显式替换或设置为空列表

services:
  web:
    ports: []   # 清空基础列表

• 配置未生效（文件顺序错误）
• 现象：仍使用基础端口或环境变量
• 排查：确认 -f 顺序
• 合并结果验证

docker compose -f docker-compose.yml -f docker-compose.dev.yml config

• 预期：输出最终合并的配置

7. 命令速查与解释

docker compose config                 # 展示合并后的最终配置
docker compose up -d                  # 创建并后台启动
docker compose down                   # 停止并删除容器/网络
docker compose ps                     # 查看服务状态
docker compose logs -f web            # 实时查看指定服务日志

8. 练习
1. 基于示例目录，创建 docker-compose.test.yml，将 web 端口改为 8082:80，并验证生效。
2. 为 app 增加 profiles: ["bench"]，使用 --profile bench 启动并确认容器出现。
3. 使用 docker compose config 对比 dev 与 prod 的合并差异，记录环境变量与端口变化。