撰写文件版本2参考

预计阅读时间：54分钟

参考和准则

这些主题描述了Compose文件格式的版本2。

撰写和Docker兼容性矩阵

有多种版本的Compose文件格式– 1，2，2.x和3.x。下表是快速浏览。有关每个版本包括什么以及如何升级的完整详细信息，请参阅关于版本和升级。

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

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

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

服务配置参考

Compose文件是一个YAML文件，用于定义 服务， 网络和 卷。撰写文件的默认路径为./docker-compose.yml。

提示：您可以为此文件使用a.yml或.yaml扩展名。他们俩都工作。

服务定义包含应用于该服务启动的每个容器的配置，就像将命令行参数传递给一样 docker run。同样，网络和卷定义类似于 docker network create和docker volume create。

如docker run，在Dockerfile指定的选项，如CMD， EXPOSE，VOLUME，ENV，在默认情况下尊重-你不需要再次指定它们docker-compose.yml。

您可以使用类似Bash的${VARIABLE}语法在配置值中使用环境变量 -有关完整详细信息，请参见变量替换。

本节包含版本2中的服务定义支持的所有配置选项的列表。

blkio_config

一组配置选项，用于为此服务设置块IO限制。

version: "2.4"
services:
  foo:
    image: busybox
    blkio_config:
      weight: 300
      weight_device:
        - path: /dev/sda
          weight: 400
      device_read_bps:
        - path: /dev/sdb
          rate: '12mb'
      device_read_iops:
        - path: /dev/sdb
          rate: 120
      device_write_bps:
        - path: /dev/sdb
          rate: '1024k'
      device_write_iops:
        - path: /dev/sdb
          rate: 30

device_read_bps，device_write_bps

为给定设备上的读/写操作设置限制，以每秒字节数为单位。列表中的每个项目都必须具有两个键：

• path，定义到受影响设备的符号路径
• rate，可以是表示字节数的整数值，也可以是表示字节值的字符串。

device_read_iops，device_write_iops

为给定设备上的读/写操作设置每秒操作的限制。列表中的每个项目都必须具有两个键：

• path，定义到受影响设备的符号路径
• rate，是表示每秒允许的操作数的整数值。

重量

修改分配给该服务的带宽相对于其他服务的比例。取10到1000之间的整数值，默认值为500。

weight_device

根据设备微调带宽分配。列表中的每个项目都必须具有两个键：

• path，定义到受影响设备的符号路径
• weight，介于10到1000之间的整数

建造

在构建时应用的配置选项。

build 可以指定为包含构建上下文路径的字符串：

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

或者，作为具有上下文和（可选）Dockerfile和args下指定的路径的对象：

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

如果您指定image和build，那么Compose将使用中指定的webapp和可选名称命名构建的图像：tagimage

build: ./dir
image: webapp:tag

这将产生一个名为webapp并标记为的图像，该图像tag是从构建的./dir。

语境

以2.0版文件格式添加。

包含Dockerfile的目录的路径，或git存储库的URL。

当提供的值是相对路径时，它将被解释为相对于Compose文件的位置。该目录还是发送到Docker守护程序的构建上下文。

Compose用生成的名称构建并标记它，然后使用该图像。

build:
  context: ./dir

码头工人文件

备用Dockerfile。

Compose使用一个替代文件进行构建。还必须指定一个构建路径。

build:
  context: .
  dockerfile: Dockerfile-alternate

args

以2.0版文件格式添加。

添加构建参数，它们是只能在构建过程中访问的环境变量。

首先，在Dockerfile中指定参数：

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

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

然后在build键下指定参数。您可以传递映射或列表：

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

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

build-args的范围

在Dockerfile中，如果您ARG在FROM指令之前指定， ARG则在下方的构建指令中不可用FROM。如果您需要一个参数在两个地方都可用，请在FROM说明中也指定它。 有关用法的详细信息，请参阅文档中的“了解ARGS和FROM之间的交互方式”部分。

您可以在指定构建参数时忽略该值，在这种情况下，构建时的值就是运行Compose的环境中的值。

args:
  - buildno
  - gitcommithash

使用布尔值时的提示

YAML布尔值（"true"，"false"，"yes"，"no"，"on"， "off"）必须用引号括起来，这样分析器会将它们解释为字符串。

cache_from

以2.2版文件格式添加

引擎用于缓存解析的图像列表。

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

extra_hosts

在构建时添加主机名映射。使用与docker client--add-host参数相同的值。

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

在/etc/hosts此构建的内部容器中创建了一个具有ip地址和主机名的条目，例如：

162.242.195.82  somehost
50.31.209.229   otherhost

隔离

以2.1版文件格式添加。

指定构建的容器隔离技术。在Linux上，唯一支持的值是default。在Windows中，可接受的值是default，process和 hyperv。 有关详细信息，请参考 Docker Engine文档。

如果未指定，则Compose将使用isolation在服务的定义中找到的值来确定用于构建的值。

标签

以2.1版文件格式添加

使用Docker标签将元数据添加到生成的图像中。您可以使用数组或字典。

建议您使用反向DNS表示法，以防止标签与其他软件使用的标签冲突。

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"

网络

以2.2版文件格式添加

设置网络容器的连接以RUN在构建过程中进行说明。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

用于none在构建期间禁用联网：

build:
  context: .
  network: none

shm_size

以2.3版文件格式添加

设置/dev/shm此构建容器的分区大小。指定为表示字节数的整数值，或指定为表示字节值的字符串。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

目标

以2.3版文件格式添加

建立内定义的指定阶段Dockerfile。有关详细信息，请参见 多阶段构建文档。

build:
  context: .
  target: prod

cap_add，cap_drop

添加或删除容器功能。请参阅man 7 capabilities以获取完整列表。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent

为容器指定一个可选的父cgroup。

cgroup_parent: m-executor-abcd

命令

覆盖默认命令。

command: bundle exec thin -p 3000

该命令也可以是列表，类似于 dockerfile：

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

container_name

指定自定义容器名称，而不是生成的默认名称。

container_name: my-web-container

因为Docker容器名称必须是唯一的，所以如果您指定了自定义名称，则不能将服务扩展到超过1个容器。尝试这样做会导致错误。

cpu_rt_runtime，cpu_rt_period

以2.2版文件格式添加

使用Docker守护程序实时调度程序配置CPU分配参数。

cpu_rt_runtime: '400ms'
cpu_rt_period: '1400us'

整数值将以微秒为单位：

cpu_rt_runtime: 95000
cpu_rt_period: 11000

device_cgroup_rules

以2.3版文件格式添加。

将规则添加到cgroup允许的设备列表中。

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

设备

设备映射列表。使用与--devicedocker client create选项相同的格式。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

取决于

以2.0版文件格式添加。

表达服务之间的依赖性。服务依赖项导致以下行为：

• docker-compose up以依赖性顺序启动服务。在以下示例中，db和redis在之前启动web。
• docker-compose up SERVICE自动包含SERVICE的依赖项。在下面的示例中，docker-compose up web还将创建并启动db和redis。
• docker-compose stop按依赖关系顺序停止服务。在以下示例中，web在db和之前停止redis。

简单的例子：

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

笔记

depends_on在启动之前不会等待db并且redis要“准备就绪” web-仅在启动之前。如果您需要等待服务准备就绪，请参阅控制启动顺序以 获取有关此问题的更多信息以及解决该问题的策略。

以2.1版文件格式添加。

运行状况检查表示您希望依赖项在启动之前等待另一个容器“运行状况良好”（如运行状况检查中的成功状态所示）。

例子：

version: "2.4"
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres
    healthcheck:
      test: "exit 0"

在上面的示例中，Compose在redis启动之前等待服务启动（旧行为）并且db服务运行正常web。

请参阅运行状况检查部分以获取补充信息。

域名系统

自定义DNS服务器。可以是单个值或列表。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

要添加到容器resolv.conf文件中的自定义DNS选项的列表。

dns_opt:
  - use-vc
  - no-tld-query

dns_search

自定义DNS搜索域。可以是单个值或列表。

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

入口点

覆盖默认入口点。

entrypoint: /code/entrypoint.sh

入口点也可以是列表，类似于 dockerfile：

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

笔记

设置entrypoint两者都会覆盖使用ENTRYPOINTDockerfile指令在服务映像上设置的任何默认入口点，并清除映像上的任何默认命令-这意味着如果CMDDockerfile中有指令，则将其忽略。

env_file

从文件添加环境变量。可以是单个值或列表。

如果您使用指定了Compose文件docker-compose -f FILE，则inenv_file的路径是相对于该文件所在目录的路径 。

在环境部分中 声明的环境变量将覆盖这些值–即使这些值为空或未定义也是如此。

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env

Compose期望环境文件中的每一行都采用VAR=VAL格式。以开头的行#被视为注释，并被忽略。空行也将被忽略。

# Set Rails/Rack environment
RACK_ENV=development

笔记

如果您的服务指定了构建选项，则在构建过程中不会自动显示环境文件中定义的变量。使用的args子选项build来定义构建时环境变量。

的值按VAL原样使用，根本没有修改。例如，如果该值用引号引起来（通常是shell变量），则引号包含在传递给Compose的值中。

请记住，列表中文件的顺序对于确定分配给多次显示的变量的值很重要。列表中的文件从上到下进行处理。对于在file中指定并在file中a.env分配了不同值的相同变量 b.env，如果b.env在下面（之后）列出，则来自标准位的值b.env。例如，在中给出以下声明docker-compose.yml：

services:
  some-service:
    env_file:
      - a.env
      - b.env

和以下文件：

# a.env
VAR=1

和

# b.env
VAR=hello

$VAR是hello。

环境

添加环境变量。您可以使用数组或字典。任何布尔值（true，false，yes，no）都需要用引号引起来，以确保YML解析器不会将其转换为True或False。

仅具有键的环境变量在运行Compose的计算机上解析为它们的值，这对于秘密或特定于主机的值很有用。

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

environment:
  - RACK_ENV=development
  - SHOW=true
  - SESSION_SECRET

笔记

如果您的服务指定了构建选项，environment则在构建过程中不会自动显示中定义的变量 。使用的 args子选项build来定义构建时环境变量。

暴露

公开端口而不将其发布到主机上-只有链接的服务才能访问它们。只能指定内部端口。

expose:
  - "3000"
  - "8000"

延伸

在当前文件或其他可选的覆盖配置中扩展另一个服务。

您可以extends在任何服务上与其他配置键一起使用。该extends值必须是使用必需键service 和可选file键定义的字典。

extends:
  file: common.yml
  service: webapp

的service是该服务的名称被扩展，例如 web或database。的file是一个撰写配置文件定义该服务的位置。

如果省略，则fileCompose在当前文件中查找服务配置。该file值可以是绝对路径或相对路径。如果指定相对路径，则Compose会将其视为相对于当前文件位置的相对路径。

您可以扩展本身扩展另一个服务的服务。您可以无限期地扩展。Compose不支持循环引用，docker-compose 如果遇到循环引用，则返回错误。

有关更多信息extends，请参见 扩展文档。

外部链接

链接到在此范围之外docker-compose.yml甚至在Compose之外开始的容器，特别是对于提供共享或公共服务的容器。 同时指定容器名称和链接别名（）时，请external_links遵循与legacy选项相似的语义。linksCONTAINER:ALIAS

external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql

笔记

如果您使用的是版本2或更高版本的文件格式，则外部创建的容器必须连接到与链接到它们的服务相同的网络中的至少一个。链接 是旧选项。我们建议改为使用网络。

extra_hosts

添加主机名映射。使用与docker client--add-host参数相同的值。

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

在/etc/hosts此服务的内部容器中创建一个具有ip地址和主机名的条目，例如：

162.242.195.82  somehost
50.31.209.229   otherhost

group_add

指定容器内的用户应成为其成员的其他组（按名称或编号）。要添加的容器和主机系统中都必须存在组。当多个容器（以不同用户身份运行）需要全部在主机系统上读取或写入同一文件时，此方法很有用。该文件可以归所有容器共享的组所有，并在中指定group_add。有关更多详细信息，请参阅 Docker文档。

一个完整的例子：

version: "2.4"
services:
  myservice:
    image: alpine
    group_add:
      - mail

id在创建的容器中运行将显示该用户属于该mail组，如果group_add不使用，则不会属于这种情况。

健康检查

以2.1版文件格式添加。

配置运行的检查以确定该服务的容器是否“健康”。请参阅文档以获取 HEALTHCHECK Dockerfile指令， 以获取有关运行状况检查如何工作的详细信息。

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

interval，timeout并start_period指定为 duration。

以2.3版文件格式添加。

该start_period选项以文件格式2.3添加。

test必须是字符串或列表。如果它是一个列表，第一项必须是NONE，CMD或CMD-SHELL。如果是字符串，则等效于指定CMD-SHELL后跟该字符串。

# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]

如上所述，但包裹在中/bin/sh。以下两种形式是等效的。

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]

test: curl -f https://localhost || exit 1

要禁用图像设置的任何默认运行状况检查，可以使用disable: true。这等效于指定test: ["NONE"]。

healthcheck:
  disable: true

图像

指定要从中启动容器的图像。可以是存储库/标签或部分图像ID。

image: redis

image: ubuntu:18.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

如果图像不存在，除非您还指定了build，否则Compose会尝试将其拉出，在这种情况下，它将使用指定的选项来构建图像并使用指定的标签对其进行标记。

在里面

以2.2版文件格式添加。

在容器内运行一个初始化程序，以转发信号并获取进程。设置此选项可以true为服务启用此功能。

version: "2.4"
services:
  web:
    image: alpine:latest
    init: true

使用的默认初始化二进制文件是Tini，并安装在/usr/libexec/docker-init守护程序主机上。您可以通过init-path配置选项将守护程序配置为使用自定义init二进制文件 。

隔离

以2.1版文件格式添加。

指定容器的隔离技术。在Linux上，唯一支持的值是default。在Windows中，可接受的值是default，process和 hyperv。 有关详细信息，请参考 Docker Engine文档。

标签

使用Docker标签将元数据添加到容器中。您可以使用数组或字典。

建议您使用反向DNS表示法，以防止标签与其他软件使用的标签冲突。

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

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

链接

链接到另一个服务中的容器。既可以指定服务名称，也可以指定链接别名（"SERVICE:ALIAS"），也可以仅指定服务名称。

链接是旧选项。我们建议改为使用 网络。

web:
  links:
    - "db"
    - "db:database"
    - "redis"

可以使用与别名相同的主机名访问链接服务的容器，如果未指定别名，则可以使用服务名。

不需要链接即可使服务进行通信-默认情况下，任何服务都可以使用该服务的名称访问任何其他服务。（另请参见Compose中的Networking中的 Links主题。）

链接还以与depends_on相同的方式表示服务之间的依赖关系 ，因此它们确定了服务启动的顺序。

笔记

如果同时定义链接和网络，则它们之间具有链接的服务必须共享至少一个公共网络以进行通信。我们建议改为使用网络。

测井

服务的日志记录配置。

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

该driver 名称指定了服务容器的日志记录驱动程序，以及--log-driverdocker run选项（在此处记录）。

默认值为json-file。

driver: "json-file"

driver: "syslog"

driver: "none"

笔记

只有json-file和journald驱动程序才能从docker-compose up和直接提供日志docker-compose logs。使用任何其他驱动程序都不会打印任何日志。

使用options键为日志记录驱动程序指定日志记录选项，如的--log-opt选项docker run。

日志记录选项是键值对。syslog选项示例：

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

网络模式

更改为版本2文件格式。

网络模式。使用与docker client--network参数相同的值，以及特殊形式service:[service name]。

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]"

network_mode: "container:[container name/id]"

网路

更改为版本2文件格式。

要加入的网络，引用顶级networks密钥下的条目 。

services:
  some-service:
    networks:
     - some-network
     - other-network

别名

网络上此服务的别名（备用主机名）。同一网络上的其他容器可以使用服务名称或此别名来连接到服务的容器之一。

由于aliases是网络范围的，因此同一服务在不同的网络上可以具有不同的别名。

笔记

一个网络范围内的别名可以被多个容器甚至多个服务共享。如果是这样，则不能保证名称解析到哪个容器。

通用格式如下所示。

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

在下面的例子中，提供了三种服务（web，worker，和db），其中两个网络（沿new和legacy）。该db服务是在到达的主机名db或database上new网络，并db或mysql将上legacy网络。

version: "2.4"

services:
  web:
    image: "nginx:alpine"
    networks:
      - new

  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy

  db:
    image: mysql
    networks:
      new:
        <