撰写文件版本和升级

警告

此页面包含有关 Compose 旧版本（也统称为 Compose V1）的信息。从 2023 年 6 月底开始，将不再支持 Compose V1。

Compose 的最新推荐版本是Compose 规范。确保 使用CLI 插件或激活Docker Desktop 中的“使用 Docker Compose V2”设置切换到Compose V2 。docker compose

有关详细信息，请参阅 Compose 的历史。

Compose 文件是一个 YAML文件，定义 Docker 应用程序的服务、网络和卷。

现在，这些参考文献中描述了 Compose 文件格式，具体针对每个版本。

参考文件这个版本有什么变化
版本3版本 3 更新
版本2版本 2 更新
版本 1（已弃用）版本 1 更新

以下主题解释了版本之间的差异、Docker Engine 兼容性以及 如何升级。

兼容性矩阵

此表显示哪些 Compose 文件版本支持特定的 Docker 版本。

撰写文件格式Docker 引擎发布
撰写规范19.03.0+
3.819.03.0+
3.718.06.0+
3.618.02.0+
3.517.12.0+
3.417.09.0+
3.317.06.0+
3.217.04.0+
3.11.13.1+
3.01.13.0+
2.417.12.0+
2.317.06.0+
2.21.13.0+
2.11.12.0+
2.01.10.0+

除了表中显示的 Compose 文件格式版本之外，Compose 本身也在发布计划中，如 Compose 版本中所示，但文件格式版本不一定随每个版本而增加。例如，Compose 文件格式 3.0 首次在 Compose 版本 1.10.0中引入，并在后续版本中逐渐版本化。

最新的 Compose 文件格式由Compose 规范定义 ，并由 Docker Compose 1.27.0+实现。

正在寻找有关 Docker 和 Compose 兼容性的更多详细信息？

我们建议尽可能保持最新版本。但是，如果您使用的是较旧版本的 Docker 并且想要确定哪个 Compose 版本兼容，请参阅 Compose 发行说明。每组发行说明都提供了有关支持哪些版本的 Docker Engine 的详细信息，以及兼容的 Compose 文件格式版本。 （另请参阅问题 #3404中的讨论 。）

有关版本和如何升级的详细信息，请参阅 版本控制和 升级。

版本控制

Compose 文件格式共有三个旧版本：

Compose 文件格式的最新和推荐版本由Compose 规范定义 。该格式合并了 2.x 和 3.x 版本，由Compose 1.27.0+实现。

兼容性矩阵显示 映射到 Docker 引擎版本的 Compose 文件版本。

要将项目移至更高版本，请参阅 升级 部分。

笔记

如果您使用 多个 Compose 文件或 扩展服务，则每个文件必须具有相同版本 - 例如，您不能在单个项目中混合版本 1 和 2。

根据您使用的版本，有几点会有所不同：

  • 结构和允许的配置键
  • 您必须运行的最低 Docker 引擎版本
  • Compose 的网络行为

这些差异解释如下。

版本2

使用版本 2 语法撰写文件必须在文档根部指示版本号。所有 服务都 必须在该services密钥下声明。

Compose 1.6.0+支持版本 2 文件，并且需要版本1.10.0+的 Docker 引擎。

命名 卷可以在该 volumes密钥下声明， 网络也可以在该networks密钥下声明。

默认情况下，每个容器都会加入应用程序范围的默认网络，并且可以通过与服务名称相同的主机名来发现。这意味着 链接基本上是不必要的。有关更多详细信息，请参阅 Compose 中的网络。

笔记

对于 Compose 版本 2，在指定要使用的 Compose 文件版本时，请确保指定主要编号和次要编号。如果未给出次要版本，则 0默认使用而不是最新的次要版本。因此，以后版本中添加的功能将不受支持。例如：

version: "2"

相当于：

version: "2.0"

简单的例子：

version: "2.4"
services:
  web:
    build: .
    ports:
     - "8000:5000"
    volumes:
     - .:/code
  redis:
    image: redis

一个更扩展的示例，定义卷和网络：

version: "2.4"
services:
  web:
    build: .
    ports:
     - "8000:5000"
    volumes:
     - .:/code
    networks:
      - front-tier
      - back-tier
  redis:
    image: redis
    volumes:
      - redis-data:/var/lib/redis
    networks:
      - back-tier
volumes:
  redis-data:
    driver: local
networks:
  front-tier:
    driver: bridge
  back-tier:
    driver: bridge

添加了其他几个选项来支持网络，例如：

  • aliases

  • 该 depends_on选项可以用来代替链接来指示服务和启动顺序之间的依赖关系。

    version: "2.4"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

  • ipv4_address,ipv6_address

版本 2 中还添加了变量替换。

2.1版

版本 2的升级 ，引入了仅适用于 Docker Engine 版本1.12.0+的新参数。Compose 1.9.0+支持版本 2.1 文件。

引入以下附加参数：

2.2版本

版本 2.1的升级 ，引入了仅适用于 Docker Engine 版本1.13.0+的新参数。Compose 1.13.0+支持版本 2.2 文件。此版本还允许您在服务配置中指定默认比例编号。

引入以下附加参数：

2.3版本

版本 2.2的升级 ，引入了仅适用于 Docker Engine 版本17.06.0+的新参数。Compose 1.16.0+支持版本 2.3 文件。

引入以下附加参数：

2.4版本

版本 2.3的升级 ，引入了仅适用于 Docker Engine 版本17.12.0+的新参数。Compose 1.21.0+支持版本 2.4 文件。

引入以下附加参数：

  • platform用于服务定义
  • 支持服务、网络和卷定义根部的扩展字段

版本3

版本 3 旨在实现 Compose 和 Docker Engine 的swarm 模式之间的交叉兼容 ，删除了多个选项并添加了多个选项。

  • 删除：volume_driver, volumes_from, cpu_shares, cpu_quota, cpuset, mem_limit, memswap_limit, extends, group_add。请参阅 升级指南了解如何迁移这些内容。

  • 补充： 部署

如果仅给出主要版本 ( version: '3')，则默认使用最新的次要版本。

3.1版本

版本 3的升级 ，引入了仅适用于 Docker Engine 版本1.13.1+及更高版本的新参数。

引入以下附加参数：

3.2版本

版本 3的升级 ，引入了仅适用于 Docker Engine 版本17.04.0+及更高版本的新参数。

引入以下附加参数：

3.3版本

版本 3的升级 ，引入了仅适用于 Docker Engine 版本17.06.0+及更高版本的新参数。

引入以下附加参数：

3.4版本

版本 3的升级 ，引入了新参数。它仅适用于 Docker Engine 版本17.09.0及更高版本。

引入以下附加参数：

3.5版本

版本 3的升级 ，引入了新参数。它仅适用于 Docker Engine 版本17.12.0及更高版本。

引入以下附加参数：

3.6版本

版本 3的升级 ，引入了新参数。它仅适用于 Docker Engine 版本18.02.0及更高版本。

引入以下附加参数：

3.7版本

版本 3的升级 ，引入了新参数。它仅适用于 Docker Engine 版本18.06.0及更高版本。

引入以下附加参数：

  • init在服务定义中
  • rollback_config在部署配置中
  • 支持服务、网络、卷、秘密和配置定义根部的扩展字段

3.8版本

版本 3的升级 ，引入了新参数。它仅适用于 Docker Engine 版本19.03.0及更高版本。

引入以下附加参数：

  • max_replicas_per_node在放置配置中
  • template_driver配置 和 秘密配置的选项 。仅当使用 部署 swarm 服务时才支持此选项 docker stack deploy。
  • driver以及秘密driver_opts配置的选项 。仅当使用 部署 swarm 服务时才支持此选项。docker stack deploy

版本 1（已弃用）

1.6.x 以下的 Compose 版本是

未声明版本的 Compose 文件被视为“版本 1”。在这些文件中，所有 服务都在文档的根目录下声明。

Compose 最高支持 1.6.x** 版本 1，但已弃用。

版本 1 文件无法声明命名 卷、 网络或 构建参数。

当您使用版本 1 时， Compose 不会利用 网络：每个容器都放置在默认bridge网络上，并且可以通过其 IP 地址从每个其他容器访问。您需要使用 links来启用容器之间的发现。

例子：

web:
  build: .
  ports:
   - "8000:5000"
  volumes:
   - .:/code
  links:
   - redis
redis:
  image: redis

升级中

版本 2.x 至 3.x

在版本 2.x 和 3.x 之间，Compose 文件的结构是相同的，但删除了几个选项：

  • volume_driver：不要在服务上设置卷驱动程序，而是使用 顶级volumes选项定义卷 并在其中指定驱动程序。

    version: "3.8"
services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data
volumes:
  data:
    driver: mydriver

  • volumes_from：要在服务之间共享卷，请使用 top-levelvolumes选项定义它，并使用service-levelvolumes选项 从共享它的每个服务引用它 。

  • cpu_shares,,,,, ：这些已被替换为 下的 cpu_quota资源键。配置仅在使用时生效 ，被忽略。cpusetmem_limitmemswap_limitdeploydeploydocker stack deploydocker-compose

  • extends：此选项已针对version: "3.x"Compose 文件删除。有关详细信息extends，请参阅 扩展服务。

  • group_add：此选项已针对version: "3.x"Compose 文件删除。

  • pids_limitversion: "3.x"： Compose 文件中尚未引入此选项。

  • link_local_ipsin ： Compose 文件networks中尚未引入此选项 。version: "3.x"

兼容模式

docker-compose1.20.0 引入了一个新--compatibility标志，旨在帮助开发人员更轻松地过渡到版本 3。启用后， docker-compose读取deploy每个服务定义的部分并尝试将其转换为等效的版本 2 参数。目前，已翻译以下部署密钥：

所有其他键都将被忽略，并在存在时发出警告。您可以通过使用--compatibility 带有该命令的标志来查看将用于部署的配置config。

不要在生产中使用它

我们建议不要--compatibility在生产中使用模式。生成的配置只是使用非 Swarm 模式属性的近似值，它可能会产生意外的结果。

版本 1 至 2.x

在大多数情况下，从版本 1 迁移到版本 2 的过程非常简单：

  1. 将整个文件缩进一级并services:在顶部放置一个键。
  2. version: '2'在文件顶部添加一行。

如果您使用特定的配置功能，情况会更加复杂：

  • dockerfile：现在它位于build密钥下：

    build:
  context: .
  dockerfile: Dockerfile-alternate

  • log_driver, log_opt: 这些现在位于logging密钥下：

    logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

  • links使用环境变量：由链接创建的环境变量，例如CONTAINERNAME_PORT, ` 已被弃用一段时间。在新的Docker网络系统中，它们已被删除。您应该直接连接到适当的主机名，或者使用链接主机名自行设置相关的环境变量：

    web:
  links:
    - db
  environment:
    - DB_PORT=tcp://db:5432

  • external_links：Compose 在运行版本 2 项目时使用 Docker 网络，因此链接的行为略有不同。特别是，即使明确链接在一起，两个容器也必须连接到至少一个公共网络才能进行通信。

    将外部容器连接到应用程序的 默认网络，或者将外部容器和服务的容器都连接到 外部网络。

  • net：现在已被 network_mode取代：

    net: host    ->  network_mode: host
net: bridge  ->  network_mode: bridge
net: none    ->  network_mode: none

    如果您正在使用net: "container:[service name]"，则现在必须改用 network_mode: "service:[service name]"。

    net: "container:web"  ->  network_mode: "service:web"

    如果您使用net: "container:[container name/id]"，则该值不需要更改。

    net: "container:cont-name"  ->  network_mode: "container:cont-name"
net: "container:abc12345"   ->  network_mode: "container:abc12345"

  • volumesvolumes带有命名卷：现在必须在Compose 文件的顶级部分中显式声明这些卷。如果服务安装了名为 的命名卷data，您必须data在顶级volumes部分声明一个卷。整个文件可能如下所示：

    version: "2.4"
services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data
volumes:
  data: {}

    默认情况下，Compose 创建一个卷，其名称以您的项目名称为前缀。如果您希望它只是被调用data，请将其声明为外部：

    volumes:
  data:
    external: true