撰写文件版本和升级

预计阅读时间：15分钟

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

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

参考文件	此版本中发生了什么变化
撰写规范（最新，推荐）	版本控制
版本3	版本3更新
版本2	版本2更新
版本1（不建议使用）	版本1更新

以下主题说明了版本之间的差异，Docker Engine兼容性以及升级方法。

相容性矩阵

有多种版本的Compose文件格式– 1，2，2.x和3.x

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

撰写档案格式	Docker Engine版本
撰写规格	19.03.0+
3.8	19.03.0+
3.7	18.06.0+
3.6	18.02.0+
3.5	17.12.0+
3.4	17.09.0+
3.3	17.06.0+
3.2	17.04.0+
3.1	1.13.1+
3.0	1.13.0+
2.4	17.12.0+
2.3	17.06.0+
2.2	1.13.0+
2.1	1.12.0+
2.0	1.10.0+
1.0	1.9.1。+

除了表中显示的Compose文件格式版本外，Compose本身也处于发布计划中，如Compose releases中所示，但是文件格式版本不一定随每个发行版增加。例如，Compose文件格式3.0最初是在Compose版本1.10.0中引入的，并在随后的版本中逐渐版本化。

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

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

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

有关版本以及如何升级的详细信息，请参见“ 版本控制和升级”。

版本控制

有三种旧版本的Compose文件格式：

版本1。这是通过省略versionYAML根目录下的密钥来指定的。
版本2.x。这是使用YAML根目录中的version: '2'或version: '2.1'等条目指定的。
版本3.x，旨在在Compose和Docker Engine的swarm模式之间交叉兼容。这是使用YAML根目录中的version: '3'或version: '3.1'等条目指定的。

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

v2和v3声明

注意：指定要使用的撰写文件版本时，请确保同时指定主数字和副数字。如果未提供次要版本， 0则默认情况下使用，而不是最新的次要版本。

在兼容性矩阵显示映射到码头工人引擎版本撰写的文件版本。

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

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

根据您使用的版本，有些事情有所不同：

结构和允许的配置密钥
您必须运行的最低Docker Engine版本
撰写有关网络的行为

这些差异将在下面说明。

版本1（不建议使用）

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

Compose最高支持1.6.x版本1 。在以后的Compose版本中将不推荐使用。

版本1文件不能声明命名卷，网络或构建参数。

使用版本1时，Compose无法利用网络的优势：每个容器都位于默认bridge网络上，并且可以通过其IP地址从其他每个容器访问。您需要使用 links来启用容器之间的发现。

例子：

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

版本2

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

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

可以在键下声明命名卷volumes，并在键下声明网络networks。

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

笔记

指定要使用的撰写文件版本时，请确保同时指定主数字和副数字。如果未提供次要版本， 0则默认情况下使用，而不是最新的次要版本。因此，将不支持在更高版本中添加的功能。例如：
version: "2"
等效于：
version: "2.0"

简单的例子：

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

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

version: "2.4"
services:
  web:
    build: .
    ports:
     - "5000: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版文件。

引入了以下附加参数：

link_local_ips
isolation 在构建配置和服务定义中
labels用于卷，网络和构建
name对于卷
userns_mode
healthcheck
sysctls
pids_limit
oom_kill_disable
cpu_period

版本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

设计为在Compose和Docker Engine的swarm模式之间具有交叉兼容性，版本3删除了几个选项，并添加了更多选项。

删除：volume_driver，volumes_from，cpu_shares，cpu_quota， cpuset，mem_limit，memswap_limit，extends，group_add。请参阅升级指南，以了解如何从这些指南中进行迁移。（有关更多信息extends，请参阅扩展服务。）
新增：部署

注意：指定要使用的撰写文件版本时，请确保同时指定主数字和副数字。如果未提供次要版本， 0则默认情况下使用，而不是最新的次要版本。因此，将不支持在更高版本中添加的功能。例如：
version: "3"
等效于：
version: "3.0"

版本3.1

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

引入了以下附加参数：

secrets

版本3.2

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

引入了以下附加参数：

版本3.3

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

引入了以下附加参数：

版本3.4

引入新参数的版本3的升级。它仅在Docker Engine 17.09.0及更高版本中可用。

引入了以下附加参数：

target并network在构建配置中
start_period 为了 healthchecks
order用于更新配置
name对于卷

版本3.5

引入新参数的版本3的升级。它仅在Docker Engine 17.12.0及更高版本中可用。

引入了以下附加参数：

isolation 在服务定义中
name 用于网络，机密和配置
shm_size在构建配置中

版本3.6

引入新参数的版本3的升级。它仅在Docker Engine 18.02.0及更高版本中可用。

引入了以下附加参数：

tmpfs尺寸为tmpfs型坐骑

版本3.7

引入新参数的版本3的升级。它仅在Docker Engine 18.06.0及更高版本中可用。

引入了以下附加参数：

init 在服务定义中
rollback_config 在部署配置中
支持扩展域位于服务，网络，卷，机密和配置定义的根目录

版本3.8

引入新参数的版本3的升级。它仅在Docker Engine 19.03.0及更高版本中可用。

引入了以下附加参数：

max_replicas_per_node 在展示位置配置中
template_driverconfig 和secret配置的选项。仅当使用部署群集服务时才支持此选项 docker stack deploy。
driver以及driver_opts用于秘密配置的选项。仅当使用部署群集服务时才支持此选项docker stack deploy。

升级中

版本2.x至3.x

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

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

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

volumes_from：要在服务之间共享卷，请使用顶级volumes选项对其进行定义，并使用service-levelvolumes选项从共享该卷的每个服务中对其进行引用。
cpu_shares，cpu_quota，cpuset，mem_limit，memswap_limit：这些已被替换的资源下键 deploy。deploy配置仅在使用时生效 docker stack deploy，而被忽略docker-compose。
extends：此选项已针对version: "3.x" 撰写文件删除。（有关更多信息，请参阅扩展服务。）
group_add：此选项已针对version: "3.x"撰写文件删除。
pids_limit：“version: "3.x"撰写”文件中未引入此选项。
link_local_ipsin networks：“version: "3.x"撰写”文件中未引入此选项。

版本1至2.x

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

将整个文件缩进一个级别，然后services:在顶部放置一个密钥。
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：运行版本2项目时，Compose使用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"

volumes带有命名卷的卷：现在必须在volumesCompose文件的顶级部分中明确声明这些卷。如果服务安装了名为的命名卷data，则必须data在顶级volumes部分中声明一个卷。整个文件可能如下所示：
```
version: "2.4"
services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data
volumes:
  data: {}
```
默认情况下，Compose创建一个名称以您的项目名称为前缀的卷。如果只想调用data它，则将其声明为external：
```
volumes:
  data:
    external: true
```

兼容模式

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

资源限制和内存预留
复制品
restart_policy condition和max_attempts

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

不要在生产中使用它！

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

撰写文件格式参考

无花果，组成，组成，版本，升级，码头工人