Docker Compose配置文件是Docker Compose的核心，用于定义服务、网络和数据卷。格式为YAML，默认路径为./docker-compose.yml，可以使用.yml或.yaml扩展名，目前Compose配置文件格式的最新版本为V3。Compose配置文件中涉及的配置项也比较多，但大部分配置项的含义跟docker run命令相关选项是类似的。

本文主要参考官方文档对目前最新的V3版Compose配置文件进行一个总结。都是一些概念性的内容，不涉及具体操作。

一、Compose配置文件版本

这里主要对Compose配置文件的版本的相关要点进行一个简单的总结。至于每个版本具体的变化和升级信息可以参考官方的Compose配置文件版本与升级指南。

1.Compose配置文件格式的版本概述

当前有三种版本的Compose配置文件格式：

• Version 1：
  • 旧版格式，通过省略YAML的根配置项version来指定。
  • 未声明版本的Compose配置文件都被视为V1版，所有的服务都作为根选项在Compose配置文件中声明。
  • 支持V1的Compose最高到1.6.x，再高版本的Compose不推荐使用V1版Compose配置文件。
  • 不支持数据卷、网络和构建参数配置。
  • V1的Compose不会利用网络优势，每个容器都位于默认的bridge网络上，并且可以从其他容器的IP地址访问，需要使用links来启用容器之间的发现。
• Version 2.x：
  • 通过YAML的根配置项version来指定，具体配置如version: '2'或version: '2.1'等。
  • 必须在Compose配置文件根选项指定版本号，并且主版本数字为2，且所有服务必须在services配置项下声明。
  • 1.6.0+版本的Compose都支持V2，Docker Engine的版本需要1.10.0+版本。
  • 支持数据卷和网络的配置。
  • 默认情况下，每个容器都加入了应用范围的默认网络，并且可以在与服务名称相同的主机名下发现。很大程度上links不是必要的。
  • V2中加入了环境变量替换。
• Version 3.x：
  • 最新版本，也是推荐使用版本，推出该版的目的是为了在Compose和Docker Engine的swarm模式之间形成交叉兼容。
  • 通过YAML的根配置项version来指定，具体配置如version: '3'或version: '3.1'等。
  • V3删除了多个配置项，但也新增了更多配置项。

关于Compose配置文件版本的常见注意事项：

• 在声明V2和V3版本时需注意：
  • 在指定Compose配置文件要使用的版本时，需同时指定主版本数字和次版本数字。如果未给定次版本数字，则默认使用0而不是最新版本，因此将不支持再更高版本中才加入的新功能。比如version: '3'，使用的是3.0版本而不是目前最新的3.8版本。
• 在使用多Compose配置文件时需注意：
  • 使用多个Compose配置文件扩展服务时，每个文件必须为相同的版本。

2.Compose配置文件格式版本与Docker的兼容性关系

Compose配置文件格式具有多种版本。其中Compose配置文件格式版本与Docker的兼容性关系如下表所示：

如果使用的较旧版本的Docker，可以参考官方的Compose版本发布列表。其中的每组发行说明都详细说明了支持的Docker Engine版本和兼容的Compose配置文件格式版本。

3.兼容模式

在1.20.0版本，Compose在docker-compose命令中引入了一个新的选项--compatibility，目的在于帮助开发人员更轻松地过渡到V3版。启用该选项后，docker-compose命令会读取每个服务定义的deploy部分，并尝试将其转换为等效的V2配置项。目前，以下deploy下的配置项已被转换：

• resources下的limits和reservations下的memory
• replicas
• restart_policy下的 condition 和max_attempts

所有的其他配置项都将被忽略，如果这些被忽略的配置项存在则会发出一个警告。可以使用带--compatibility的Config命令查看将用于deploy的配置。

注意请勿在生成环境使用兼容模式！
建议不要在生产环境中使用--compatibility选项。由于使用非Swarm模式属性生成的配置仅是近似值，因此可能会产生意外的结果。

二、Compose配置文件结构

Docker Compose配置文件是一个用于定义服务、网络和数据卷的YAML文件。其中服务定义了该服务启动的每个容器的配置，就像将命令行参数传递给docker run一样，网络和数据卷的定义类似于docker network create和docker volume create。跟docker run一样，如果在Dockerfile中通过诸如CMD、EXPOSE、VOLUME和ENV这些指令指定了相关选项，那么在默认情况下，不需要在docker-compose.yml中再次指定它们。下面是从官网引过来的一个Compose配置文件的示例，可以先大致了解一下它的结构：

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

  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints:
          - "node.role==manager"

  vote:
    image: dockersamples/examplevotingapp_vote:before
    ports:
      - "5000:80"
    networks:
      - frontend
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
      restart_policy:
        condition: on-failure

  result:
    image: dockersamples/examplevotingapp_result:before
    ports:
      - "5001:80"
    networks:
      - backend
    depends_on:
      - db
    deploy:
      replicas: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 1
      labels: [APP=VOTING]
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
        window: 120s
      placement:
        constraints:
          - "node.role==manager"

  visualizer:
    image: dockersamples/visualizer:stable
    ports:
      - "8080:8080"
    stop_grace_period: 1m30s
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
    deploy:
      placement:
        constraints:
          - "node.role==manager"

networks:
  frontend:
  backend:

volumes:
  db-data:

services:
  redis:
    image: redis:alpine

version: "3.8"
services:
  webapp:
    build: ./dir

version: "3.8"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

build: ./dir
image: webapp:tag

build:
  context: ./dir

build:
  context: .
  dockerfile: Dockerfile-alternate

ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

args:
  - buildno
  - gitcommithash

build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14

build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""

build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

build:
  context: .
  network: custom_network_1

build:
  context: .
  network: none

build:
  context: .
  shm_size: 10000000

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  target: prod

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent: m-executor-abcd

command: bundle exec thin -p 3000

command: ["bundle", "exec", "thin", "-p", "3000"]

version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs: