Compose Version 3 参考

这些主题描述了 Compose 的第 3 个版本。这是当前的最新版本。

[TOC]

Compose 和 Docker 兼容性

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

**Compose 文件格式

Docker Engine 版本

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查看，但是文件格式版本不一定随每个版本增加。 例如，Compose 文件格式 3.0 最初是在Compose 版本 1.10.0引入的，并在随后的发布中逐渐版本化。

Compose 文件结构和示例

参考页上的主题按照顶级键（top-level）排序，以反映 Compose 文件的结构。 顶级键是配置文件中的一部分，比如build，deploy，depends_on，networks等等，支持他们的子主题被列出。 这个映射到的缩进结构是<key>: <option>: <value>。

一个很好的起始是阅读入门教程，该教程使用版本 3 的 Compose 文件来实现多容器程序，服务定义和集群模式。 在指南中有一些 Compose 文件用法。

另一个很好的参考是Docker for Beginners 实验主题中 有关将应用程序部署到Swarm的 投票应用程序示例的 Compose 文件。这也显示在本节可折叠的部分中。

服务配置参考（Service）

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

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

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

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

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

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

构建（build）

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

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

或者，作为一个具有上下文路径的对象， 以及可选的Dockerfile 和args：

如果您指定image以及build，则 Compose 使用webapp和可选tag作为image的名字：

这将产生一个名为webapp和 Tag 为tag的镜像，该镜像从./dir构建的。

注意：在以（版本 3） compose 文件以群集模式部署堆栈时， 将忽略此选项 。该docker stack命令仅接受预构建的图像。

语境（CONTEXT）

指向 Dockerfile 目录的路径，或 git 存储库的 URL。

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

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

DOCKERFILE

替换 Dockerfile。

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

ARGS

添加构建参数，这些环境变量只能在构建过程中访问。

首先，在 Dockerfile 中指定参数：

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

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

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

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

CACHE_FROM

注意：此选项是 v3.2 中的新增功能

用于缓存解析的镜像列表。

标签（LABLE）

注意：此选项是 v3.3 中的新增功能

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

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

SHM_SIZE

在v3.5文件格式中添加

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

目标（TARGET）

在v3.4文件格式中添加

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

cap_add，cap_drop

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

注意：在（版本 3）编写以群集模式部署堆栈时， 将忽略这些选项 。

cgroup_parent

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

注意：在（版本 3）编写以群集模式部署堆栈时，将忽略这些选项 。

命令（command）

覆盖默认命令。

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

配置（config）

使用configs 配置授予服务对配置的访问权限。支持两种不同的语法。

注意：该配置必须已经存在或 在configs的顶级配置中定义，否则集群部署失败。

有关配置的更多信息，请参见 configs。

短语法

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

以下示例使用短语法来授予redis服务对my_config和my_other_config配置的访问权限。 my_config的值设置为./my_config.txt的内容，my_other_config定义为外部资源，这意味着它已经在 Docker 中定义，可以通过运行docker config create 命令或通过其他集群部署进行定义。 如果外部配置不存在，则集群部署失败并显示config not found错误。

注意：config仅在 3.3 版及更高版本的 COMPOSE文件格式中支持。

长语法

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

  • source：Docker 中存在的配置名称。

  • target：要在服务的任务容器中挂载的文件的路径和名称。如果未指定，则默认为/<source>。

  • uid和gid：服务的任务容器中拥有已挂载的配置文件的 UID 或 GID。如果未指定，在 Linux 上则两者默认为0，Windows 不支持。

  • mode：服务的容器中文件的权限，以八进制表示法。

    例如，0444 表示全部可读。默认值为0444。

    由于配置文件挂载在临时文件系统中，因此它们不可写。

    如果您修改可写位，则会被忽略。可执行位可以设置。

    如果您不熟悉 UNIX 文件权限模式，则可能会发现此权限计算器很有用。

下面的示例设置的名称my_config，以redis_config在容器内，将模式设定为0440（组可读），并且将所述用户和组103。该redis服务无权访问该my_other_config 配置。

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

container_name

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

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

注意：在以（版本 3）编写文件以群集模式部署时，将忽略此选项 。

credential_spec

注意：此选项已在 v3.3 中添加。在 Compose 版本 3.8 中支持将组托管服务帐户（gMSA）配置与 compose 文件一起使用。

配置托管服务帐户的凭据规范。此选项仅用于使用 Windows 容器的服务。在credential_spec必须在格式file://或registry://。

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

使用registry:，将从守护程序主机上的 Windows 注册表中读取凭据规范。给定名称的注册表值必须位于：

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

GMSA 配置示例

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

依赖（depend_on）

服务之间的依赖关系，服务依赖关系将导致以下行为：

  • docker-compose up以依赖性顺序启动服务。在以下示例中，db和redis在之前启动web。

  • docker-compose up SERVICE自动包含SERVICE的依赖项。在以下示例中，docker-compose up web还将创建并启动db和redis。

  • docker-compose stop按依赖关系顺序停止服务。在以下示例中，web在db和之前停止redis。

简单的例子：

使用时需要注意以下几点depends_on：

  • depends_on web不会等待db和redis“准备就绪”，只会等待到它们启动之时。

    如果需要等待服务准备就绪，请参阅控制启动顺序 以获取有关此问题的更多信息以及解决该问题的策略。

  • 版本 3 不再支持的condition形式depends_on。

  • 在以集群模式 版本的 Compose 文件部署 depends_on时，将忽略该选项 。

部署（deploy）

仅版本 3。

指定与服务的部署和运行有关的配置。这只能部署到集群时生效，并且被忽略docker-compose up和docker-compose run。

有几个子选项可用：

端点模式

为连接到集群的外部客户端指定服务发现方式。

仅版本 3.3。

  • endpoint_mode: vip-Docker 为服务分配了一个虚拟 IP（VIP），该虚拟 IP 充当客户端访问网络服务的前端。

    Docker 在客户端和服务的可用工作节点之间路由请求，而无需客户端知道有多少节点正在参与服务或其 IP 地址与端口。（这是默认设置。）

  • endpoint_mode: dnsrr-DNS 轮询（DNSRR）服务发现不使用单个虚拟 IP。

    Docker 设置服务 DNS 条目，以便对服务名称的 DNS 查询返回 IP 地址列表，并且客户端直接连接到其中之一。

    在想要使用自己的负载平衡器或混合 Windows 和 Linux 应用程序的情况下，DNS 轮询很有用。

选项endpoint_mode还可以在群集模式 CLI 命令docker service create上用作标志 。 有关所有 swarm 相关docker命令的快速列表，请参阅 Swarm 模式 CLI 命令。

要了解有关在群集模式下进行服务发现和联网的更多信息，请参阅在群集模式下 配置服务发现主题。

标签（LABELS）

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

在容器上设置标签，在deploy外使用labels：

模式（MODE）

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

位置（PLACEMENT）

指定约束和首选项的位置。有关约束语法 以及首选项的可用类型完整说明， 请参阅 docker 服务 create 文档。

复制（REPLICAS）

如果服务设置replicated服务，指定了应运行的容器数。

资源（RESOURCES）

配置资源约束。

注意：这取代了旧的资源约束选项， 例如包含在编写非集群模式文件之前版本（cpu_shares，cpu_quota，cpuset， mem_limit，memswap_limit，mem_swappiness） 看升级版本 2.x 到 3.x的描述。

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

在示例中，redis服务被限制为使用不超过 50M 的内存和0.50（不超过单个内核的 50％）可用处理时间（CPU），并且具有保留20M的内存和0.25CPU 时间（始终可用）。

以下主题描述了可用于集群服务或容器资源约束的可用选项。

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

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

内存不足异常（OOME）

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

RESTART_POLICY

配置在退出容器时如何重启容器方式。代替restart

  • condition：none，on-failure或者any（默认值：any）。

  • delay：重新启动尝试的等待的时间，指定 持续时间（默认值：0）。

  • max_attempts：放弃之前尝试重新启动容器的次数（默认值：永不放弃）。如果重新启动在windows时间内未成功，则此尝试不会计入配置max_attempts值。例如，如果max_attempts设置为“ 2”，并且第 1 次尝试重启失败，则可能会再尝试 2 次。

  • window：重新启动是否成功之前要等待的时间，指定为持续时间（默认值：立即）。

ROLLBACK_CONFIG

3.7 版文件格式及更高版本

更新失败的情况下如何回滚服务。

  • parallelism：一次要回滚的容器数。如果设置为 0，则所有容器将同时回滚。

  • delay：每个容器组回滚之间等待的时间（默认为 0s）。

  • failure_action：如果回滚失败将做什么。continue或者pause（默认pause）

  • monitor：每次任务更新后监视的持续时间(ns|us|ms|s|m|h)（默认为 0s）。

  • 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)（默认为0s）。

  • max_failure_ratio：更新期间可以容忍的故障率。

  • order：更新期间的操作顺序。stop-first（旧任务在开始新的一个前停止），start-first（新的任务首先启动，并和正在运行的任务重叠）（默认stop-first）注：仅支持 V3.4 及更高版本。

注意：order仅 v3.4 及更高版本的受支持。

不支持 DOCKER STACK DEPLOY

下面的子选项（支持docker-compose up和docker-compose run）是不支持的docker stack deploy或deploy关键词的。

提示：请参阅有关如何为服务，集权和 docker-stack.yml 文件配置卷的内容。卷是受支持的，但是要与群集和服务一起使用，必须将它们配置为命名卷或或有权访问卷的节点的服务关联。

设备（devices）

设备映射列表。使用与--device和 docker client create相同的格式。

注意：在（版本 3）集群模式部署时，将忽略此选项 。

域名系统（dns）

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

dns_search

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

入口（entrypoint）

覆盖默认入口点。

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

注意： 设置entrypoint会 覆盖 Dockerfile 指令中 ENTRYPOINT 的默认值，并清除镜像上的任何默认命令（command），这意味着如果 Dockerfile 中有CMD指令，则将其忽略。

env_file

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

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

在环境部分声明的环境变量将覆盖这些值 -- 即使这些值为空或未定义。

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

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

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

请记住， 在确定分配给多次出现的变量的值时，列表中的文件顺序非常重要 。列表中的文件从上到下进行处理。对于a.env指定变量一个值，但又在 b.env指定相同变量另一个值，而如果b.env在a.env下面列出，则变量的值来自b.env。例如，在以下docker-compose.yml`：

和：

和：

$VAR是hello。

环境（environment）

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

只有一个键的环境变量被解析为运行在其上的机器上的值，这对于密钥或特定于主机的值很有帮助。

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

暴露（expose）

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

外部链接（external_links）

链接到这个docker-compose.yml外部启动的容器，甚至 Compose 之外，特别是对于提供共享或公共服务的容器。external_links 在同时指定容器名称和链接别名时（CONTAINER:ALIAS）遵循links。

注意：

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

在（版本 3）以集群模式部署时，将忽略此选项。

extra_hosts

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

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

健康检查

2.1 版文件格式及更高版本。

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

interval，timeout和start_period指定间隔时间。

注意：start_period仅 v3.4 及更高版本受支持。

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

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

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

镜像（images）

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

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

init

3.7 版文件格式添加。

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

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

隔离（isolation）

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

标签（labels）

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

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

链接（links）

警告：该--link标志是 Docker 的旧功能。它最终可能会被删除。除非您绝对需要继续使用它，否则我们建议您使用用户定义的网络 来促进两个容器之间的通信，而不要使用--link。 --link是在容器之间共享环境变量。但是，您可以使用其他机制（例如卷）以更可控的方式在容器之间共享环境变量。

链接到另一个服务中的容器。指定服务名称和链接别名（SERVICE:ALIAS），或者仅指定服务名称。

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

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

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

笔记

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

  • 在（版本 3）以集群模式部署时，将忽略此选项 。

logging

服务的日志记录配置。

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

默认值为 json-file。

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

用options关键词为日志记录驱动程序指定日志记录选项。

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

默认驱动程序 json-file，有限制存储日志量的选项。因此，请使用键值对以设置最大存储大小和最大文件数：

上面显示的示例将存储日志文件，直到它们达到max-size200kB，然后分割它们。单个日志文件的存储量由该max-file值指定。随着日志超过最大限制，将删除较旧的日志文件以允许存储新日志。

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

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

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

网络模式（network_mode）

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

注意

网络

要加入的网络，参考 networks 关键词。

别名（ALIAES）

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

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

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

一般格式如下所示。

在下面的例子中，提供了三种服务（web，worker，和db），其中两个网络（new和legacy）。该db服务是在db或database的new网络，db与mysql在legacy网络。

IPV4_ADDRESS，IPV6_ADDRESS

加入网络后，为此服务的容器指定一个静态 IP 地址。

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

如果需要 IPv6 寻址，则enable_ipv6 设置该选项，并且必须使用 2.x 版本的 Compose 文件。 IPv6 选项当前在群集模式下不起作用。

一个例子：

pid

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

端口（ports）

暴露端口。

注意：端口映射与network_mode: host不兼容

短语法

要么指定两个端口（HOST:CONTAINER），要么仅指定容器端口（选择临时主机端口）。

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

长语法

长格式语法允许配置其他不能以短格式表示的字段。

  • target：容器内的端口

  • published：公开端口

  • protocol：端口协议（tcp或udp）

  • mode：host用于在每个节点上发布主机端口，或ingress使群集模式端口达到负载平衡。

注意：长语法是 v3.2 中的新增功能

重启（restart）

no是默认的重启策略，在任何情况下都不会重启容器。当always指定时，容器总是重新启动。 on-failure如果启动失败，则重启容器。

注意：在（版本3）以集群模式部署时，将忽略此选项 。请改用 restart_policy。

密钥（secrets）

授予每个服务对机密的访问权。 。支持两种不同的语法变量。

注意：密码必须已经存在或已 在secrets 文件的顶级配置中定义，否则部署失败。

有关密钥的更多信息，请参见密钥。

短语法

短语法变量仅指定密钥名称。这将授予容器访问密钥的权限，并将其挂载在在容器的/run/secrets/<secret_name> 。源名称和目标挂载点都设置为密钥名称。

以下示例使用短语法授予redis服务对my_secret和my_other_secret密钥的访问权限。值 my_secret设置为file的内容./my_secret.txt， my_other_secret定义为外部资源，这意味着它已经在 Docker中 定义，可以通过运行docker secret create 命令或通过其他部署方式进行定义。如果外部密钥不存在，则部署将失败并显示secret not found错误。

长语法

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

  • source：存在于 Docker 中密钥的名称。

  • target：在服务的容器/run/secrets/挂载的文件的名称。如果未指定，默认为source。

  • uid和gid：在服务的容器中拥有文件的数字 UID 或 GID 。如果未指定，则两者都默认为0。

  • mode：文件的权限以八进制表示。例如，0444 表示全部可读。Docker 1.13.1 中的默认值为0000，较新的版本采用0444。密钥信息不可写，因为它们已挂载在临时文件系统中，因此，如果设置可写位，它也将被忽略。可执行位可以设置。如果您不熟悉 UNIX 文件权限模式，可能会发现此 权限计算器 很有用。

下面的示例设置名称my_secret，在容器内命名redis_secret，模式为0440（组可读），并且将用户和组设置为103。该redis服务无权访问该my_other_secret 机密。

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

security_opt

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

注意：在（版本 3）以集群模式部署时，将忽略此选项 。

stop_grace_period

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

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

停止信号

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

sysctls

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

您只能使用内核中命名空间的 sysctls。 Docker 不支持在容器中更改 sysctls 而修改主机系统。 请参阅在运行时配置命名空间的内核参数（sysctls）。

在（版本 3）Compose文件以集群模式部署时，此选项需要Docker Engine 19.03或更高 版本。

tmpfs

版本 2 文件格式及更高版本。

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

在（版本 3-3.5）Compose文件以集群模式部署时，将忽略此选项 。

3.6 版文件格式及更高版本。

在容器内安装一个临时文件系统。Size 参数指定 tmpfs 安装的大小（以字节为单位）。默认情况下不受限制。

ulimits

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

userns_mode

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

在（版本 3）Compose文件以集群模式部署时，将忽略此选项 。

卷（volumes）

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

您可以将主机路径挂载为单个服务的定义的一部分，而无需在顶级volumes关键词中进行定义。

但是，如果要在多个服务之间重用卷，请在顶级volumes关键词中定义一个命名卷。将命名卷与服务，集群和文件一起使用。

注意：顶级卷定义了一个命名卷，并从每个服务的volumes列表中引用了该卷。这将替换volumes_from早期版本的 Compose 文件格式。有关卷的信息，请参见使用卷和卷插件。

这个例子显示了服务（web）正在使用的命名卷（mydata），以及为单个服务（db服务 下的第一个路径volumes）定义的绑定安装。该db服务还使用了一个名为dbdata（dbservice 下的第二个路径volumes）的命名卷，但是使用旧的字符串格式定义了该卷以挂载命名卷。volumes如图所示，必须在顶级键下列出命名的卷 。

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

短语法

在主机上指定路径（HOST:CONTAINER）或访问模式（HOST:CONTAINER:ro）。

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

长语法

长格式语法允许配置其他不能以短格式表示的字段。

  • type：类型volume，bind，tmpfs或npipe

  • source：挂载的源，主机上用于绑定挂载的路径或顶级volumes关键词中定义的卷的名称 。不适用于 tmpfs 挂载。

  • target：卷的容器中的路径

  • read_only：将卷设置为只读的标志

  • bind：配置其他绑定选项

    • propagation：用于绑定的模式

  • volume：配置其他卷选项

    • nocopy：创建卷时禁用从容器复制数据

  • tmpfs：配置其他 tmpfs 选项

    • size：tmpfs 挂载的大小（以字节为单位）

  • consistency：装载的一致性要求，consistent（主机和容器具有相同的视图），cached（读缓存，主机视图具有权威性）或delegated（读写缓存，容器的视图具有权威性）

注意：长语法是 v3.2 中的新增功能

服务，集群和 STACK 文件的卷

当使用服务、集群和 docke-stack.yml文件时，请记住，支持服务的任务(容器)可以部署在集群中的任何节点上，而且每次更新服务时可能是不同的节点。

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

如果要保留数据，请使用命名卷和支持多主机的卷驱动程序，以便可以从任何节点访问数据。或者，对服务设置约束，以便将其任务部署在具有该卷的节点上。

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

卷挂载的缓存选项（适用于 MAC 的 DOCKER 桌面）

在 Docker 17.04 CE Edge 及更高版本（包括 17.06 CE Edge 和 Stable）上，您可以在 Compose 文件中为绑定挂载的目录配置容器和主机的一致性要求，以提高卷的读/写性能。这些选项解决了osxfs文件共享所特有的问题，因此仅适用于 Mac 的 Docker Desktop。

这些标志是：

  • consistent：完全一致。容器运行时和主机始终保持相同的安装视图。这是默认值。

  • cached：主机对挂载的视图是权威的。在容器中可以看到主机上所做的更新，这可能会有所延迟。

  • delegated：容器运行时的挂载视图具有权威性。在主机上看到容器中所做的更新之前可能会有所延迟。

这是将卷配置为的示例cached：

有关这些标志，它们所解决的问题以及docker run与之对应的问题的完整详细信息，请 参见 Docker Desktop for Mac 主题“针对卷挂载（共享文件系统）的性能调整”。

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

每个标志都是一个值，类似于其 docker run 对应项。请注意，mac_address是一个旧选项。

指定持续时间

一些配置选项，例如interval和timeout子选项 check，将持续时间作为字符串以如下格式显示：

支持的单位是us，ms，s，m和h。

指定字节值

某些配置选项，例如的shm_size子选项 build，接受字节值通过字符格式，格式如下：

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

卷配置参考

虽然可以在服务声明中在文件上声明卷，但是本节允许您创建命名卷（不依赖volumes_from），这些卷可以在多个服务中重用，并且可以使用 docker 命令行或 API。有关更多信息，请参阅 docker volume子命令文档。

有关卷的信息，请参见使用卷和卷插件。

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

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

driver

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

driver_opts

指定选项列表，以传递给该卷的驱动程序。这些选项取决于驱动程序-有关更多信息，请参考驱动程序的文档。

external

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

3.3 和以下的版本，external 不能与其他卷配置键 （driver，driver_opts， labels）一起使用。对于 3.4 及更高版本，此限制不再存在 。

在下面的示例中，Compose 不会尝试创建一个名为[projectname]_data的卷，而是查找一个称为data的现有卷，并将其装入db服务的容器中。

不推荐 external.name，使用name来代替。

您还可以在 compose 文件中分别指定卷名和引用卷名的名称：

外部卷始终使用 docker stack deploy 创建

如果使用docker stack deploy以集群模式启动应用程序 （而不是 docker compose up），则会创建不存在的外部卷。在集群模式下，由服务定义卷后将自动创建该卷。由于服务任务是在新节点上安排的，因此 swarmkit在本地节点上创建卷。要了解更多信息，请参见 moby / moby＃29976。

labels

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

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

name

3.4 版文件格式添加

为此卷设置自定义名称。name 字段可用于引用包含特殊字符的卷。该名称按原样使用，不会与 stack 名称一起限定作用域。

它也可以与external属性一起使用：

网络配置参考

顶级networks关键词可让您指定要创建的网络。

drive

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

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

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

BRIDGE

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

OVERLAY

该overlay驱动程序创建一个跨多个节点命名的网络群。

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），然后使用该别名向该网络授予服务访问权限。

driver_opts

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

attachable

注意：仅 v3.2 和更高版本支持。

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

enable_ipv6

在此网络上启用 IPv6 网络。

文件版本 3 不支持

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

ipam

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

  • driver：自定义 IPAM 驱动程序，而不是默认驱动程序。

  • config：具有零个或多个配置块的列表，每个配置块包含以下任何关键词：

    • subnet：代表网段的 CIDR 格式的子网

一个完整的例子：

注意：目前gateway，仅适用于版本 2 的其他 IPAM 配置。

internal

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

labels

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

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

external

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

3.3 和更低格式的版本，external不可以（driver，driver_opts， ipam，internal）使用。对于 3.4 及更高版本，此限制不再存在 。

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

不推荐 external.name ，使用name来代替。

您还可以在文件中单独指定网络名称和用于引用网络的名称：

name

3.5 版文件格式添加

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

它也可以与external属性一起使用：

configs 配置参考

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

  • file：使用指定路径中的文件内容创建配置。

  • external：如果设置为 true，则指定此配置已创建。Docker 不会尝试创建它，如果它不存在， 则会发生config not found错误。

  • name：Docker 中配置对象的名称。此字段可用于引用包含特殊字符的配置。该名称按原样使用，不会与 stack 名称一起限定作用域。3.5 版文件格式引入。

在此示例中，my_first_config被创建（就像 _my_first_config)部署堆栈时一样，并且my_second_config已经存在于 Docker 中。）

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

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

secret 配置参考

顶级secrets声明定义或引用可以授予此 stack 中服务的配置。配置的来源是file或external。

  • file：使用指定路径中的文件内容创建配置。

  • external：如果设置为 true，则指定此配置已创建。Docker 不会尝试创建它，如果它不存在， 则会发生config not found错误。

  • name：Docker 中配置对象的名称。此字段可用于引用包含特殊字符的配置。该名称按原样使用，不会与 stack 名称一起限定作用域。3.5 版文件格式引入。

在此示例中，my_first_config被创建（就像 _my_first_config)部署堆栈时一样，并且my_second_config已经存在于 Docker 中。）

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

v3.5 及更高版本

v3.4 及以下版本

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

变量替代（Variable substitution）

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

当您运行docker-compose up这个配置，寻找 POSTGRES_VERSION环境变量的 shell 和替换其值。在这个例子中，在运行配置之前，解析image到postgres:9.3。

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

您可以使用 Compose 自动查找的.env文件为环境变量设置默认值 。在 shell 环境中设置的值将覆盖为.env文件中设置的值。

重要说明：该.env file功能仅在使用 docker-compose up命令时有效，而不能与一起使用docker stack deploy。

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

  • ${VARIABLE:-default}环境中VARIABLE是否未设置，如果为空，则值为default。

  • ${VARIABLE-default}仅VARIABLE在环境中未设置时值为default。

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

  • ${VARIABLE:?err} 如果环境中的变量未设置或为空，则使用包含err的错误消息退出。

  • ${VARIABLE?err} 如果环境中的变量未设置，则使用包含err的错误消息退出。

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

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

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

未设置 VAR_NOT_INTERPOLATED_BY_COMPOSE。替换为空字符串。

扩展字段

3.4 版文件格式添加。

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

注意

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

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

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

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

Compose 文件

PreviousDockerfile 参考Nextdocker-compose^1^

Last updated

Was this helpful?