Docker Compose 配置参数详解

什么是 Docker Compose

• Docker 是运行 单个容器 的工具

• Docker Compose 是运行 一组容器（多服务） 的工具

1️⃣ 顶级字段

version: "3.9"  # Compose 文件版本
services:       # 服务列表
volumes:        # 卷（持久化数据）
networks:       # 自定义网络
configs:        # 配置文件（Docker Swarm）
secrets:        # 秘密信息（Docker Swarm）

• version：指定 Compose 文件格式版本

  • V3+ 适合 Swarm / Kubernetes 部署

  • 也可以不写，默认最新版本

• services：必选字段，定义一组容器服务

• volumes / networks：可选，定义共享卷和自定义网络

• configs / secrets：Swarm 集群使用，用于配置管理和敏感信息

---

2️⃣ services 字段详解

每个服务类似一个容器，常用参数如下：

参数	类型	说明
build	string / dict	构建镜像的路径或配置，例如 . 或带 context、dockerfile
image	string	使用已有镜像，例如 postgres:15-alpine
container_name	string	容器名字（方便 docker ps 查看）
command	string / list	覆盖 Dockerfile CMD，指定容器启动命令
entrypoint	string / list	覆盖 Dockerfile ENTRYPOINT
environment	list / dict	环境变量，可用 ${VAR} 引用 .env 文件
ports	list	端口映射，格式 "宿主机:容器" 或 "8000:80/tcp"
volumes	list	挂载卷或目录，格式 "宿主机路径:容器路径"
depends_on	list	声明服务启动依赖，Compose 会按顺序启动
restart	string	容器重启策略，如 no, always, on-failure, unless-stopped
networks	list / dict	指定网络，默认在 default 网络下
working_dir	string	容器内工作目录（类似 Dockerfile WORKDIR）
user	string	以指定用户运行容器，例如 "1000:1000"
tty	bool	是否分配伪终端，调试用
stdin_open	bool	是否保持 stdin 打开
healthcheck	dict	健康检查配置，例如命令、间隔、重试次数
depends_on.condition	string	可指定依赖启动条件：service_started、service_healthy

---

2.1 build 参数支持

build:
  context: .         # 构建上下文路径
  dockerfile: Dockerfile.prod  # 指定 Dockerfile 文件
  args:               # 构建时变量
    APP_ENV: production
  target: builder     # 多阶段构建阶段

---

2.2 environment 支持格式

environment:
  - DEBUG=1
  - SECRET_KEY=${SECRET_KEY}
# 或者字典方式
environment:
  DEBUG: "1"
  SECRET_KEY: "${SECRET_KEY}"

• 可以在项目根目录放 .env 文件，Compose 会自动读取

• 可在命令行 docker compose up --env-file ./myenv 指定文件

---

2.3 volumes 支持

volumes:
  - ./code:/app       # 本地目录挂载
  - postgres_data:/var/lib/postgresql/data  # 命名卷
  - type: bind
    source: ./config
    target: /app/config
    read_only: true

---

2.4 ports 支持

ports:
  - "8000:8000"       # host:container
  - "443:443/tcp"     # 指定协议

---

2.5 restart 策略

策略	说明
no	不自动重启（默认）
always	容器退出无论状态都重启
on-failure	仅在非 0 退出码时重启
unless-stopped	除非手动停止，否则重启

---

2.6 healthcheck 健康检查

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 5s

• 容器状态会标记为 healthy / unhealthy

• 可以配合 depends_on.condition: service_healthy 控制启动顺序

---

3️⃣ volumes & networks

3.1 volumes（持久化数据）

volumes:
  postgres_data:
  redis_data:

• 命名卷由 Docker 管理

• 也可以直接挂载宿主机路径

3.2 networks（自定义网络）

networks:
  frontend:
  backend:

• Compose 会默认创建 default 网络

• 可以自定义网络，控制服务间通信范围

---

4️⃣ docker-compose 常用命令

命令	说明
docker compose up	构建并启动服务
docker compose up -d	后台启动
docker compose down	停止并删除容器、网络
docker compose build	构建镜像
docker compose logs	查看日志
docker compose exec <service> bash	进入容器
docker compose ps	查看服务状态
docker compose stop/start/restart	停止/启动/重启服务
docker compose config	查看完整配置，合并继承、环境变量

---

5️⃣ 高级技巧

1. 多环境配置

   • dev / prod 两个 Compose 文件：

     docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

   • 后面文件会覆盖前面的设置

2. 扩缩容

   docker compose up --scale worker=3 -d

   • worker 容器可以水平扩展

3. 依赖顺序

   • depends_on + healthcheck 配合使用，确保服务按顺序启动

4. 共享镜像

   • 多个服务可以使用同一个 build: . 或 image: xxx

   • 只构建一次镜像，多容器共享

---

✅ 总结

• Docker Compose 核心是 services

• 常用参数：build, image, volumes, ports, environment, depends_on, command, restart

• 高级特性：healthcheck, 多环境 override, scale

• volumes 挂载宿主机目录适合开发，生产通常用命名卷