Docker Compose 配置

⏱️最后更新: 2025/07/26

基础

yml

version: "3" # 版本号，一般使用最新版或适用版本
services: # 定义多个服务（容器）
  service_name:
    image: 镜像名
    ports:
      - "端口映射"
    environment:
      - 变量=值
    volumes:
      - 本地路径:容器路径
    networks:
      - 网络名

networks: #（可选）定义自定义网络
  network_name:

volumes: #（可选）定义数据卷
  volume_name:

🍒 version

指定 Compose 文件格式的版本。推荐使用 3.8 或更高版本。

🍒 services

定义应用程序中运行的各个服务（容器）
每个服务都代表一个 Docker 容器

🍦🍦 image

image: 指定用于创建容器的 Docker 镜像。可以是 Docker Hub 上的公共镜像，也可以是您自己构建的镜像。
yaml
```
services:
  web:
    image: nginx:latest
```

🍦🍦 build

build: 指定用于构建镜像的 Dockerfile 的路径。如果指定了 build，则不需要 image。

yaml

services:
  app:
    build: ./app # 指向包含 Dockerfile 的目录

您还可以指定 context 和 dockerfile：

yaml

services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile.dev

🍦🍦 container_name

container_name: 为容器指定一个自定义名称，而不是让 Docker Compose 自动生成。
yaml
```
services:
  db:
    container_name: my_database
    image: postgres:14
```

🍦🍦 ports

ports: 将容器的端口映射到主机的端口。格式为 "HOST:CONTAINER"。

yaml

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"

您可以省略主机端口，让 Docker 自动分配：

yaml

services:
  web:
    image: nginx:latest
    ports:
      - "80" # 映射到主机的随机端口

🍦🍦 volumes

volumes: 挂载卷或绑定挂载。

命名卷 (Named Volumes): 更推荐的方式，Docker 管理卷的生命周期。

yaml

volumes:
  db_data: # 定义一个命名卷

services:
  db:
    image: postgres:14
    volumes:
      - db_data:/var/lib/postgresql/data # 将命名卷挂载到容器内

绑定挂载 (Bind Mounts): 将主机上的文件或目录挂载到容器内。

yaml

services:
  app:
    build: ./app
    volumes:
      - ./app:/app # 将本地的 ./app 目录挂载到容器的 /app
      - ./config/nginx.conf:/etc/nginx/nginx.conf:ro # 挂载一个只读配置文件

🍦🍦 environment

environment: 设置容器内的环境变量。

yaml

services:
  app:
    image: python:3.9
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://user:password@db:5432/mydb

您也可以使用 .env 文件来管理环境变量，并在 docker-compose.yml 中使用 env_file。

yaml

# .env 文件
NODE_ENV=production
DATABASE_URL=postgres://user:password@db:5432/mydb

# docker-compose.yml
services:
  app:
    image: python:3.9
    env_file:
      - .env

🍦🍦 depends_on

depends_on: 指定服务的启动顺序。这不会等待依赖服务完全启动和运行，只是等待其容器启动。

yaml

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - app # web 服务会在 app 服务容器启动后启动

  app:
    build: ./app
    ports:
      - "5000:5000"
    depends_on:
      - db # app 服务会在 db 服务容器启动后启动

  db:
    image: postgres:14
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

🍦🍦 networks

networks: 将服务连接到指定的网络。

yaml

networks:
  frontend:
    driver: bridge # 指定网络驱动

services:
  web:
    image: nginx:latest
    networks:
      - frontend # 将 web 服务连接到 frontend 网络

🍦🍦 restart

restart: 指定容器退出时的重启策略。
- no: 不重启（默认）。
- on-failure: 仅在容器以非零退出码退出时重启。
- always: 无论退出码如何，始终重启。
- unless-stopped: 始终重启，但如果容器被手动停止，则不重启。
yaml
```
services:
  app:
    build: ./app
    restart: unless-stopped
```

🍦🍦 healthcheck

healthcheck: 定义健康检查，用于监测容器是否正常运行。

yaml

services:
  db:
    image: postgres:14
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"] # 执行命令检查
      interval: 10s # 每 10 秒检查一次
      timeout: 5s # 检查超时时间为 5 秒
      retries: 3 # 失败 3 次后认为容器不健康
      start_period: 30s # 容器启动后 30 秒内不计入失败次数

command: 覆盖镜像中定义的默认命令。

yaml

services:
  app:
    image: alpine
    command: ["ping", "localhost"]

🍦🍦 entrypoint

entrypoint: 覆盖镜像中定义的默认入口点。

yaml

services:
  app:
    image: alpine
    entrypoint: "/bin/sh"
    command: "-c 'echo Hello'"

🍦🍦 其他

hostname: 设置容器的主机名。
domainname: 设置容器的域名。
dns: 自定义 DNS 服务器。
extra_hosts: 添加自定义的主机名到 /etc/hosts 映射。
ulimits: 设置容器的 ulimit。

🍒 networks

允许您创建自定义网络，从而实现服务之间的隔离和通信。

driver: 指定网络驱动，最常用的是 bridge。
name: 指定网络的名称。
ipam: IP 地址管理配置，允许您指定子网等。

yaml

networks:
  my_app_net:
    driver: bridge
    ipam:
      config:
        - subnet: 192.168.99.0/24

🍒 volumes

用于定义持久化存储卷。

name: 卷的名称。
driver: 指定卷驱动，默认为 local。
driver_opts: 为卷驱动提供选项。

yaml

volumes:
  postgres_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/on/host/for/postgres_data # 绑定到主机上的目录（不推荐，通常使用命名卷）

扩展

扩展 (Extensions)

Compose 文件格式允许使用扩展点，例如 extends。

extends: 从另一个 Compose 文件或服务继承配置。

yaml

# docker-compose.yml
services:
  base_service:
    image: alpine:latest
    command: ["echo", "Hello"]

# docker-compose.override.yml
services:
  app:
    extends:
      file: docker-compose.yml
      service: base_service
    ports:
      - "8080:80"

当您运行 docker compose -f docker-compose.yml -f docker-compose.override.yml up 时，app 服务将继承 base_service 的配置，并添加自己的配置。

覆盖文件 (`docker-compose.override.yml`)

您可以使用多个 Compose 文件，并且后面的文件会覆盖前面的文件的配置。通常，docker-compose.yml 用于生产环境的定义，而 docker-compose.override.yml 用于开发环境的覆盖，例如：

重新构建镜像。
修改端口映射。
挂载本地代码目录。
设置开发相关的环境变量。

示例：

docker-compose.yml (生产环境定义)

yaml

version: "3.8"
services:
  app:
    image: my_app:production
    ports:
      - "80:8000"
    environment:
      NODE_ENV: production

docker-compose.override.yml (开发环境覆盖)

yaml

version: "3.8"
services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile.dev
    ports:
      - "3000:8000" # 映射到不同的端口
    volumes:
      - ./app:/app # 挂载本地代码
    environment:
      NODE_ENV: development

使用 docker compose up 运行，将同时应用这两个文件的配置。

变量插值 (`${VARIABLE}`)

您可以在 Compose 文件中使用环境变量来动态设置配置。

yaml

services:
  db:
    image: postgres:${POSTGRES_VERSION:-14} # 如果 POSTGRES_VERSION 未定义，则默认为 14
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}

可以在运行命令时设置这些变量： DB_USER=myuser DB_PASSWORD=mypassword docker compose up 或者通过 .env 文件。

版本兼容性

Docker Engine 版本	Compose 文件版本
19.03.0+	3.8
18.06.0+	3.7
18.02.0+	3.6
17.12.0+	3.5
17.09.0+	3.4
17.06.0+	3.3
17.04.0+	3.2

Docker Compose 配置

基础

🍒 version

🍒 services

🍦🍦 image

🍦🍦 build

🍦🍦 container_name

🍦🍦 ports

🍦🍦 volumes

🍦🍦 environment

🍦🍦 depends_on

🍦🍦 networks

🍦🍦 restart

🍦🍦 healthcheck

🍦🍦 entrypoint

🍦🍦 其他

🍒 networks

🍒 volumes

扩展

扩展 (Extensions)

覆盖文件 (docker-compose.override.yml)

变量插值 (${VARIABLE})

版本兼容性

覆盖文件 (`docker-compose.override.yml`)

变量插值 (`${VARIABLE}`)