Docker Compose Override

什么是 Compose Override

在实际项目中，应用通常需要在不同的环境中运行——本地开发、CI/CD 测试、预发布验证、生产部署。每个环境对服务的配置需求各不相同：

• 本地开发：需要源码热更新、调试端口、更低的资源限制
• CI/CD 测试：需要自动退出、测试报告输出、并行执行
• 预发布：需要与生产一致的配置但使用测试数据
• 生产环境：需要高可用、资源限制、日志管理、安全加固

Docker Compose Override 机制正是为了解决这个多环境配置管理问题而设计的。它允许你定义一个基础配置文件（通常命名为 docker-compose.yml），然后通过一个或多个覆盖文件（override 文件）针对不同环境进行定制，而无需修改基础配置。

核心原理：YAML 深度合并

合并规则详解

Docker Compose 的合并策略基于 YAML 的数据类型：

1. 标量值（Scalar）— 覆盖

# docker-compose.yml
services:
  web:
    image: myapp:latest
    command: npm start
    environment:
      - NODE_ENV=production

---
# docker-compose.override.yml
services:
  web:
    image: myapp:dev          # 覆盖：dev 镜像替换 latest
    command: npm run dev       # 覆盖：dev 命令替换 start
    environment:
      - NODE_ENV=development  # 覆盖：development 替换 production

2. 映射/字典（Mapping/Dict）— 递归合并

# docker-compose.yml
services:
  web:
    environment:
      DB_HOST: prod-db.internal
      DB_PORT: "5432"
      CACHE_HOST: redis-prod

---
# docker-compose.override.yml
services:
  web:
    environment:
      DB_HOST: localhost       # 覆盖 DB_HOST
      DEBUG: "true"            # 新增 DEBUG
      # DB_PORT 和 CACHE_HOST 保留原值（合并）

合并结果：

environment:
  DB_HOST: localhost    # 被 override 覆盖
  DB_PORT: "5432"       # 保留
  CACHE_HOST: redis-prod # 保留
  DEBUG: "true"         # 新增

3. 序列/数组（Sequence/Array）— 追加

# docker-compose.yml
services:
  web:
    ports:
      - "8080:80"
    volumes:
      - app-data:/app/data

---
# docker-compose.override.yml
services:
  web:
    ports:
      - "9229:9229"    # 追加调试端口，不会替换 8080:80
    volumes:
      - ./src:/app/src # 追加源码挂载，不会替换 app-data

合并结果：

ports:
  - "8080:80"      # 保留
  - "9229:9229"    # 追加
volumes:
  - app-data:/app/data  # 保留
  - ./src:/app/src      # 追加

4. 特殊字段的处理

# docker-compose.yml
services:
  web:
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M

---
# docker-compose.override.yml
services:
  web:
    deploy:
      replicas: 1         # 覆盖副本数
      resources:
        limits:
          memory: 256M    # 覆盖内存限制
          cpus: "2.0"     # 新增 CPU 限制
      restart_policy:     # 新增重启策略
        condition: on-failure

基础 Override 示例

最简项目结构

project/
├── docker-compose.yml                 # 基础配置（提交到 Git）
├── docker-compose.override.yml        # 本地开发覆盖（加入 .gitignore）
├── docker-compose.override.example.yml # 模板文件（提交到 Git）
├── docker-compose.prod.yml            # 生产环境配置（提交到 Git）
├── docker-compose.test.yml            # 测试环境配置（提交到 Git）
├── .env                               # 环境变量（加入 .gitignore）
└── .env.example                       # 环境变量模板（提交到 Git）

# docker-compose.yml（基础配置 — 所有环境共享，提交到 Git）
version: "3.8"

services:
  web:
    image: myapp:latest
    ports:
      - "8080:80"
    environment:
      - APP_ENV=production
      - DB_HOST=${DB_HOST:-db}
      - DB_PASSWORD=${DB_PASSWORD}
    depends_on:
      - db
      - redis
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  pg-data:
  redis-data:

# docker-compose.override.yml（本地开发覆盖 — 不提交 Git）
version: "3.8"

services:
  web:
    build: .                          # 使用本地构建替代远程镜像
    volumes:
      - ./src:/app/src                # 源码热更新
      - ./config/dev:/app/config:ro   # 开发配置
    environment:
      - APP_ENV=development
      - DEBUG=true
      - LOG_LEVEL=debug
    command: npm run dev               # 开发模式启动
    ports:
      - "9229:9229"                   # Node.js 调试端口

# .gitignore 添加以下内容
docker-compose.override.yml
.env

查看合并后的最终配置

# 查看合并后的完整配置（非常重要！）
docker compose config

# 只查看服务配置
docker compose config --services

# 将合并结果输出到文件（用于审计）
docker compose config > merged-compose.yml

# 验证配置文件语法（不实际启动）
docker compose config --quiet && echo "Config is valid"

多环境配置模式

模式一：双文件模式（开发 + 生产）

docker-compose.yml          # 基础配置
docker-compose.override.yml # 开发覆盖（本地自动加载）
docker-compose.prod.yml     # 生产覆盖（CI/CD 显式加载）

# docker-compose.prod.yml
version: "3.8"

services:
  web:
    image: registry.example.com/myapp:v2.1.0
    restart: always
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.5"
          memory: 256M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - APP_ENV=production
    # 生产环境不挂载源码目录
    # 没有 volumes 和 command 覆盖
    # 没有 debug 端口

  db:
    volumes:
      - pg-prod-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}

  redis:
    volumes:
      - redis-prod-data:/data

volumes:
  pg-prod-data:
    external: true
  redis-prod-data:
    external: true

# 开发环境（自动加载 override）
docker compose up

# 生产环境（显式指定，不加载 override）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

模式二：多文件叠加模式（开发 + 测试 + 预发布 + 生产）

docker-compose.yml           # 基础配置
docker-compose.override.yml  # 开发覆盖
docker-compose.test.yml      # 测试覆盖
docker-compose.staging.yml   # 预发布覆盖
docker-compose.prod.yml      # 生产覆盖

# docker-compose.test.yml
version: "3.8"

services:
  web:
    build:
      context: .
      target: test            # 使用测试阶段的镜像
    command: npm run test:ci  # 运行测试
    environment:
      - NODE_ENV=test
      - DB_HOST=test-db
    depends_on:
      - test-db

  test-db:
    image: postgres:15
    environment:
      - POSTGRES_DB: myapp_test
      - POSTGRES_PASSWORD: test_pass
    tmpfs:
      - /var/lib/postgresql/data  # 测试数据不持久化

# docker-compose.staging.yml
version: "3.8"

services:
  web:
    image: registry.example.com/myapp:${VERSION:-latest}
    restart: always
    environment:
      - APP_ENV=staging
      - DB_HOST=staging-db.internal
    deploy:
      replicas: 2

# 测试环境
docker compose -f docker-compose.yml -f docker-compose.test.yml up --abort-on-container-exit

# 预发布环境
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d

# 生产环境
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

模式三：环境变量 + .env 文件

Docker Compose 支持通过 .env 文件和 shell 环境变量来参数化配置：

# .env 文件（不提交到 Git）
DB_HOST=prod-db.internal
DB_PASSWORD=S3cureP@ss!
REDIS_HOST=redis-prod.internal
APP_VERSION=v2.1.0

# .env.example 文件（提交到 Git）
DB_HOST=your-db-host
DB_PASSWORD=your-db-password
REDIS_HOST=your-redis-host
APP_VERSION=v1.0.0

# docker-compose.yml 中使用环境变量
services:
  web:
    image: myapp:${APP_VERSION:-latest}
    environment:
      - DB_HOST=${DB_HOST}
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=${REDIS_HOST}

# 指定自定义 .env 文件
docker compose --env-file .env.production up -d

生产环境最佳实践

完整的生产 Compose 配置

# docker-compose.prod.yml
version: "3.8"

services:
  web:
    image: registry.example.com/myapp:${APP_VERSION:-v2.1.0}
    restart: always
    read_only: true                  # 只读文件系统
    tmpfs:
      - /tmp:size=100m,mode=1777
      - /run:size=10m
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    ports:
      - "127.0.0.1:8080:80"         # 只监听 localhost
    environment:
      - APP_ENV=production
      - DB_HOST=${DB_HOST}
      - DB_PASSWORD=${DB_PASSWORD}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 30s
        failure_action: rollback
        monitor: 60s
      rollback_config:
        parallelism: 0
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
        tag: "{{.Name}}/{{.ID}}"

  db:
    image: postgres:15
    restart: always
    volumes:
      - pg-prod-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2Gi
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

  redis:
    image: redis:7-alpine
    restart: always
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
    volumes:
      - redis-prod-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
    deploy:
      resources:
        limits:
          memory: 768M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  pg-prod-data:
    external: true
    name: production-pg-data
  redis-prod-data:
    external: true
    name: production-redis-data

生产部署脚本

#!/bin/bash
# deploy.sh — 生产环境部署脚本
set -euo pipefail

COMPOSE_DIR="/opt/myapp"
ENV_FILE="${COMPOSE_DIR}/.env.production"

# 加载环境变量
source "$ENV_FILE"

echo "Deploying myapp:${APP_VERSION}..."

# 验证配置合并结果
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file "$ENV_FILE" config --quiet

# 拉取最新镜像
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file "$ENV_FILE" pull

# 滚动更新
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file "$ENV_FILE" up -d --remove-orphans

# 等待健康检查通过
echo "Waiting for health checks..."
sleep 30

# 验证部署
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file "$ENV_FILE" ps

# 清理旧镜像
docker image prune -f

echo "Deployment completed successfully"

CI/CD 集成

GitHub Actions 示例

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests with test override
        run: |
          docker compose -f docker-compose.yml -f docker-compose.test.yml \
            up --build --abort-on-container-exit

      - name: Cleanup
        if: always()
        run: |
          docker compose -f docker-compose.yml -f docker-compose.test.yml down -v

  deploy-staging:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to staging
        run: |
          docker compose -f docker-compose.yml -f docker-compose.staging.yml \
            up -d --build --remove-orphans

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Validate production config
        run: |
          docker compose -f docker-compose.yml -f docker-compose.prod.yml config --quiet

      - name: Deploy to production
        run: |
          docker compose -f docker-compose.yml -f docker-compose.prod.yml \
            up -d --remove-orphans

Compose Profiles（补充方案）

Docker Compose Profiles 是 override 机制的补充，用于按场景选择性启动服务：

# docker-compose.yml
version: "3.8"

services:
  web:
    image: myapp:latest
    profiles: ["frontend"]       # 只在 frontend profile 下启动
    ports:
      - "8080:80"

  api:
    image: myapi:latest
    profiles: ["backend"]        # 只在 backend profile 下启动
    ports:
      - "3000:3000"

  db:
    image: postgres:15
    # 没有 profiles 字段 = 始终启动

  debug-tools:
    image: nicolaka/netshoot
    profiles: ["debug"]          # 只在调试时启动

# 启动基础服务 + frontend
docker compose --profile frontend up -d

# 启动基础服务 + backend
docker compose --profile backend up -d

# 启动所有服务（包括 debug）
docker compose --profile frontend --profile backend --profile debug up -d

# 列出哪些服务属于哪个 profile
docker compose config --profiles

优点

• 1.零侵入定制 — 本地开发配置完全不修改共享的主 docker-compose.yml
• 2.团队协作友好 — 每个开发者可以有独立的 override 文件，不会互相影响
• 3.环境一致性 — 所有环境共享同一个基础配置，降低配置漂移风险
• 4.CI/CD 集成简单 — 流水线中通过 -f 参数精确控制加载哪些配置文件
• 5.可审计性 — docker compose config 可以查看最终合并结果，便于验证

缺点

• 1.合并行为不直观 — 数组合并（追加）vs 字典合并（覆盖）容易混淆，调试困难
• 2.隐式加载风险 — 自动加载 override 可能在生产环境意外生效
• 3.复杂场景受限 — 无法删除主配置中已定义的服务或端口，只能追加或覆盖
• 4.调试成本高 — 最终生效的配置需要 docker compose config 命令查看合并结果
• 5.文件数量膨胀 — 环境越多，compose 文件越多，管理复杂度线性增长

总结

Docker Compose Override 是多环境配置管理的轻量级方案，适合中小型项目。使用时务必理解合并策略，生产部署应显式指定 -f 参数避免 override 意外加载，并养成用 docker compose config 验证最终配置的习惯。

对于更复杂的多环境需求，可以考虑以下替代方案：

• Docker Compose Profiles：按场景选择性启动服务组
• Helm + Kubernetes：云原生方案，通过 values 文件管理多环境配置
• Kustomize：Kubernetes 原生的配置覆盖方案，与 Compose override 思路一致但更强大

关键知识点

• docker-compose.override.yml 在 docker compose up 时被自动加载，无需显式指定
• 多文件叠加时，后面的文件覆盖前面文件中相同 key 的值
• 用 docker compose config 命令可查看合并后的最终配置
• 数组类型的字段（ports、volumes）是追加而非替换
• 标量类型的字段（image、command）是覆盖而非合并
• 映射类型的字段（environment、deploy）是递归合并

项目落地视角

• 将 docker-compose.yml 作为基础配置提交到 Git，docker-compose.override.yml 加入 .gitignore
• 为生产环境创建独立的 docker-compose.prod.yml，在 CI/CD 中显式引用
• 团队统一 override 的使用规范，避免开发者随意覆盖关键配置
• 建立 docker compose config 校验步骤，确保配置合并结果符合预期
• 使用 .env 文件管理敏感配置，将 .env.example 提交到 Git 作为模板

常见误区

• 以为 override 文件必须叫 docker-compose.override.yml，实际上任意文件名都可以通过 -f 指定
• 在 override 中定义新服务但忘记声明依赖关系，导致启动顺序错误
• 生产环境忘记排除 override 文件，导致开发配置泄漏到生产
• 不使用 docker compose config 验证，依赖猜测来判断合并结果
• 在 override 中试图删除主配置中已定义的端口或环境变量（实际上做不到）

进阶路线

• 学习 Docker Compose profiles 功能，按场景选择性激活服务组
• 掌握 docker compose 的 extends 继承机制，实现服务模板复用
• 了解 Kubernetes Kustomize 的 overlay 机制，它与 Compose override 思路一致但更强大
• 学习 Helm 的 values 文件覆盖机制，理解云原生的多环境配置管理

适用场景

• 多人协作项目中每个开发者需要独立的本地开发配置
• 同一项目需要在不同环境（dev/staging/prod）使用不同服务配置
• CI/CD 流水线需要在不同阶段使用不同的 Compose 配置
• 需要按需启用/禁用某些辅助服务（如调试工具、监控组件）

落地建议

• 在项目根目录创建 docker-compose.override.example.yml 作为模板，新成员复制后修改
• 生产部署脚本中显式使用 -f docker-compose.yml -f docker-compose.prod.yml，禁止自动加载
• 在 CI 中增加 docker compose config 校验步骤，确保配置合并结果正确
• 将所有 compose 文件和 .env.example 纳入版本控制，确保团队使用一致的配置基线
• 定期审查 compose 文件，清理不再使用的服务配置和 volume 声明

排错清单

• 合并结果不符合预期时，运行 docker compose config 查看最终配置
• 端口冲突时检查是否多个 compose 文件追加了相同端口
• 环境变量未生效时确认 override 中的 environment 字段 key 是否与主配置一致
• 生产环境出现了开发配置，检查是否意外加载了 override 文件
• 服务启动顺序异常，检查 depends_on 和 healthcheck 是否正确配置

复盘问题

• 当前项目的 Compose 配置分层是否清晰？是否存在 override 中包含生产关键配置的情况？
• 团队成员是否都理解 merge 策略？是否出现过配置覆盖导致的事故？
• CI/CD 中的 Compose 配置是否与本地开发配置保持同步？
• 是否有自动化校验来防止配置合并错误？

延伸阅读

• Docker Compose 生产实践
• Docker Compose 进阶
• Docker Volume 持久化
• Docker 安全实践