Docker Compose 完全参考：v2 配置字典与实战

Compose 是 Docker 官方推出的多容器编排工具——把一组容器 / 网络 / 卷 / 配置用一份 YAML 描述，docker compose up 一键拉起。从 v1（Python 实现）到 v2（Go 插件化，2020-08 GA）经历了一次大重构，v2 速度更快、不再是 Python 副作用、字段语义和 v1 大体兼容。

这一篇把 compose 文件的所有常用字段按 services / networks / volumes 三大块组织成速查字典，配实战示例。

阅读对象：用 docker compose 编排多服务、想系统了解每个字段的开发者 / 运维 覆盖范围：compose v1 vs v2 差异 + service 字段字典 + networks / volumes 顶层 + 实战 YAML + compose 常用命令

一、Compose v1 vs v2：先搞清楚用哪个

维度	v1	v2
命令	`docker-compose`（带横线）	`docker compose`（空格）
实现	Python	Go（Docker CLI 插件）
启动速度	慢（要启 Python 解释器）	快（Go 二进制）
Compose Spec	1.x - 3.x	3.8+ 兼容 Spec
K8s 集成	实验性 `kompose`	内置 `docker compose convert`
维护	已停止新特性	当前主推

2023 年后：docker compose (v2) 是事实标准。新项目不要再用 v1。

二、Compose 文件结构总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# 顶层 keys（按规范顺序）
version: "3.8"          # 文件格式版本（v2 中可选，但建议保留）
name: "my-project"      # v2.20+ 项目名（影响容器前缀）

services:               # 必填：所有服务
  web:
    image: nginx:latest
    # ... 50+ 字段

networks:               # 可选：自定义网络
  frontend:
  backend:

volumes:                # 可选：命名卷
  db-data:

configs:                # 可选：配置文件
  app-config:

secrets:                # 可选：密钥
  db-password:

Spec 是什么：Compose Spec 是 v2.0 起的"格式规范"——docker compose、Kompose、docker stack deploy、podman compose 都按这个规范解析 YAML。比 v1 的 version: 3.x 更通用。

三、service 字段字典

3.1 镜像 / 构建

字段	作用	版本
`image`	指定镜像	全部
`build`	构建路径或对象	全部
`build.context`	Dockerfile 所在目录	v2 起
`build.dockerfile`	Dockerfile 名（默认 `Dockerfile`）	v2 起
`build.args`	`ARG` 参数	v2 起
`build.cache_from`	缓存来源镜像列表	v3.2+
`build.labels`	构建后打 labels	v3.3+
`build.shm_size`	`/dev/shm` 大小	v3.5+

示例：

1
2
3
4
5
6
7
8
9
services:
  web:
    build:
      context: ./app
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production
      cache_from:
        - myapp:cache

3.2 启动 / 运行时

字段	作用
`command`	覆盖默认启动命令（支持 shell 格式或 `[]` 格式）
`entrypoint`	覆盖默认入口点
`container_name`	指定容器名（`docker run --name` 等价）
`working_dir`	工作目录
`user`	容器内运行用户
`tty` / `stdin_open`	是否分配 TTY / 保持 stdin
`privileged`	特权模式
`init`	容器内跑 init 进程（PID 1，正确转发信号）

示例：

1
2
3
4
5
6
7
8
services:
  api:
    image: myapi:latest
    command: ["python", "manage.py", "runserver", "0.0.0.0:8000"]
    user: "1000:1000"
    init: true
    tty: true
    working_dir: /app

3.3 端口 / 网络

字段	作用
`ports`	端口映射（`HOST:CONTAINER`）
`expose`	暴露端口（容器间可访问，不映射到宿主机）
`networks`	加入指定网络
`network_mode`	单一网络模式（如 `host`）
`dns` / `dns_search`	自定义 DNS
`extra_hosts`	加 `/etc/hosts` 条目
`hostname`	容器主机名
`domainname`	域名
`mac_address`	MAC 地址

ports 短语法：

1
2
3
4
5
6
7
ports:
  - "3000"                          # 容器 3000 端口，宿主机随机
  - "3000-3005"                     # 范围
  - "8000:8000"                     # 宿主机 8000:容器 8000
  - "9090-9091:8080-8081"           # 范围映射
  - "127.0.0.1:8001:8001"           # 指定宿主机 IP
  - "6060:6060/udp"                 # 指定协议

ports 长语法（v3.2+）：

1
2
3
4
5
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

networks 与固定 IP：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
services:
  test:
    image: nginx:1.14-alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10

networks:
  app_net:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24

3.4 存储 / 卷

字段	作用
`volumes`	挂载卷 / 目录
`tmpfs`	挂载 tmpfs（v2+）
`read_only`	根文件系统只读

短语法：

1
2
3
4
5
6
volumes:
  - /var/lib/mysql                  # 匿名卷
  - /opt/data:/var/lib/mysql        # bind mount
  - ./cache:/tmp/cache              # 相对路径 bind
  - ~/configs:/etc/configs/:ro      # 只读
  - datavolume:/var/lib/mysql       # 引用顶层命名卷

长语法（v3.2+）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
volumes:
  - type: volume
    source: mydata
    target: /data
    volume:
      nocopy: true
  - type: bind
    source: ./static
    target: /opt/app/static
    read_only: true

3.5 环境变量 / 配置

字段	作用
`environment`	内联环境变量
`env_file`	从文件读环境变量
`secrets`	挂载 secret（来自顶层 secrets）
`configs`	挂载 config（来自顶层 configs）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
services:
  app:
    environment:
      DB_HOST: db
      DB_PORT: 5432
    env_file:
      - .env
      - .env.production
    configs:
      - source: app-config
        target: /app/config.json

优先级：environment > env_file > 镜像内 ENV

3.6 依赖 / 健康检查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
services:
  web:
    depends_on:
      db:
        condition: service_healthy    # v2 起
      redis:
        condition: service_started    # 默认

  db:
    image: postgres:14
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

condition: service_healthy 必须配 healthcheck 才生效——v2 起推荐用这个替代 wait-for-it 脚本。

3.7 资源限制 / 重启

字段	作用
`restart`	`no` / `always` / `on-failure` / `unless-stopped`
`deploy.resources.limits`	CPU / 内存上限（`docker stack` 用）
`cpus` / `cpuset`	v1 兼容字段，`docker compose` 仍支持
`mem_limit` / `memswap_limit`	v1 兼容内存限制
`ulimits`	ulimit 列表
`pids_limit`	PID 上限
`logging`	日志驱动（`json-file` / `syslog` / `fluentd`）
`shm_size`	`/dev/shm` 大小
`stop_grace_period`	收到 SIGTERM 后等待秒数（默认 10s）
`stop_signal`	停止信号（默认 SIGTERM）

资源限制示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
services:
  api:
    image: myapi:latest
    deploy:
      resources:
        limits:
          cpus: "0.5"      # 50% 单核
          memory: 512M
        reservations:
          cpus: "0.2"      # 预留 20%
          memory: 128M
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

Why 用 deploy.resources 而不是 mem_limit：前者是 Compose Spec 规范字段，后者是 v1 兼容字段。新项目用前者。

3.8 其他

字段	作用
`labels`	Docker 标签（`LABEL` 等价）
`pid`	`host` 表示共享宿主机 PID namespace
`ipc`	共享 IPC namespace
`security_opt`	SELinux / AppArmor 选项
`cap_add` / `cap_drop`	Linux capabilities
`devices`	设备映射（`docker run --device`）
`links`	链接到其他容器（已废弃，用 networks）
`external_links`	链接到 compose 外的容器
`isolation`	隔离技术（仅 `default` / `process` / `hyperv`）
`runtime`	指定 runtime（`runc` / `runsc` 沙箱）
`profiles`	启用 profile（条件启动）

profiles 示例：

1
2
3
4
5
6
7
services:
  api:
    image: myapi:latest

  debug-tools:
    image: mydebug:latest
    profiles: ["debug"]

1
2
3
4
# 默认 up 不启动 debug-tools
docker compose up
# 加 profile 启动
docker compose --profile debug up

四、networks 顶层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true    # 不通外网
  monitoring:
    driver: overlay   # 跨主机
  external_net:
    external: true    # 引用已创建的网络
    name: my-pre-existing-network

internal: true：内网隔离的 bridge——容器能互相访问，不能访问外网。数据库 / 缓存很适合。

五、volumes 顶层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
volumes:
  db-data:
    driver: local
    driver_opts:
      type: "nfs"
      o: "addr=10.0.0.10,nolock,soft,rw"
      device: ":/path/to/dir"
  shared:
    external: true
    name: my-pre-existing-volume

六、完整实战示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
version: "3.8"

services:
  redis:
    image: redis:alpine
    ports:
      - "6379"
    networks:
      - frontend
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

  db:
    image: postgres:14
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      placement:
        constraints: [node.role == manager]

  web:
    build: ./app
    ports:
      - "8080:8080"
    networks:
      - frontend
      - backend
    depends_on:
      redis:
        condition: service_healthy
      db:
        condition: service_started
    environment:
      REDIS_HOST: redis
      DB_HOST: db
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

networks:
  frontend:
  backend:
    internal: true

volumes:
  db-data:

关键点：
web 同时加入 frontend 和 backend 网络——能访问 redis 和 db
db 在 internal: true 的 backend 网络——不能访问外网
redis 多副本 + 滚动更新配置
web 资源限制

七、Compose 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 启动
docker compose up -d

# 启动指定服务
docker compose up -d web

# 不重建已停止的容器
docker compose up -d --no-recreate

# 停止 / 启动
docker compose stop
docker compose start

# 停掉 + 销毁容器
docker compose down          # 保留卷
docker compose down -v       # 同时删卷（**危险**）
docker compose down --rmi all  # 同时删镜像

# 查看状态
docker compose ps
docker compose logs -f web

# 进入容器
docker compose exec web bash

# 在 web 容器内跑一次性命令
docker compose run --rm web python manage.py migrate

八、字段优先级与兼容性

字段类型	优先级
`environment`	> `env_file` > 镜像 `ENV`
`command`	覆盖镜像 `CMD`
`entrypoint`	覆盖镜像 `ENTRYPOINT`
`ports` + `expose`	都可以，`ports` 同时映射到宿主机

v1 → v2 字段迁移：

v1 字段	v2 推荐
`mem_limit`	`deploy.resources.limits.memory`
`memswap_limit`	`deploy.resources.limits.memory`（swap 用 flag）
`cpus` / `cpuset`	`deploy.resources.limits.cpus`
`volume_driver`	`driver_opts`（在 volumes 顶层）
`extends`	已移除（用 `include` 或合并 YAML）

九、要点回顾

Compose v2 (docker compose) 是当前主推，不要再用 v1 (docker-compose)
services 是必填顶层，networks / volumes / configs / secrets 可选
build 支持对象语法（context + dockerfile + args）
depends_on: condition: service_healthy 替代 wait-for-it 脚本
deploy.resources.limits 才是规范字段，mem_limit 是 v1 兼容
internal: true 给敏感服务（数据库）做网络隔离
profiles 区分"开发 / 调试 / 生产"不同场景
docker compose down -v 是核弹——会删数据卷

十、小结

Compose v2 是个"看似简单、字段多到爆炸"的工具。日常用到的不到 20 个字段：

image / build
ports / networks / volumes
environment / env_file
depends_on + healthcheck
restart / deploy.resources.limits
logging

把这十几个字段摸熟，80% 的多服务编排就够用了。剩下冷门字段（cap_add / secrets / configs / pid）需要时查文档即可。

下一步：理解了 Compose，下一步是 Kubernetes——把"compose 文件"换成"YAML manifest"，把 docker compose up 换成 kubectl apply，把"单机多服务"换成"集群多副本"。K8s 的 Pod 抽象比 Container 更进一步——把"应用 + 卷 + 网络"打包成不可变单元，跨节点调度。