Compose file version 3 reference

预计阅读时间：79 分钟

Reference and guidelines

这些主题描述了 Compose 文件格式的版本 3. 这是最新版本.

Compose and Docker compatibility matrix

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 file structure and examples

以下是Docker for Beginners 实验室主题中使用的投票应用程序示例中的示例 Compose 文件，主题为将应用程序部署到 Swarm ：

version: "3.9"
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:
        max_replicas_per_node: 1
        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:

此参考页面上的主题按顶级键的字母顺序组织，以反映 Compose 文件本身的结构. 在配置文件中定义部分的顶级键（例如build 、 deploy 、 depends_on 、 networks等）与支持它们的选项一起作为子主题列出. 这映射到 Compose 文件的<key>: <option>: <value>缩进结构.

Service configuration reference

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

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

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

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

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

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

build

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

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

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

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

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

如果您指定image和build ，则 Compose 使用webapp和 image 中指定的可选tag命名构建的image ：

build: ./dir
image: webapp:tag

这会生成一个名为webapp和tag的图像，从./dir .

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略build选项docker stack命令在部署之前不会构建映像.

context

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

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

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

build:
  context: ./dir

dockerfile

备用 Dockerfile.

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

build:
  context: .
  dockerfile: Dockerfile-alternate

args

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

首先，在 Dockerfile 中指定参数：

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

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

Then specify the arguments under the build key. You can pass a mapping or a list:

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

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

构建参数的范围

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

You can omit the value when specifying a build argument, in which case its value at build time is the value in the environment where Compose is running.

args:
  - buildno
  - gitcommithash

使用布尔值时的提示

YAML 布尔值（ "true" 、 "false" 、 "yes" 、 "no" 、 "on" 、 "off" ）必须用引号括起来，以便解析器将它们解释为字符串.

cache_from

以3.2 版文件格式添加

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

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

labels

在3.3 版文件格式中添加

Add metadata to the resulting image using 码头工人标签. You can use either an array or a dictionary.

建议您使用反向 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"

network

以3.4 版文件格式添加

在构建期间为RUN指令设置网络容器连接.

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

在构建期间使用none禁用网络：

build:
  context: .
  network: none

shm_size

以3.5 版文件格式添加

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

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

target

以3.4 版文件格式添加

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

build:
  context: .
  target: prod

cap_add, cap_drop

添加或删除容器功能. 有关完整列表，请参阅man 7 capabilities .

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略cap_add和cap_drop选项

cgroup_parent

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

cgroup_parent: m-executor-abcd

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略cgroup_parent选项

command

覆盖默认命令.

command: bundle exec thin -p 3000

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

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

configs

使用 per-service configs配置在每个服务的基础上授予对配置的访问权限. 支持两种不同的语法变体.

注意：该配置必须已经存在或在此堆栈文件的顶级configs配置中定义，否则堆栈部署失败.

有关配置的更多信息，请参阅配置.

Short syntax

短语法变体仅指定配置名称. 这将授予容器对配置的访问权限并将其安装在容器内的/<config_name>处. 源名称和目标挂载点都设置为配置名称.

以下示例使用简短语法授予redis服务对my_config和my_other_config配置的访问权限. my_config的值被设置为文件./my_config.txt的内容，而my_other_config被定义为外部资源，这意味着它已经在 Docker 中定义，通过运行docker config create命令或通过另一个堆栈部署. 如果外部配置不存在，堆栈部署将失败并出现config not found错误.

以3.3 版文件格式添加.

config定义仅在 compose 文件格式的 3.3 及更高版本中受支持.

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

长语法为如何在服务的任务容器中创建配置提供了更多的粒度.

• source ：在此配置中定义的配置标识符.
• target ：要挂载到服务任务容器中的文件的路径和名称. 如果未指定，则默认为/<source> .
• uid和gid ：在服务的任务容器中拥有挂载配置文件的数字 UID 或 GID. 如果未指定，两者在 Linux 上都默认为0 . 在 Windows 上不支持.
• mode ：挂载在服务的任务容器中的文件的权限，以八进制表示. 例如， 0444代表世界可读. 默认值为0444 . 配置不能写，因为它们被挂载在一个临时文件系统中，所以如果你设置了可写位，它会被忽略. 可执行位可以设置. 如果您不熟悉 UNIX 文件权限模式，您可能会发现此权限计算器很有用.

以下示例在容器中将redis_config my_config将模式设置为0440 （组可读）并将用户和组设置为103 . redis服务无权访问my_other_config配置.

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

您可以授予服务访问多个配置的权限，并且可以混合使用长语法和短语法. 定义配置并不意味着授予服务对其的访问权限.

container_name

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

container_name: my-web-container

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

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时会忽略container_name选项

credential_spec

以3.3 版文件格式添加.

在 v3.3 中添加了credential_spec选项. 文件格式版本 3.8 或更高版本支持将组托管服务帐户 (gMSA) 配置与撰写文件一起使用.

为托管服务帐户配置凭据规范. 此选项仅用于使用 Windows 容器的服务. credential_spec必须采用file://<filename>或registry://<value-name>格式.

使用file:时，引用的文件必须存在于 Docker 数据目录的CredentialSpecs子目录中，在 Windows 上默认为C:\ProgramData\Docker\ . 以下示例从名为C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json的文件加载凭证规范.

credential_spec:
  file: my-credential-spec.json

当使用registry:时，凭据规范是从守护进程主机上的 Windows 注册表中读取的. 具有给定名称的注册表值必须位于：

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

以下示例从注册表中名为my-credential-spec的值加载凭据规范：

credential_spec:
  registry: my-credential-spec

Example gMSA configuration

为服务配置 gMSA 凭证规范时，您只需使用config指定凭证规范，如下例所示：

version: "3.9"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|

depends_on

表达服务之间的依赖关系. 服务依赖会导致以下行为：

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

简单的例子：

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

使用depends_on时有几件事情需要注意：

• 在启动web之前， depends_on不会等待db和redis "准备好" - 仅在它们启动之前. 如果您需要等待服务准备好，请参阅控制启动顺序以获取有关此问题的更多信息以及解决该问题的策略.
• 在使用版本 3 Compose 文件以 swarm 模式部署堆栈时，将忽略depends_on选项.

deploy

以版本 3文件格式添加.

指定与服务的部署和运行相关的配置. 以下
sub-options 仅在使用docker stack deploy部署到swarm时生效，并且被docker-compose up和docker-compose run忽略，除了resources .

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

有几个子选项可用：

endpoint_mode

以3.2 版文件格式添加.

为连接到 swarm 的外部客户端指定服务发现方法.

• endpoint_mode: vip - Docker 为服务分配一个虚拟 IP (VIP)，作为客户端访问网络上服务的前端. Docker 在客户端和服务的可用工作节点之间路由请求，而客户端不知道有多少节点参与服务或它们的 IP 地址或端口. （这是默认设置.）

• endpoint_mode: dnsrr - DNS 循环 (DNSRR) 服务发现不使用单个虚拟 IP. Docker 为服务设置 DNS 条目，以便对服务名称的 DNS 查询返回 IP 地址列表，客户端直接连接到其中一个. 在您想要使用自己的负载均衡器或混合 Windows 和 Linux 应用程序的情况下，DNS 循环非常有用.

version: "3.9"

services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    networks:
      - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

  mysql:
    image: mysql
    volumes:
       - db-data:/var/lib/mysql/data
    networks:
       - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: dnsrr

volumes:
  db-data:

networks:
  overlay:

endpoint_mode的选项也可以作为 swarm 模式 CLI 命令docker service create的标志. 有关所有 swarm 相关docker命令的快速列表，请参阅Swarm 模式 CLI 命令.

要了解有关 swarm 模式下的服务发现和网络的更多信息，请参阅 swarm 模式主题中的配置服务发现.

labels

指定服务的标签. 这些标签仅设置在服务上，而不设置在服务的任何容器上.

version: "3.9"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

要在容器上设置标签，请在deploy之外使用labels键：

version: "3.9"
services:
  web:
    image: web
    labels:
      com.example.description: "This label will appear on all containers for the web service"

mode

global （每个 swarm 节点只有一个容器）或replicated （指定数量的容器）. 默认为已replicated . （要了解更多信息，请参阅swarm主题中的复制服务和全局服务.）

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global

placement

指定约束和首选项的位置. 有关语法和可用约束类型、 首选项以及指定每个节点的最大副本数的完整描述，请参阅 docker 服务创建文档.

version: "3.9"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone

max_replicas_per_node

以3.8 版文件格式添加.

如果服务被replicated （这是默认设置），请随时限制可以在节点上运行的副本数量.

当请求的任务多于正在运行的节点时，将引发错误no suitable node (max replicas per node limit exceed) .

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1

replicas

如果服务被replicated （这是默认设置），请指定在任何给定时间应该运行的容器数量.

version: "3.9"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6

resources

配置资源约束.

在撰写文件版本 3 中更改

resources部分替换了 Compose 版本 3 之前的文件中的旧资源约束选项（ cpu_shares 、 cpu_quota 、 cpuset 、 mem_limit 、 memswap_limit 、 mem_swappiness ）. 请参阅将版本 2.x 升级到 3.x以了解 compose-file 格式的版本 2 和 3 之间的差异.

其中每一个都是一个值，类似于它的docker service create对应项.

在这个通用示例中， redis服务被限制为使用不超过 50M 的内存和0.50 （单核的 50%）的可用处理时间（CPU），并保留20M的内存和0.25的 CPU 时间（始终可用）给它）.

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M

下面的主题描述了对集群中的服务或容器设置资源约束的可用选项.

寻找在非集群模式容器上设置资源的选项？

此处描述的选项特定于deploy密钥和群模式. 如果要对非 swarm 部署设置资源限制，请使用Compose 文件格式版本 2 CPU、内存和其他资源选项. 如果您还有其他问题，请参阅 GitHub 问题docker/compose/4513上的讨论.

Out Of Memory Exceptions (OOME)

如果您的服务或容器尝试使用比系统可用内存更多的内存，您可能会遇到内存不足异常 (OOME)，并且容器或 Docker 守护程序可能会被内核 OOM 杀手杀死. 为防止这种情况发生，请确保您的应用程序在具有足够内存的主机上运行，​​并参阅了解内存不足的风险.

restart_policy

配置是否以及如何在容器退出时重新启动容器. 替换restart .

• condition ： none ， on-failure或any之一（默认值： any ）.
• delay ：重新启动尝试之间等待的时间，指定为持续时间（默认值：5s）.
• max_attempts: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not succeed within the configured window, this attempt doesn’t count toward the configured max_attempts value. For example, if max_attempts is set to ‘2’, and the restart fails on the first attempt, more than two restarts may be attempted.
• window ：在决定重启是否成功之前等待多长时间，指定为持续时间（默认值：立即决定）.

version: "3.9"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

rollback_config

以3.7 版文件格式添加.

配置在更新失败的情况下应如何回滚服务.

• parallelism ：一次回滚的容器数. 如果设置为 0，所有容器同时回滚.
• delay ：每个容器组回滚之间的等待时间（默认 0s）.
• failure_action ：如果回滚失败该怎么办. continue或pause之一（默认pause ）
• monitor ：每次任务更新后监控失败的持续时间(ns|us|ms|s|m|h) （默认 5s）注意：设置为 0 将使用默认 5s.
• max_failure_ratio ：回滚期间容忍的失败率（默认为 0）.
• order ：回滚期间的操作顺序. stop-first （旧任务在开始新任务之前停止）或start-first （新任务先启动，正在运行的任务短暂重叠）（默认stop-first ）之一.

update_config

配置应如何更新服务. 对于配置滚动更新很有用.

• parallelism ：一次更新的容器数.
• delay ：更新一组容器之间的等待时间.
• failure_action ：如果更新失败怎么办. continue ， rollback或pause之一（默认值： pause ）.
• monitor ：每次任务更新后监控失败的持续时间(ns|us|ms|s|m|h) （默认 5s）注意：设置为 0 将使用默认 5s.
• max_failure_ratio ：更新期间容忍的失败率.
• order ：更新期间的操作顺序. stop-first （旧任务在开始新任务之前停止）或start-first （新任务先启动，正在运行的任务短暂重叠）之一（默认stop-first ）注意：仅支持 v3.4 及更高版本.

以3.4 版文件格式添加.

order选项仅受 compose 文件格式的 v3.4 及更高版本支持.

version: "3.9"
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
        order: stop-first

Not supported for docker stack deploy

docker stack deploy或deploy键不支持以下子选项（支持docker-compose up和docker-compose run ）.

• build
• cgroup_parent
• container_name
• devices
• tmpfs
• external_links
• links
• network_mode
• restart
• security_opt
• userns_mode

Tip

请参阅如何为服务、群和 docker-stack.yml 文件配置卷的部分. 卷是受支持的，但要与群和服务一起使用，它们必须配置为命名卷或与服务相关联，这些服务仅限于可以访问必要卷的节点.

devices

设备映射列表. 使用与--device docker client create 选项相同的格式.

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

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时， devices选项被忽略

dns

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

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_search

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

dns_search: example.com

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

entrypoint

覆盖默认入口点.

entrypoint: /code/entrypoint.sh

入口点也可以是一个列表，其方式类似于dockerfile ：

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

Note

设置entrypoint点既会覆盖使用ENTRYPOINT Dockerfile 指令在服务映像上设置的任何默认入口点，也会清除映像上的任何默认命令——这意味着如果 Dockerfile 中有CMD指令，它将被忽略.

env_file

Add environment variables from a file. Can be a single value or a list.

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

Environment variables declared in the environment section override these values – this holds true even if those values are empty or undefined.

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

Compose 还可以识别内联注释，例如：

MY_VAR = value # this is a comment

为避免将"#"解释为内联注释，请使用引号：

MY_VAR = "All the # inside are taken as part of the value"

Note

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

VAL的值按原样使用，根本不修改. 例如，如果值被引号包围（这通常是 shell 变量的情况），则引号将包含在传递给 Compose 的值中.

请记住，列表中文件的顺序对于确定分配给多次出现的变量的值很重要. 列表中的文件是自上而下处理的. 对于在文件b.env中指定并在文件a.env中分配不同值的相同变量，如果b.env在下面（之后）列出，则b.env中的值代表. 例如，给定docker-compose.yml中的以下声明：

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

以及以下文件：

# a.env
VAR=1

and

# b.env
VAR=hello

$VAR is hello.

environment

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

只有一个键的环境变量在运行 Compose 的机器上解析为它们的值，这对于秘密或特定于主机的值很有帮助.

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

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

Note

如果您的服务指定了构建选项，则environment中定义的变量在构建期间不会自动可见. 使用build的args子选项来定义构建时环境变量.

expose

公开端口而不将它们发布到主机 - 它们只能被链接服务访问. 只能指定内部端口.

expose:
  - "3000"
  - "8000"

external_links

链接到在这个docker-compose.yml甚至在 Compose 之外启动的容器，特别是对于提供共享或公共服务的容器. 在同时指定容器名称和链接别名 ( CONTAINER:ALIAS ) 时， external_links遵循类似于遗留选项links的语义.

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

Note

外部创建的容器必须连接到至少一个与链接到它们的服务相同的网络. 链接是一个遗留选项. 我们建议改用网络.

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略external_links选项

extra_hosts

添加主机名映射. 使用与 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

healthcheck

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

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

interval ， timeout和start_period被指定为持续时间.

以3.4 版文件格式添加.

start_period选项以文件格式 3.4 添加.

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

image

指定启动容器的镜像. 可以是存储库/标签或部分图像 ID.

image: redis

image: ubuntu:18.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

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

init

以3.7 版文件格式添加.

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

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

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

isolation

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

labels

Add metadata to containers using 码头工人标签. You can use either an array or a dictionary.

建议您使用反向 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"

links

Warning

--link标志是 Docker 的遗留功能. 它最终可能会被删除. 除非您绝对需要继续使用它，否则我们建议您使用用户定义的网络来促进两个容器之间的通信，而不是使用--link .

用户定义的网络不支持您可以使用--link执行的一项功能是在容器之间共享环境变量. 但是，您可以使用其他机制（例如卷）以更可控的方式在容器之间共享环境变量.

链接到另一个服务中的容器. 要么指定服务名称和链接别名（ "SERVICE:ALIAS" ），要么只指定服务名称.

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

链接服务的容器可以通过与别名相同的主机名访问，如果没有指定别名，则可以使用服务名.

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

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

Note

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

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略links选项

logging

服务的日志记录配置.

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

driver名称指定服务容器的日志驱动程序，与 docker run 的--log-driver选项一样（在此处记录）.

默认值为 json 文件.

driver: "json-file"

driver: "syslog"

driver: "none"

Note

只有json-file和journald驱动程序可以直接从 docker docker-compose up和docker-compose logs获取日志. 使用任何其他驱动程序不会打印任何日志.

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

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

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

默认驱动程序json-file具有限制存储日志量的选项. 为此，请使用键值对来获取最大存储大小和最大文件数：

options:
  max-size: "200k"
  max-file: "10"

上面显示的示例将存储日志文件，直到它们达到 200kB 的max-size ，然后旋转它们. 存储的单个日志文件的数量由max-file值指定. 随着日志增长超过最大限制，旧日志文件将被删除以允许存储新日志.

这是一个限制日志存储的示例docker-compose.yml文件：

version: "3.9"
services:
  some-service:
    image: some-service
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

可用的日志记录选项取决于您使用的日志记录驱动程序

上面用于控制日志文件和大小的示例使用特定于json-file 驱动程序的选项. 这些特定选项在其他日志记录驱动程序上不可用. 有关支持的日志记录驱动程序及其选项的完整列表，请参阅日志记录驱动程序文档.

network_mode

网络模式. 使用与 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]"

Note

• 在 swarm 模式下部署堆栈时，此选项将被忽略.
• network_mode: "host"不能与链接混合.

networks

要加入的网络，引用顶级networks键下的条目.

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

aliases

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

由于aliases是网络范围的，相同的服务在不同的网络上可以有不同的别名.

Note

网络范围的别名可以被多个容器共享，甚至可以被多个服务共享. 如果是，则无法保证名称解析为哪个容器.

一般格式如下所示.

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

在下面的示例中，提供了三个服务（ web 、 worker和db ），以及两个网络（ new和legacy ）. db服务可在new网络上的主机名db或database以及legacy网络上的db或mysql上访问.

version: "3.9"

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_address, ipv6_address

加入网络时，为此服务的容器指定静态 IP 地址.

The corresponding network configuration in the 顶级网络部分 must have an ipam block with subnet configurations covering each static address.

如果您想使用 IPv6，您必须首先确保将 Docker 守护程序配置为支持 IPv6. 有关详细说明，请参阅启用 IPv6 . 然后，您可以在 3.x 版 Compose 文件中访问 IPv6 寻址，方法是编辑/etc/docker/daemon.json以包含： {"ipv6": true, "fixed-cidr-v6": "2001:db8:1::/64"}

然后，重新加载 docker 守护进程并编辑 docker-compose.yml 以在服务下包含以下内容：

    sysctls:
      - net.ipv6.conf.all.disable_ipv6=0

enable_ipv6选项仅在2.x Compose 文件中可用. IPv6 选项目前不适用于群模式.

一个例子：

version: "3.9"

services:
  app:
    image: nginx:alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

pid

pid: "host"

将 PID 模式设置为主机 PID 模式. 这将打开容器和主机操作系统之间共享 PID 地址空间. 使用此标志启动的容器可以访问和操作裸机命名空间中的其他容器，反之亦然.

ports

暴露端口.

Note

端口映射与network_mode: host不兼容

Note

docker docker-compose run忽略ports ，除非您包含--service-ports .

Short syntax

有三个选项：

• 指定两个端口（ HOST:CONTAINER ）
• 仅指定容器端口（为主机端口选择一个临时主机端口）.
• 指定要绑定到两个端口的主机 IP 地址（默认为 0.0.0.0，表示所有接口）：（ IPADDR:HOSTPORT:CONTAINERPORT ）. 如果 HOSTPORT 为空（例如127.0.0.1::80 ），则选择绑定到主机上的临时端口.

Note

以HOST:CONTAINER格式映射端口时，使用低于 60 的容器端口时可能会遇到错误结果，因为 YAML 将xx:yy格式的数字解析为 base-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"
  - "127.0.0.1::5000"
  - "6060:6060/udp"
  - "12400-12500:1240"

Long syntax

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

• target : 容器内的端口
• published ：公开的端口
• protocol ：端口协议（ tcp或udp ）
• mode : 用于在每个节点上发布host端口的主机，或用于负载均衡的集群模式端口的ingress .

ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

以3.2 版文件格式添加.

长语法在 v3.2 文件格式中是新的.

profiles

profiles: ["frontend", "debug"]
profiles:
  - frontend
  - debug

profiles为要启用的服务定义了一个命名配置文件列表. 如果未设置，则始终启用该服务. 对于构成核心应用程序的服务，您应该省略profiles ，以便它们始终启动.

有效的配置文件名称遵循正则表达式格式[a-zA-Z0-9][a-zA-Z0-9_.-]+ .

另请参阅将配置文件与 Compose一起使用以了解有关配置文件的更多信息.

restart

no是默认的重启策略，在任何情况下都不重启容器. 当指定always时，容器总是重新启动. 如果退出代码指示出现故障时错误，则on-failure策略会重新启动容器. unless-stopped停止（手动或其他方式）停止容器，否则总是重新启动容器.

restart: "no"
restart: always
restart: on-failure
restart: unless-stopped

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时，将忽略restart选项.

secrets

使用 per-service secrets配置在每个服务的基础上授予对 secret 的访问权限. 支持两种不同的语法变体.

使用 docker stack deploy 时的注意事项

该密钥必须已存在或已在撰写文件的顶级secrets配置中定义，否则堆栈部署将失败.

有关机密的更多信息，请参阅机密.

Short syntax

短语法变体仅指定秘密名称. 这将授予容器对密钥的访问权限并将其安装在容器内的/run/secrets/<secret_name>处. 源名称和目标挂载点都设置为机密名称.

以下示例使用简短语法授予redis服务访问my_secret和my_other_secret机密的权限. my_secret的值被设置为文件./my_secret.txt的内容，而my_other_secret被定义为外部资源，这意味着它已经在 Docker 中定义，通过运行docker secret create命令或通过另一个堆栈部署. 如果外部机密不存在，堆栈部署将失败并出现secret not found错误.

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

Long syntax

长语法为如何在服务的任务容器中创建密钥提供了更多的粒度.

• source ：在此配置中定义的秘密标识符.
• target ：要挂载在服务任务容器中的/run/secrets/中的文件的名称. 如果未指定，则默认为source .
• uid和gid ：拥有服务任务容器中/run/secrets/中文件的数字 UID 或 GID. 如果未指定，则两者都默认为0 .
• mode : 文件挂载到服务任务容器中的/run/secrets/的权限，以八进制表示. 例如， 0444代表世界可读. Docker 1.13.1 中的默认值为0000 ，但在较新版本中为0444 . 秘密不能被写，因为它们被挂载在一个临时文件系统中，所以如果你设置了可写位，它就会被忽略. 可执行位可以设置. 如果您不熟悉 UNIX 文件权限模式，您可能会发现此权限计算器很有用.

以下示例在容器中将redis_secret的名称设置为my_secret ，将模式设置为0440 （组可读）并将用户和组设置为103 . redis服务无权访问my_other_secret密钥.

version: "3.9"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true

您可以授予服务访问多个机密的权限，并且可以混合使用长语法和短语法. 定义秘密并不意味着授予服务对其的访问权限.

security_opt

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

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

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时忽略security_opt选项.

stop_grace_period

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

stop_grace_period: 1s

stop_grace_period: 1m30s

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

stop_signal

设置一个替代信号来停止容器. 默认情况下， stop使用 SIGTERM. 使用stop_signal设置替代信号会导致stop改为发送该信号.

stop_signal: SIGUSR1

sysctls

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

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

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

您只能使用在内核中命名空间的 sysctl. Docker 不支持更改容器内的 sysctls 也会修改主机系统. 有关支持的 sysctls 的概述，请参阅在运行时配置命名空间内核参数 (sysctls) .

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时，此选项需要 Docker Engine 19.03 或更高版本.

tmpfs

以3.6 版文件格式添加.

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

tmpfs: /run

tmpfs:
  - /run
  - /tmp

使用 docker stack deploy 时的注意事项

当使用（版本 3-3.5）撰写文件以集群模式部署堆栈时，此选项将被忽略.

在容器内挂载一个临时文件系统. Size 参数指定 tmpfs 挂载的大小（以字节为单位）. 默认无限制.

- type: tmpfs
  target: /app
  tmpfs:
    size: 1000

ulimits

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

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

userns_mode

userns_mode: "host"

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

使用 docker stack deploy 时的注意事项

在 swarm 模式下部署堆栈时，会忽略userns_mode选项.

volumes

挂载主机路径或命名卷，指定为服务的子选项.

您可以将主机路径挂载为单个服务定义的一部分，无需在顶级volumes键中定义它.

但是，如果您想跨多个服务重用一个卷，请在顶级volumes键中定义一个命名卷. 将命名卷与服务、群和堆栈文件一起使用.

更改了版本 3的文件格式.

顶级卷键定义了一个命名卷并从每个服务的volumes列表中引用它. 这将替换早期版本的 Compose 文件格式中的volumes_from .

此示例显示了web服务使用的命名卷 ( mydata )，以及为单个服务定义的绑定挂载 ( db service volumes下的第一个路径). db服务还使用名为dbdata的命名卷（ db service volumes下的第二条路径），但使用旧字符串格式定义它以安装命名卷. 命名卷必须列在顶级volumes键下，如图所示.

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

  db:
    image: postgres:latest
    volumes:
      - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock"
      - "dbdata:/var/lib/postgresql/data"

volumes:
  mydata:
  dbdata:

Note

有关卷的一般信息，请参阅文档中的使用卷和卷插件部分.

Short syntax

简短语法使用通用[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

Long syntax

以3.2 版文件格式添加.

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

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

version: "3.9"
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:

Note

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

Volumes for services, swarms, and stack files

使用 docker stack deploy 时的注意事项

在使用服务、群和docker-stack.yml文件时，请记住，支持服务的任务（容器）可以部署在群中的任何节点上，并且每次更新服务时这可能是不同的节点.

在没有指定源的命名卷的情况下，Docker 为每个支持服务的任务创建一个匿名卷. 删除关联容器后，匿名卷不会持续存在.

如果您希望数据持久化，请使用命名卷和可识别多主机的卷驱动程序，以便可以从任何节点访问数据. 或者，对服务设置约束，以便将其任务部署在存在卷的节点上.

例如， Docker Labs 中votingapp 示例的 docker docker-stack.yml文件定义了一个名为db的服务，该服务运行一个postgres数据库. 它被配置为命名卷以将数据持久保存在 swarm 上，并且被限制为仅在manager节点上运行. 这是该文件中的相关片段：

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

domainname, hostname, ipc, mac_address, privileged, read_only, shm_size, stdin_open, tty, user, working_dir

其中每一个都是一个值，类似于它的docker run对应项. 请注意， mac_address是一个旧选项.

user: postgresql
working_dir: /code

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

privileged: true


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

Specifying durations

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

2.5s
10s
1m30s
2h32m
5h34m56s

The supported units are us, ms, s, m and h.

Specifying byte values

一些配置选项，例如build的shm_size子选项，接受一个字节值作为字符串，格式如下：

2b
1024kb
2048k
300m
1gb

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

Volume configuration reference

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

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

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

version: "3.9"

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驱动程序）. 或者，您可以使用以下键对其进行配置：

driver

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

driver: foobar

driver_opts

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

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

external

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

对于 3.3 及以下版本的格式， external不能与其他卷配置键（ driver 、 driver_opts 、 labels ）结合使用. 3.4 及更高版本不再存在此限制.

在下面的示例中，Compose 并没有尝试创建一个名为[projectname]_data的卷，而是查找一个名为data的现有卷并将其挂载到db服务的容器中.

version: "3.9"

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

volumes:
  data:
    external: true

在3.4 版文件格式中已弃用.

external.name 在版本 3.4 文件格式中已弃用，改用name .

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

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

Note when using docker stack deploy

如果您使用docker stack deploy以swarm 模式（而不是docker compose up ）启动应用程序，则会创建不存在的外部卷. 在 swarm 模式下，卷在由服务定义时自动创建. 随着服务任务在新节点上调度， swarmkit在本地节点上创建卷. 要了解更多信息，请参阅moby/moby#29976 .

labels

使用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"

name

以3.4 版文件格式添加.

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

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

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

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

Network configuration reference

顶级networks键允许您指定要创建的网络.

• 有关 Compose 使用 Docker 网络功能和所有网络驱动程序选项的完整说明，请参阅网络指南.
• 对于Docker Labs网络教程，从设计可扩展、可移植的 Docker 容器网络开始

driver

指定应为此网络使用的驱动程序.

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

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

driver: overlay

bridge

Docker 默认在单个主机上使用bridge网络. 有关如何使用桥接网络的示例，请参阅有关桥接网络的 Docker 实验室教程.

overlay

overlay驱动程序在一个swarm中的多个节点上创建一个命名网络.

• 有关如何在 swarm 模式下构建和使用带有服务的overlay网络的工作示例，请参阅 Docker 实验室关于覆盖网络和服务发现的教程.

• 如需深入了解其底层工作原理，请参阅Overlay Driver Network Architecture上的网络概念实验室.

host or none

使用主机的网络堆栈，或不使用网络. 相当于docker run --net=host或docker run --net=none . 仅在使用docker stack命令时使用. 如果您使用docker-compose命令，请改用network_mode .

如果您想在公共构建中使用特定网络，请使用第二个 yaml 文件示例中提到的 [network].

使用内置网络（例如host和none ）的语法略有不同. 使用名称host或none （Docker 已经自动创建）和 Compose 可以使用的别名（以下示例中的hostnet或nonet ）定义一个外部网络，然后使用别名授予服务访问该网络的权限.

version: "3.9"
services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host

services:
  web:
    ...
    build:
      ...
      network: host
      context: .
      ...

services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none

driver_opts

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

driver_opts:
  foo: "bar"
  baz: 1

attachable

以3.2 版文件格式添加.

仅在driver设置为overlay时使用. 如果设置为true ，那么除了服务之外，独立容器还可以附加到该网络. 如果独立容器连接到覆盖网络，它可以与服务和独立容器通信，这些服务和独立容器也从其他 Docker 守护程序连接到覆盖网络.

networks:
  mynet1:
    driver: overlay
    attachable: true

enable_ipv6

在此网络上启用 IPv6 网络.

Compose File 版本 3 中不支持

enable_ipv6要求您使用版本 2 Compose 文件，因为 Swarm 模式尚不支持此指令.

ipam

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

• driver ：自定义 IPAM 驱动程序，而不是默认驱动程序.
• config ：具有零个或多个配置块的列表，每个配置块包含以下任何键：
  • subnet : CIDR 格式的子网，代表一个网段

一个完整的例子：

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16

Note

其他 IPAM 配置，例如gateway ，目前仅适用于版本 2.

internal

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

labels

使用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"

external

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

For version 3.3 and below of the format, external cannot be used in conjunction with other network configuration keys (driver, driver_opts, ipam, internal). This limitation no longer exists for 3.4版 and above.

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

version: "3.9"

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

networks:
  outside:
    external: true

在3.5 版文件格式中已弃用.

external.name 在版本 3.5 文件格式中已弃用，改用name .

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

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

name

以3.5 版文件格式添加.

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

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

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

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

configs configuration reference

顶级configs声明定义或引用可以授予此堆栈中的服务的配置. 配置的来源是file或external .

• file ：使用指定路径的文件内容创建配置.
• external ：如果设置为 true，则指定此配置已创建. Docker 不会尝试创建它，如果它不存在，则会发生config not found错误.
• name ：Docker 中配置对象的名称. 该字段可用于引用包含特殊字符的配置. 该名称按原样使用，不会与堆栈名称一起使用. 以 3.5 版文件格式引入.
• driver和driver_opts ：自定义秘密驱动程序的名称，以及作为键/值对传递的特定于驱动程序的选项. 以 3.8 版文件格式引入，仅在使用docker stack时支持.
• template_driver ：要使用的模板驱动程序的名称，它控制是否以及如何将秘密有效负载评估为模板. 如果未设置驱动程序，则不使用模板. 当前支持的唯一驱动程序是golang ，它使用golang . 以 3.8 版文件格式引入，仅在使用docker stack时支持. 有关模板化配置的示例，请参阅使用模板化配置.

在此示例中， my_first_config在部署堆栈时创建（作为<stack_name>_my_first_config) ，并且my_second_config已存在于 Docker 中.

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external: true

外部配置的另一个变体是当 Docker 中的配置名称与服务中存在的名称不同时. 以下示例修改前一个以使用名为redis_config的外部配置.

configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external:
      name: redis_config

您仍然需要向堆栈中的每个服务授予对配置的访问权限.

secrets configuration reference

顶级secrets声明定义或引用可以授予此堆栈中的服务的机密. 秘密的来源是file或external .

• file ：秘密是使用指定路径的文件内容创建的.
• external ：如果设置为 true，则指定此密钥已创建. Docker 不会尝试创建它，如果它不存在，则会发生secret not found错误.
• name ：Docker 中秘密对象的名称. 此字段可用于引用包含特殊字符的机密. 该名称按原样使用，不会与堆栈名称一起使用. 以 3.5 版文件格式引入.
• template_driver: The name of the templating driver to use, which controls whether and how to evaluate the secret payload as a template. If no driver is set, no templating is used. The only driver currently supported is golang, which uses a golang. Introduced in version 3.8 file format, and only supported when using docker stack.

在此示例中， my_first_secret在部署堆栈时创建为<stack_name>_my_first_secret ，并且my_second_secret已存在于 Docker 中.

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true

外部机密的另一种变体是当 Docker 中的机密名称与服务中存在的名称不同时. 以下示例修改了前一个示例以使用名为redis_secret的外部密钥.

Compose File v3.5 and above

secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true
    name: redis_secret

Compose File v3.4 and under

  my_second_secret:
    external:
      name: redis_secret

您仍然需要向堆栈中的每个服务授予对机密的访问权限.

Variable substitution

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

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

当您使用此配置运行docker-compose up时，Compose 会在 shell 中查找POSTGRES_VERSION环境变量并将其值代入.对于此示例，Compose 在运行配置之前将image解析为postgres:9.3 .

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

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

使用 docker stack deploy 时的注意事项

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

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

• 如果VARIABLE在环境中未设置或为空，则${VARIABLE:-default}评估为default .
• 只有在环境中未设置VARIABLE时${VARIABLE-default}才会评估为default .

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

• 如果VARIABLE在环境中未设置或为空，则${VARIABLE:?err}退出并显示包含err的错误消息.
• 如果在环境中未设置VARIABLE ，则${VARIABLE?err}退出并显示包含err的错误消息.

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

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

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

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

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

Extension fields

以3.4 版文件格式添加.

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

Note

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

version: "3.9"
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.9"
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.9"
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 documentation

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