撰写文件版本 2 参考

重要的

Docker 的文档引用并描述了 Compose V2 功能。

自 2023 年 7 月起，Compose V1 停止接收更新，并且不再出现在新的 Docker Desktop 版本中。 Compose V2 已取代它，并且现已集成到所有当前的 Docker Desktop 版本中。有关更多信息，请参阅 迁移到 Compose V2。

参考和指南

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

Compose 和 Docker 兼容性矩阵

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

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

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

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

服务配置参考

Compose 文件是 定义 服务、 网络和 卷的YAML文件。 Compose 文件的默认路径是../docker-compose.yml

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

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

与 一样docker run，默认情况下会考虑 Dockerfile 中指定的选项，例如CMD、 EXPOSE、VOLUME、 、ENV，您无需在 中再次指定它们docker-compose.yml。

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

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

块配置

一组配置选项，用于为此服务设置块 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。

重量设备

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

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

建造

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

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

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

或者，作为一个对象，其路径在 context下指定，并且可选 Dockerfile和 args：

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

如果您指定image以及，则 Compose 会使用中指定的和 选项build来命名构建的映像：webapptagimage

build: ./dir
image: webapp:tag

这会产生一个名为webapp并标记为tag、由 构建的图像./dir。

语境

在2.0 版本中添加 文件格式。

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

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

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

build:
  context: ./dir

docker文件

备用 Dockerfile。

Compose 使用备用文件进行构建。还必须指定构建路径。

build:
  context: .
  dockerfile: Dockerfile-alternate

参数

在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") 必须用引号引起来，以便解析器将它们解释为字符串。

缓存来源

2.2版本添加 文件格式

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

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

额外主机

在构建时添加主机名映射。使用与 docker 客户端参数相同的值--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 引擎文档 。

如果未指定，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_大小

2.3版本添加 文件格式

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

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

目标

2.3版本添加 文件格式

构建指定阶段，如Dockerfile.有关详细信息，请参阅 多阶段构建文档。

build:
  context: .
  target: prod

上限添加、上限删除

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

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_父级

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

cgroup_parent: m-executor-abcd

命令

覆盖默认命令。

command: bundle exec thin -p 3000

该命令也可以是一个列表，其方式类似于 dockerfile：

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

容器名称

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

container_name: my-web-container

由于 Docker 容器名称必须是唯一的，因此如果指定了自定义名称，则无法将服务扩展至超过 1 个容器。尝试这样做会导致错误。

cpu_rt_运行时间、cpu_rt_周期

2.2版本添加 文件格式

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

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

整数值将使用微秒作为单位：

cpu_rt_runtime: 95000
cpu_rt_period: 11000

设备_cgroup_规则

在2.3 版本中添加了 文件格式。

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

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

设备

设备映射列表。使用与--devicedocker 客户端创建选项相同的格式。

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 选项列表resolv.conf。

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

域名解析搜索

自定义 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两者都会覆盖使用 Dockerfile 指令在服务映像上设置的任何默认入口点ENTRYPOINT，并清除映像上的任何默认命令 - 这意味着如果CMDDockerfile 中有指令，它将被忽略。

环境文件

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

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

在环境部分 中声明的环境变量 会覆盖这些值——即使这些值是空的或未定义的，这也成立。

env_file: .env

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

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

# Set Rails/Rack environment
RACK_ENV=development

笔记

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

的值VAL按原样使用，根本不进行修改。例如，如果该值被引号括起来（shell 变量经常出现这种情况），则引号将包含在传递给 Compose 的值中。

请记住，列表中文件的顺序对于确定分配给多次出现的变量的值非常重要。列表中的文件是从上到下处理的。对于在 file 中指定的相同变量 a.env并在​​ file 中分配不同的值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定义的字典。servicefile

extends:
  file: common.yml
  service: webapp

是service正在扩展的服务的名称，例如 web或database。这file是定义该服务的 Compose 配置文件的位置。

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

您可以扩展一项服务，而该服务本身又扩展了另一项服务。您可以无限期延长。 Compose 不支持循环引用，docker-compose 如果遇到循环引用，则会返回错误。

有关 的更多信息extends，请参阅 扩展文档

外部链接

链接到在此docker-compose.yml之外甚至在 Compose 之外启动的容器，特别是对于提供共享或通用服务的容器。 在指定容器名称和链接别名 ( ) 时，external_links遵循与旧选项类似的语义。linksCONTAINER:ALIAS

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

笔记

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

额外主机

添加主机名映射。使用与 docker 客户端参数相同的值--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.有关更多详细信息，请参阅 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指定为 持续时间。

在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:22.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

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

在里面

在2.2 版本中添加了 文件格式。

在容器内运行 init 来转发信号并获取进程。将此选项设置为true可为服务启用此功能。

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

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

隔离

添加到 版本 2.1文件格式。

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

标签

使用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 中的网络中的链接主题。）

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

笔记

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

记录

服务的日志记录配置。

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

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

默认值为 json 文件。

driver: "json-file"

driver: "syslog"

driver: "none"

笔记

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

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

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

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

网络模式

版本 2文件格式已更改 。

网络模式。使用与 docker 客户端参数相同的值--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文件格式已更改 。

要加入的网络，引用顶级networkskey下的条目 。

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:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

ipv4_地址、ipv6_地址

加入网络时为该服务的容器指定静态 IP 地址。

顶级网络部分中的相应网络配置 必须有一个 ipam包含覆盖每个静态地址的子网和网关配置的块。

如果需要 IPv6 寻址，则 enable_ipv6必须设置该选项。

一个例子：

version: "2.4"

services:
  app:
    image: busybox
    command: ifconfig
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24
          gateway: 172.16.238.1
        - subnet: 2001:3984:3989::/64
          gateway: 2001:3984:3989::1

链接本地ip

添加到 版本 2.1文件格式。

指定链接本地 IP 的列表。链路本地 IP 是属于众所周知的子网的特殊 IP，并且完全由运营商管理，通常取决于部署它们的架构。因此它们不受 docker（IPAM 驱动程序）管理。

用法示例：

version: "2.4"
services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

优先事项

指定优先级以指示 Compose 应按什么顺序将服务的容器连接到其网络。如果未指定，则默认值为0。

在以下示例中，app服务首先连接，app_net_1因为它具有最高优先级。然后它连接到app_net_3then app_net_2，它使用默认优先级值0。

version: "2.4"
services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

笔记

如果多个网络具有相同的优先级，则连接顺序未定义。

PID

pid: "host"

pid: "container:custom_container_1"

pid: "service:foobar"

如果设置为以下形式之一：container:<container_name>、 service:<service_name>，则该服务共享指定容器或服务的 PID 地址空间。

如果设置为“host”，则服务的PID模式是主机PID模式。这将开启容器和主机操作系统之间共享 PID 地址空间。使用此标志启动的容器可以访问和操作裸机名称空间中的其他容器，反之亦然。

添加到 版本 2.1文件格式。

和service:表格container:需要 2.1或更高版本

pids_限制

添加到 版本 2.1文件格式。

调整容器的 PID 限制。设置-1为无限制 PID。

pids_limit: 10

平台

2.4 版本添加 文件格式。

该服务的目标平台容器将使用以下语法运行 os[/arch[/variant]]，例如

platform: osx

platform: windows/amd64

platform: linux/arm64/v8

此参数确定将提取哪个版本的映像和/或将在哪个平台上执行服务的构建。

港口

暴露端口。指定两个端口 ( HOST:CONTAINER)，或仅指定容器端口（选择临时主机端口）。

笔记

以该HOST:CONTAINER格式映射端口时，如果使用低于 60 的容器端口，您可能会遇到错误结果，因为 YAML 将该格式中的数字解析xx:yy为以 60 为基数的值。因此，我们建议始终将端口映射显式指定为字符串。

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"
  - "12400-12500:1240"

运行

在2.3 版本中添加了 文件格式。

指定服务容器使用哪个运行时。默认运行时和可用运行时在 的输出中列出docker info。

web:
  image: busybox:latest
  command: true
  runtime: runc

规模

在2.2 版本中添加了 文件格式。

指定为此服务部署的默认容器数量。每当您运行 时docker-compose up，Compose 都会创建或删除容器以匹配指定的数量。可以使用以下命令覆盖该值 --scale

web:
  image: busybox:latest
  command: echo 'scaled'
  scale: 3

安全选项

覆盖每个容器的默认标签方案。

security_opt:
  - label:user:USER
  - label:role:ROLE

停止宽限期

stop_signal指定在发送 SIGKILL 之前尝试停止容器（如果容器不处理 SIGTERM（或使用 指定的任何停止信号））时要等待的时间 。指定为 持续时间。

stop_grace_period: 1s

stop_grace_period: 1m30s

默认情况下，stop在发送 SIGKILL 之前等待 10 秒让容器退出。

停止信号

设置替代信号来停止容器。默认情况下stop使用 SIGTERM。使用stop_signal原因 设置替代信号stop以发送该信号。

stop_signal: SIGUSR1

存储选项

添加到 版本 2.1文件格式。

为此服务设置存储驱动程序选项。

storage_opt:
  size: '1G'

系统命令

添加到 版本 2.1文件格式。

要在容器中设置的内核参数。您可以使用数组或字典。

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

临时文件系统

在容器内挂载临时文件系统。可以是单个值或列表。

tmpfs: /run

tmpfs:
  - /run
  - /tmp

极限值

覆盖容器的默认 ulimit。您可以将单个限制指定为整数，也可以将软/硬限制指定为映射。

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

用户模式

添加到 版本 2.1文件格式。

userns_mode: "host"

如果 Docker 守护进程配置了用户命名空间，则禁用此服务的用户命名空间。请参阅 dockerd了解更多信息。

卷

挂载主机路径或命名卷。命名卷需要使用 顶级volumeskey来指定。

简短语法

短语法使用通用[SOURCE:]TARGET[:MODE]格式，其中 SOURCE可以是主机路径或卷名称。TARGET是安装卷的容器路径。标准模式ro用于只读和rw读写（默认）。

您可以在主机上安装相对路径，该路径相对于正在使用的 Compose 配置文件的目录进行扩展。相对路径应始终以.或开头..。

volumes:
  # Just specify a path and let the Engine create a volume
  - /var/lib/mysql

  # Specify an absolute path mapping
  - /opt/data:/var/lib/mysql

  # Path on the host, relative to the Compose file
  - ./cache:/tmp/cache

  # User-relative path
  - ~/configs:/etc/configs/:ro

  # Named volume
  - datavolume:/var/lib/mysql

长语法

在2.3 版本中添加了 文件格式。

长格式语法允许配置无法以短格式表达的附加字段。

• type: 安装类型volume, bind,tmpfs或npipe
• source：挂载的源、主机上用于绑定挂载的路径或 顶级volumes键中定义的卷的名称。不适用于 tmpfs 安装。
• target：卷挂载的容器中的路径
• read_only：将卷设置为只读的标志
• bind：配置附加绑定选项
  • propagation：用于绑定的传播模式
• volume：配置附加音量选项
  • nocopy：创建卷时禁止从容器复制数据的标志
• tmpfs：配置额外的 tmpfs 选项
  • size：tmpfs 挂载的大小（以字节为单位）

version: "2.4"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:

笔记

创建绑定挂载时，使用长语法需要事先创建引用的文件夹。如果文件夹不存在，则使用短语法动态创建该文件夹。 有关更多信息，请参阅 绑定安装文档。

卷驱动程序

指定用于此服务上所有声明的卷的默认卷驱动程序。

volume_driver: mydriver

笔记

在 版本 2 文件中，此选项仅适用于匿名卷（在映像中指定的卷，或在volumes没有显式命名卷或主机路径的情况下指定的卷）。要为命名卷配置驱动程序，请使用顶级选项driver中条目下的键 。volumes

有关更多信息，请参阅 Docker 卷和 卷插件。

卷_来自

从另一个服务或容器装载所有卷，可以选择指定只读访问 ( ro) 或读写 ( rw)。如果未指定访问级别，则使用读写。

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

版本 2文件格式已更改 。

重新开始

no是默认的重启策略，在任何情况下都不会重启容器。指定后always，容器始终重新启动。on-failure如果退出代码指示失败错误，则策略将重新启动容器。

restart: "no"

restart: "always"

restart: "on-failure"

restart: "unless-stopped"

cpu_count、cpu_percent、cpu_shares、cpu_period、cpu_quota、cpu、cpuset、域名、主机名、ipc、mac_address、mem_limit、memswap_limit、mem_swappiness、mem_reservation、oom_kill_disable、oom_score_adj、特权、read_only、shm_size、stdin_open、tty、用户、工作目录

其中每个都是单个值，类似于其 docker run对应项。

在2.2 版本中添加了 文件格式。

cpu_count、cpu_percent、 和选项cpus是在 2.2 版本中添加的。

添加到 版本 2.1文件格式。

oom_kill_disable和选项cpu_period是在 2.1 版本中添加的。

cpu_count: 2
cpu_percent: 50
cpus: 0.5
cpu_shares: 73
cpu_quota: 50000
cpu_period: 20ms
cpuset: 0,1

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000
memswap_limit: 2000000000
mem_reservation: 512m
privileged: true

oom_score_adj: 500
oom_kill_disable: true

read_only: true
shm_size: 64M
stdin_open: true
tty: true

指定持续时间

某些配置选项（例如 的interval和timeout子选项） healthcheck接受持续时间作为字符串，格式如下：

2.5s
10s
1m30s
2h32m
5h34m56s

支持的单位为us、ms、s和。mh

指定字节值

某些配置选项（例如device_read_bps的子选项 blkio_config）接受字节值作为字符串，格式如下：

2b
1024kb
2048k
300m
1gb

支持的单位是b, k,m和g, 以及它们的替代符号kb, mb和gb。目前不支持十进制值。

卷配置参考

虽然可以动态 声明卷作为服务声明的一部分，但本节允许您创建可在多个服务之间重用（不依赖于volumes_from）的命名卷，并且可以使用 docker 命令行或API。 有关更多信息，请参阅 docker volume子命令文档。

有关卷的一般信息，请参阅 使用卷和 卷插件。

以下是双服务设置的示例，其中数据库的数据目录作为卷与另一个服务共享，以便可以定期备份：

version: "2.4"

services:
  db:
    image: db
    volumes:
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:

顶级volumes键下的条目可以为空，在这种情况下，它使用引擎配置的默认驱动程序（在大多数情况下，这就是 local驱动程序）。或者，您可以使用以下键对其进行配置：

司机

指定该卷应使用哪个卷驱动程序。默认为 Docker 引擎配置使用的任何驱动程序，在大多数情况下是 local.如果驱动程序不可用，引擎在 docker-compose up尝试创建卷时会返回错误。

driver: foobar

驱动程序选项

将选项列表指定为键值对，以传递给该卷的驱动程序。这些选项取决于驱动程序 - 请参阅驱动程序文档以获取更多信息。选修的。

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

外部的

如果设置为true，则指定该卷是在 Compose 外部创建的。docker-compose up不会尝试创建它，如果它不存在，则会引发错误。

对于该格式的 2.0 版本，不能与其他卷配置键（ 、、 ）external一起使用。2.1 及更高版本不再存在此限制 。driverdriver_optslabels

在下面的示例中， [projectname]_dataCompose 不会尝试创建名为 的卷，而是查找简单名为 的现有卷data并将其挂载到db服务的容器中。

version: "2.4"

services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true

您还可以将卷的名称与 Compose 文件中用于引用它的名称分开指定：

volumes:
  data:
    external:
      name: actual-name-of-volume

在版本 2.1文件格式中已弃用 。

external.name 在 2.1 版本中已被弃用，改为使用文件格式name。

标签

添加到 版本 2.1文件格式。

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

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

labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"

姓名

添加到 版本 2.1文件格式。

为此卷设置自定义名称。名称字段可用于引用包含特殊字符的卷。该名称按原样使用，不会与堆栈名称限定范围。

version: "2.4"
volumes:
  data:
    name: my-app-data

它也可以与属性结合使用external：

version: "2.4"
volumes:
  data:
    external: true
    name: my-app-data

网络配置参考

顶级networks键允许您指定要创建的网络。有关 Compose 使用 Docker 网络功能的完整说明，请参阅 网络指南。

司机

指定该网络应使用哪个驱动程序。

默认驱动程序取决于您使用的 Docker 引擎的配置方式，但在大多数情况下，它位于bridge单个主机和overlaySwarm 上。

如果驱动程序不可用，Docker 引擎将返回错误。

driver: overlay

2.1 版文件格式已更改 。

从 Compose 文件格式 2.1 开始，覆盖网络始终创建为 attachable，并且这是不可配置的。这意味着独立容器可以连接到覆盖网络。

驱动程序选项

将选项列表指定为键值对，以传递给该网络的驱动程序。这些选项取决于驱动程序 - 请参阅驱动程序文档以获取更多信息。选修的。

driver_opts:
  foo: "bar"
  baz: 1

启用ipv6

添加到 版本 2.1文件格式。

在此网络上启用 IPv6 网络。

伊帕姆

指定自定义 IPAM 配置。这是一个具有多个属性的对象，每个属性都是可选的：

• driver：自定义 IPAM 驱动程序，而不是默认的。
• config：包含零个或多个配置块的列表，每个配置块包含以下任意键：
  • subnet：CIDR格式的子网，表示一个网段
  • ip_range：分配容器IP的IP范围
  • gateway：主子网的 IPv4 或 IPv6 网关
  • aux_addresses：网络驱动程序使用的辅助 IPv4 或 IPv6 地址，作为从主机名到 IP 的映射
• options：驱动程序特定选项作为键值映射。

一个完整的例子：

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7
  options:
    foo: bar
    baz: "0"

内部的

默认情况下，Docker 还会连接一个桥接网络以提供外部连接。如果要创建外部隔离的覆盖网络，可以将此选项设置为true。

标签

添加到 版本 2.1文件格式。

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

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

labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

外部的

如果设置为true，则指定该网络是在 Compose 外部创建的。docker-compose up不会尝试创建它，如果它不存在，则会引发错误。

对于 2.0 版格式，不能与其他网络配置键 ( 、、、 )external一起使用。2.1 及更高版本不再存在此限制 。driverdriver_optsipaminternal

在下面的示例中，proxy是通往外部世界的网关。 Compose不会尝试创建一个名为 的网络[projectname]_outside，而是查找一个简单的名为 的现有网络，并将 服务的容器outside连接到该网络。proxy

version: "2.4"

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

您还可以将网络名称与 Compose 文件中用于引用网络的名称分开指定：

version: "2.4"
networks:
  outside:
    external:
      name: actual-name-of-network

不支持版本 2docker-compose文件。请改用 网络模式。

姓名

添加到 版本 2.1文件格式。

为此网络设置自定义名称。名称字段可用于引用包含特殊字符的网络。该名称按原样使用，不会与堆栈名称限定范围。

version: "2.4"
networks:
  network1:
    name: my-app-net

它也可以与属性结合使用external：

version: "2.4"
networks:
  network1:
    external: true
    name: my-app-net

变量替换

您的配置选项可以包含环境变量。 Compose 使用docker compose运行时的 shell 环境中的变量值。例如，假设 shell 包含POSTGRES_VERSION=9.3并且您提供以下配置：

db:
  image: "postgres:${POSTGRES_VERSION}"

当您使用此配置运行时，Compose在 shell 中docker compose up查找 环境变量并替换其值。对于此示例，Compose在运行配置之前将 解析为。POSTGRES_VERSIONimagepostgres:9.3

如果未设置环境变量，Compose 将替换为空字符串。在上面的示例中，如果POSTGRES_VERSION未设置，则该image选项的值为postgres:。

.env您可以使用file设置环境变量的默认值 ，Compose 会自动在项目目录（Compose 文件的父文件夹）中查找该文件。 shell 环境中设置的值会覆盖.env文件中设置的值。

使用docker stack deploy时的注意事项

该.env file功能仅在您使用该docker compose up命令时有效，不适用于docker stack deploy.

$VARIABLE和语法均受${VARIABLE}支持。此外，当使用 2.1 文件格式时，可以使用典型的 shell 语法提供内联默认值：

• ${VARIABLE:-default}评估环境中default是否未设置或为空。VARIABLE
• ${VARIABLE-default}default仅当VARIABLE环境中未设置时才计算为。

同样，以下语法允许您指定强制变量：

• ${VARIABLE:?err}退出并显示一条错误消息，其中包含errif VARIABLE未设置或环境中为空。
• ${VARIABLE?err}退出并显示一条错误消息，其中包含errif VARIABLE未在环境中设置。

${VARIABLE/foo/bar}不支持其他扩展的 shell 样式功能，例如。

$$当您的配置需要文字美元符号时，您可以使用（双美元符号）。这也可以防止 Compose 插入值，因此 a$$ 允许您引用您不希望由 Compose 处理的环境变量。

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

如果您忘记并使用单个美元符号 ( $)，Compose 会将该值解释为环境变量并警告您：

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

扩展字段

添加到 版本 2.1文件格式。

可以通过扩展字段重用配置片段。这些特殊字段可以是任何格式，只要它们位于 Compose 文件的根目录并且其名称以x-字符序列开头即可。

笔记

从 3.7 格式（对于 3.x 系列）和 2.4 格式（对于 2.x 系列）开始，服务、卷、网络、配置和秘密定义的根目录中也允许使用扩展字段。

version: "3.8"
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"

Compose 会忽略这些字段的内容，但可以使用 YAML 锚点将它们插入到资源定义中。例如，如果您希望多个服务使用相同的日志记录配置：

logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

您可以按如下方式编写 Compose 文件：

version: "3.8"
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging

还可以使用 YAML 合并类型部分覆盖扩展字段中的值。例如：

version: "3.8"
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local

撰写文档

• 用户指南
• 安装 Compose
• 撰写文件版本和升级
• 使用 Compose 的示例应用程序
• 命令行参考