# Compose 规范
[TOC]
## 文档状态
本文档指定用于定义多容器应用程序的Compose文件格式。本文档的分发是无限的。
本文档中的关键字“必须”，“不得”，“必须”，“应”，“应禁止”，“应”，“不应”，“推荐”，“可以”和“可选”是按照[RFC 2119中的](https://tools.ietf.org/html/rfc2119)描述进行解释。
### 要求和可选属性
Compose规范包括旨在面向本地[OCI](https://opencontainers.org/)容器运行时的属性，公开了Linux内核特定的配置选项，还包括一些Windows容器特定的属性，以及与群集上的资源放置，复制的应用程序分发和可伸缩性有关的云平台功能。
我们承认，预计不会有Compose实现支持**所有**属性，并且对某些属性的支持取决于平台，并且只能在运行时进行确认。用于控制Compose文件中受支持属性的版本化架构的定义（由设计了Compose文件格式的[docker-compose](https://github.com/docker/compose)工具建立）并未为最终用户属性提供任何保证。
该规范定义了预期的配置语法和行为，但是-除非另有说明-支持其中任何一个都是可选的。
使用不支持的属性来解析Compose文件的Compose实现应警告用户。我们建议实现者支持这些运行模式：
* 默认值：警告用户有关不支持的属性，但忽略它们
* 严格：警告用户有关不支持的属性，并拒绝撰写文件
* 宽松：忽略不受支持的属性和未知属性（在创建实现时规范尚未定义）
## Compose应用模型
Compose规范允许您定义一个与平台无关的基于容器的应用程序。这样的应用程序被设计为一组容器，它们必须与足够的共享资源和通信通道一起运行。
应用程序的计算组件被定义为`services`。服务是在平台上实现的抽象概念，通过一次或多次运行相同的容器映像（和配置）来实现。
服务通过`networks`相互通信。在本规范中，网络是一种平台功能抽象，用于在连接在一起的服务内的容器之间建立IP路由。低层的，特定于平台的网络选项被归入“网络”定义中，并且可以在某些平台上部分实现。
服务将持久性数据存储并共享到`volumes`。该规范将这种持久性数据描述为具有全局选项的高级文件系统挂载。特定于平台的实际实现细节被分组到Volumes定义中，并且可以在某些平台上部分实现。
某些服务需要依赖于运行时或平台的配置数据。为此，规范定义了一个专用概念：`configs`。从服务容器的角度来看，配置与卷具有可比性，因为它们是安装在容器中的文件。但是实际定义涉及不同的平台资源和服务，这些资源和服务由该类型抽象。
一个`secret`是配置数据的敏感数据不应该在没有安全方面的考虑会暴露一个特定的味道。密匙作为文件装入容器时可供服务使用，但是提供敏感数据的特定于平台的资源足够具体，值得在Compose规范中使用不同的概念和定义。
卷，配置和机密之间的区别允许实现在服务级别上提供可比的抽象，但涵盖适当平台资源的特定配置，以供充分确定的数据使用。
一个**项目**是一个平台上的应用程序规范的个体部署。项目的名称用于将资源分组在一起，并将它们与其他应用程序或具有不同参数的同一Compose指定应用程序的其他安装隔离。在平台上创建资源的Compose实现必须按项目在资源名称前添加前缀并设置标签`com.docker.compose.project`。
### 说明性的例子
以下示例通过一个具体的示例应用程序说明了Compose规范概念。该示例是非规范的。
考虑将应用程序分为前端Web应用程序和后端服务。
在运行时使用由基础结构管理的HTTP配置文件（提供外部域名）和由平台的安全机密存储注入的HTTPS服务器证书对运行时进行配置。
后端将数据存储在持久卷中。
两种服务都在隔离的后端网络上相互通信，而前端也连接到前端网络，并公开端口443供外部使用。
```
(External user) --> 443 [frontend network]
|
+--------------------+
| frontend service |...ro...<HTTP configuration>
| "webapp" |...ro...<server certificate> #secured
+--------------------+
|
[backend network]
|
+--------------------+
| backend service | r+w ___________________
| "database" |=======( persistent volume )
+--------------------+ \_________________/
```
该示例应用程序由以下部分组成：
* 2个服务，由Docker映像支持：`webapp`和`database`
* 1个秘密（HTTPS证书），已注入前端
* 1个配置（HTTP），注入到前端
* 1个永久卷，附加到后端
* 2个网络
```yml
services:
frontend:
image: awesome/webapp
ports:
- "443:8043"
networks:
- front-tier
- back-tier
configs:
- httpd-config
secrets:
- server-certificate
backend:
image: awesome/database
volumes:
- db-data:/etc/data
networks:
- back-tier
volumes:
db-data:
driver: flocker
driver_opts:
size: "10GiB"
configs:
httpd-config:
external: true
secrets:
server-certificate:
external: true
networks:
# The presence of these objects is sufficient to define them
front-tier: {}
back-tier: {}
```
此示例说明了卷，配置和机密之间的区别。尽管所有这些文件都作为已挂载的文件或目录公开给服务容器，但只能将一个卷配置为可读写访问。机密和配置是只读的。通过卷配置，您可以选择一个卷驱动程序并通过驱动程序选项来根据实际基础结构调整卷管理。Config和Secrets依赖于平台服务，并在`external`未作为应用程序生命周期的一部分进行管理的情况下进行声明：Compose实现将使用特定于平台的查找机制来检索运行时值。
## Compose文件
Compose文件是一个[YAML](http://yaml.org/)文件，用于定义`version`（已弃用），`services`（必需），`networks`,`volumes`,`configs`和`secrets`。Compose文件的默认路径是`compose.yaml`（首选）或`compose.yml`在工作目录中。撰写实现也应支持`docker-compose.yaml`并向`docker-compose.yml`后兼容。如果两个文件都存在，则Compose实现必须首选规范文件`compose.yaml`。
可以将多个Compose文件组合在一起以定义应用程序模型。YAML文件的组合必须通过根据用户设置的Compose文件顺序附加/覆盖YAML元素来实现。简单的属性和映射被最高顺序的Compose文件覆盖，列表通过追加合并。每当合并的互补文件托管在其他文件夹中时，相对路径都必须根据第**一个**Compose文件的父文件夹进行解析。
由于某些Compose文件元素都可以表示为单个字符串或复杂对象，因此合并必须应用于扩展形式。
### Profiles
配置文件允许针对各种用途和环境调整Compose应用程序模型。Compose实现应允许用户定义一组活动配置文件。确切的机制是特定于实现的，并且可以包括命令行标志，环境变量等。
“Services”顶级元素支持`profiles`用于定义命名配置文件列表的属性。`profiles`必须始终启用未设置属性的服务。如果列出`profiles`的服务与活动服务都不匹配，则该服务必须被Compose实现忽略，除非该服务由命令明确指定。在这种情况下，`profiles`必须将其添加到活动配置文件集中。所有其他顶级元素均不受其影响，`profiles`并且始终处于活动状态。
引用其他服务（通过`links`，`extends`或共享资源的语法`service:xxx`）不能自动启用，否则将被有效简忽视的组成部分。相反，Compose实现必须返回一个错误
#### 说明性的例子
```yaml
services:
foo:
image: foo
bar:
image: bar
profiles:
- test
baz:
image: baz
depends_on:
- bar
profiles:
- test
zot:
image: zot
depends_on:
- bar
profiles:
- debug
```
* 在没有启用配置文件的情况下分析的撰写应用程序模型仅包含`foo`服务。
* 如果`test`启用了概要文件，则模型包含服务`bar`，`baz`这些服务由`test`概要文件和`foo`始终启用的服务启用。
* 如果配置文件`debug`被启用，模型同时包含`foo`和`zot`服务，但不`bar`和`baz`，因此该模型无效有关`depends_on`的约束`zot`。
* 如果配置文件`debug`和`test`启用，模型包含了所有服务：`foo`，`bar`，`baz`和`zot`。
* 如果Compose实现是`bar`作为要运行的显式服务执行的，则`test`即使*用户*`test`未启用配置文件，配置文件也将处于活动状态。
* 如果Compose实现是`baz`作为要运行的显式服务执行的，则该服务`baz`和配置文件`test`将处于活动状态，`bar`并将被`depends_on`约束拉入。
* 如果`zot`使用要运行的显式服务执行Compose实现，则该模型对于since的`depends_on`约束将再次无效，并且没有列出任何共同点。`zot``zot``bar``profiles`
* 如果`zot`使用要运行的显式服务执行Compose实施并`test`启用了配置文件，则将`debug`自动启用配置文件，并且将服务`bar`作为启动服务`zot`和的依赖项引入`bar`。
## Version
`version`规范定义了顶级属性以实现向后兼容，但仅提供信息。
Compose实现不应使用此版本来选择用于验证Compose文件的确切模式，而应在设计时选择最新的模式。
Compose实现应验证它们可以完全解析Compose文件。如果某些字段未知，通常是因为Compose文件是用规范的较新版本定义的字段编写的，则Compose实现应警告用户。撰写实现可以提供忽略未知字段的选项（由“松散”模式定义）
## Services
服务是应用程序中计算资源的抽象定义，可以独立于其他组件进行缩放/替换。服务由一组容器支持，这些容器由平台根据复制要求和放置限制运行。由容器支持的服务由Docker映像和运行时参数集定义。使用这些参数完全创建服务中的所有容器。
组成文件必须将`services`根元素声明为映射，其键是服务名称的字符串表示形式，其值是服务定义。服务定义包含应用于该服务启动的每个容器的配置。
每个服务还可以包括一个Build部分，该部分定义了如何为该服务创建Docker镜像。组合实现可以支持使用该服务定义构建docker映像。如果未实现，则应忽略“build”部分，并且必须仍然认为“Compose”文件有效。
构建支持是Compose规范的可选方面，在[此](build.md)进行详细说明
每个服务定义运行时约束和要求以运行其容器。本`deploy`节对这些限制进行了分组，并允许平台调整部署策略，以最有效地满足容器与可用资源的需求。
部署支持是Compose规范的可选方面，在[此](deploy.md)进行详细描述。如果未实现，则应忽略“部署”部分，并且仍必须认为“Compose”文件有效。
### deploy
`deploy`指定服务的部署和生命周期的配置，定义[在这里](deploy.md)。
### blkio_config
`blkio_config` 定义了一组配置选项来设置此服务的块IO限制
```yml
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`：作为一个整数值，表示每秒允许的操作数。
#### weight
修改分配给该服务的带宽相对于其他服务的比例。取10到1000之间的整数值，默认值为500。
#### weight_device
根据设备微调带宽分配。列表中的每个项目都必须具有两个键：
* `path`：定义到受影响设备的符号路径。
* `weight`：介于10到1000之间的整数。
### cpu_count
`cpu_count` 定义服务容器可用的CPU数量。
### cpu_percent
`cpu_percent` 定义可用CPU的可用百分比。
### cpu_shares
`cpu_shares` 定义（作为整数值）服务容器相对于其他容器的相对CPU权重。
### cpu_period
`cpu_period`当平台基于Linux内核时，允许Compose实现配置CPU CFS（完全公平调度程序）期限。
### cpu_quota
`cpu_quota` 当平台基于Linux内核时，允许Compose实现配置CPU CFS（完全公平调度程序）配额
### cpu_rt_runtime
`cpu_rt_runtime`在支持实时调度程序的情况下为平台配置CPU分配参数。可以是以微秒为单位的整数值，也可以是**specifying-durations***。
```yml
cpu_rt_runtime: '400ms'
cpu_rt_runtime: 95000`
```
### cpu_rt_period
`cpu_rt_period` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either
an integer value using microseconds as unit or a [duration](#specifying-durations).
`cpu_rt_period`在支持实时调度程序的情况下为平台配置CPU分配参数。可以是以微秒为单位的整数值，也可以是**pecifying-durations***。
```yml
cpu_rt_period: '1400us'
cpu_rt_period: 11000`
```
### cpus
*弃用：使用[deploy.reservations.cpus](deploy.md)*
`cpus`定义要分配给服务容器的（潜在虚拟）CPU的数量。这是一个小数。`0.000`表示没有限制。
### cpuset
`cpuset`定义允许执行的显式CPU。可以是范围`0-3`或列表`0,1`
### build
`build`指定从源创建容器图象，限定的构建配置[这里](build.md)。
### cap_add
`cap_add`将其他容器[功能](http://man7.org/linux/man-pages/man7/capabilities.7.html)指定为字符串。
```
cap_add:
- ALL
```
### cap_drop
`cap_drop`指定要作为字符串删除的容器[功能](http://man7.org/linux/man-pages/man7/capabilities.7.html)。
```
cap_drop:
- NET_ADMIN
- SYS_ADMIN
```
### cgroup_parent
`cgroup_parent`指定容器的可选父[cgroup](http://man7.org/linux/man-pages/man7/cgroups.7.html)。
```
cgroup_parent: m-executor-abcd
```
### command
`command`覆盖容器镜像（即Dockerfile`CMD`）声明的默认命令。
```
command: bundle exec thin -p 3000
```
该命令也可以是列表，类似于[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd)：
```
command: [ "bundle", "exec", "thin", "-p", "3000" ]
```
### configs
`configs`使用每个服务的`configs`配置，基于每个服务授予对配置的访问权限。支持两种不同的语法变体。
如果平台上不存在配置或未在`configs`此Compose文件的部分中定义配置，则Compose实现必须报告错误。
为配置定义了两种语法。为了保持符合本规范，实现必须支持两种语法。实现必须允许在同一文档中使用短语法和长语法。
#### 短语法
简短的语法变体仅指定配置名称。这将授予容器对配置的访问权限，并将其安装在`/<config_name>`容器内。源名称和目标安装点都设置为配置名称。
以下示例使用短语法来授予`redis`服务对`my_config`和`my_other_config`配置的访问权限。的值`my_config`设置为file的内容`./my_config.txt`，并`my_other_config`定义为外部资源，这意味着它已在平台中定义。如果外部配置不存在，则部署必须失败。
```yml
services:
redis:
image: redis:latest
configs:
- my_config
configs:
my_config:
file: ./my_config.txt
my_other_config:
external: true
```
#### 长语法
长语法提供了在服务的任务容器中如何创建配置的更多粒度。
* `source`：平台中存在的配置名称。
* `target`：要在服务的任务容器中挂载的文件的路径和名称。`/<source>`如果未指定，则默认为。
* `uid`和`gid`：拥有服务的任务容器中已挂载的配置文件的数字UID或GID。未指定时的默认值为USER正在运行的容器。
* `mode`：服务的任务容器中装入的文件的[权限](http://permissions-calculator.org/)，以八进制表示法。默认值是世界可读的（`0444`）。可写位必须被忽略。可执行位可以设置。
下面的示例设置的名称`my_config`，以`redis_config`在容器内，将模式设定为`0440`（组可读），并且将所述用户和组`103`。该`redis`服务无权访问该`my_other_config`配置。
```yml
services:
redis:
image: redis:latest
configs:
- source: my_config
target: /redis_config
uid: "103"
gid: "103"
mode: 0440
configs:
my_config:
external: true
my_other_config:
external: true
```
您可以授予服务访问多个配置的权限，并且可以混合长短语法。
### container_name
`container_name`是一个字符串，它指定一个自定义容器名称，而不是生成的默认名称
```yml
container_name: my-web-container
```
如果Compose文件指定一个，则撰写实现不得将服务扩展到一个容器之外`container_name`。尝试这样做必须导致错误。
如果存在，`container_name`则应遵循以下内容的正则表达式格式：`[a-zA-Z0-9][a-zA-Z0-9_.-]+`
### credential_spec
`credential_spec`为托管服务帐户配置凭据规范。
组成支持使用Windows容器的服务的实现，必须支持credential\_spec`file:`和`registry:`协议。撰写实现还可以支持自定义用例的附加协议。
在`credential_spec`必须在格式`file://<filename>`或`registry://<value-name>`。
```yml
credential_spec:
file: my-credential-spec.json
```
使用时`registry:`，将从守护程序主机上的Windows注册表中读取凭据规范。具有给定名称的注册表值必须位于：
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
以下示例从`my-credential-spec`注册表中命名的值加载凭据规范：
```yml
credential_spec:
registry: my-credential-spec
```
#### gMSA凭据规范配置示例
为服务配置gMSA凭据规范时，您只需使用即可指定凭据规范`config`，如以下示例所示：
```yml
services:
myservice:
image: myimage:latest
credential_spec:
config: my_credential_spec
configs:
my_credentials_spec:
file: ./my-credential-spec.json|
```
### depends_on
`depends_on` 表示服务之间的启动和关闭依赖关系。
#### 短语法
简短的语法变体仅指定依赖项的服务名称。服务依赖项导致以下行为：
* Compose实现必须按依赖关系顺序创建服务。在以下示例中，在`web`之前创建`db`和`redis`。
* Compose实现必须按依赖关系顺序删除服务。在以下示例中，在`db`和`redis`删除之前将其`redis`删除。
简单的例子：
```yml
services:
web:
build: .
depends_on:
- db
- redis
redis:
image: redis
db:
image: postgres
```
Compose实现必须保证在启动依赖服务之前已经启动了依赖服务。Compose实现可以在启动依赖服务之前，等待依赖服务“ready”。
#### 长语法
长格式语法允许配置其他不能以短格式表示的字段。
* `condition`：满足依赖关系的条件
* `service_started`：等效于上述简短语法
* `service_healthy`：指定在启动依赖项服务之前，依赖项应为“healthy”状态（如**healthcheck**所示）。
* `service_completed_successfully`：指定在启动依赖项服务之前，期望依赖项可以成功完成。
服务依赖项导致以下行为：
* Compose实现必须按依赖关系顺序创建服务。在以下示例中，在`web`之前创建`db`和`redis`。
* Compose实现必须等待运行状况检查传递标记为的依赖项`service_healthy`。在下面的示例中，`db`在`web`创建之前应该是“healthy”的。
* Compose实现必须按依赖关系顺序删除服务。在以下示例中，在`redis`和`db`之前将其删除`web`。
简单的例子：
```yml
services:
web:
build: .
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
redis:
image: redis
db:
image: postgres
```
Compose实现必须保证在启动依赖服务之前已经启动了依赖服务。Compose实现必须确保`service_healthy`在启动依赖服务之前，标有的依赖服务是“healthy”。
### device_cgroup_rules
`device_cgroup_rules`定义此容器的设备cgroup规则列表。该格式与Linux内核在“[Control Groups Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html)“指定的格式相同。
```yml
device_cgroup_rules:
- 'c 1:3 mr'
- 'a 7:* rmw'
```
### devices
`devices`为创建的容器定义设备映射的列表。
```yml
devices:
- "/dev/ttyUSB0:/dev/ttyUSB0"
```
### dns
`dns`定义要在容器网络接口配置上设置的自定义DNS服务器。可以是单个值或列表。
```yml
dns: 8.8.8.8
```
```yml
dns:
- 8.8.8.8
- 9.9.9.9
```
### dns_opt
`dns_opt`列出要传递到容器的DNS解析器（`/etc/resolv.conf`Linux上的文件）的自定义DNS选项。
```yml
dns_opt:
- use-vc
- no-tld-query
```
### dns_search
`dns`定义要在容器网络接口配置上设置的自定义DNS搜索域。可以是单个值或列表。
```yml
dns_search: example.com
```
```yml
dns_search:
- dc1.example.com
- dc2.example.com
```
### domainname
`domainname`声明用于服务容器的自定义域名。必须是有效的RFC 1123主机名。
### entrypoint
`entrypoint`覆盖Docker映像的默认entrypoint（即`ENTRYPOINT`由Dockerfile设置）。当由Compose文件配置时，撰写实现必须清除Docker映像上的所有默认命令-`ENTRYPOINT`以及`CMD`Dockerfile中的指令`entrypoint`。如果[`command`](spec.md)还设置了if，则它将用作参数以`entrypoint`替换Docker映像的`CMD`
```yml
entrypoint: /code/entrypoint.sh
```
entrypoint也可以是列表，类似于[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd)：
```yml
entrypoint:
- php
- -d
- zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
- -d
- memory_limit=-1
- vendor/bin/phpunit
```
### env_file
`env_file`根据文件内容将环境变量添加到容器中。
```yml
env_file: .env
```
`env_file`也可以是列表。列表中的文件必须从上至下进行处理。对于在两个环境文件中指定的相同变量，列表中最后一个文件的值必须保留。
```yml
env_file:
- ./a.env
- ./b.env
```
相对路径必须从Compose文件的父文件夹中解析。由于绝对路径会阻止Compose文件的可移植性，因此当使用set路径时，Compose实现应向用户发出警告`env_file`。
在[环境](spec.md)(environment)部分声明的环境变量必须覆盖这些值–即使这些值是空的或未定义的，这也适用。
#### Env_file format
env文件中的每一行必须采用`VAR[=[VAL]]`格式。以开头开头的行`#`必须被忽略。空白行也必须被忽略。
值`VAL`用作原始字符串，根本没有修改。如果该值用引号引起来（shell变量通常是这种情况），则引号必须**包含**在传递给由Compose实现创建的容器的值中。
`VAL`可以省略，在这种情况下，变量值为空字符串。`=VAL`可以省略，在这种情况下，变量未**设置**。
```bash
# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"
```
### environment
`environment`定义在容器中设置的环境变量。`environment`可以使用数组或映射。任何布尔值；true，false，yes，no，必须用引号引起来，以确保YAML解析器不会将其转换为True或False。
环境变量可以由单个键声明（没有值等于符号）。在这种情况下，Compose实现应依靠某些用户交互来解决该值。如果未设置，则该变量未设置并且将从服务容器环境中删除。
键值语法：
```yml
environment:
RACK_ENV: development
SHOW: "true"
USER_INPUT:
```
数组语法:
```yml
environment:
- RACK_ENV=development
- SHOW=true
- USER_INPUT
```
为服务同时设置`env_file`和时，`environment`由设置的值`environment`具有优先权。
### expose
`expose`定义Compose实现必须从容器公开的端口。这些端口必须可供链接服务访问，并且不应发布到主机上。只能指定内部容器端口。
```yml
expose:
- "3000"
- "8000"
```
### extends
在当前文件或其他可选的覆盖配置中扩展另一个服务。您可以`extends`在任何服务上与其他配置键一起使用。该`extends`值必须是使用必需键`service`和可选`file`键定义的映射。
```yaml
extends:
file: common.yml
service: webapp
```
如果支持，则Compose实现必须`extends`以以下方式进行处理：
* `service`定义被引用为基础的服务的名称，例如`web`或`database`。
* `file`是定义该服务的Compose配置文件的位置。
#### Restrictions
以下限制适用于所引用的服务：
* 依赖于其他服务的服务不能用作基础。因此，任何引入对另一服务的依赖关系的密钥都不兼容`extends`。这样的键的非穷举的列表是：`links`，`volumes_from`，`container`模式（`ipc`，`pid`，`network_mode`和`net`），`service`模式（在`ipc`，`pid`和`network_mode`），`depends_on`。
* 服务不能使用以下方式的循环引用`extends`
在所有这些情况下，Compose实现都必须返回错误。
#### Finding referenced service
`file`值可以是：
* 不存在。这表明正在引用同一Compose文件中的另一个服务。
* 文件路径，可以是：
* 相对路径。该路径被认为是相对于主要Compose文件的位置而言的。
* 绝对路径。
`service`在所标识的引用的Compose文件中，必须存在以表示的服务。组合实现必须在以下情况下返回错误：
* `service`找不到由表示的服务
* `file`找不到由表示的撰写文件
#### Merging service definitions
必须以以下方式合并两个服务定义（当前Compose文件中的*主要*一个，并由所指定的一个*引用*`extends`）：
* 映射：*主*服务定义的映射中的键将覆盖*引用的*服务定义的映射中的键。未覆盖的键按原样包含。
* 序列：将项目组合在一起，形成一个新的序列。保留元素的顺序，其中*引用的*项目排在最前面，*主要的*项目排在后面。
* 标量：*主要*服务定义中的键优先于所*引用*键中的键
##### Mappings
下面的键应该被视为映射：`build.args`，`build.labels`，`build.extra_hosts`，`deploy.labels`，`deploy.update_config`，`deploy.rollback_config`，`deploy.restart_policy`，`deploy.resources.limits`，`environment`，`healthcheck`，`labels`，`logging.options`，`sysctls`，`storage_opt`，`extra_hosts`，`ulimits`。
适用的一个例外`healthcheck`是，除非*引用的*映射也指定了*主*映射，`disable: true`否则无法指定*主*映射。在这种情况下，Compose实现必须返回错误。`disable: true`
例如，下面的输入：
```yaml
services:
common:
image: busybox
environment:
TZ: utc
PORT: 80
cli:
extends:
service: common
environment:
PORT: 8080
```
为`cli`服务生成以下配置。如果使用数组语法，则会产生相同的输出。
```yaml
environment:
PORT: 8080
TZ: utc
image: busybox
```
下的项目`blkio_config.device_read_bps`，`blkio_config.device_read_iops`，`blkio_config.device_write_bps`，`blkio_config.device_write_iops`，`devices`和`volumes`也被视为映射，其中关键的是在容器内的目标路径。
例如，下面的输入：
```yaml
services:
common:
image: busybox
volumes:
- common-volume:/var/lib/backup/data:rw
cli:
extends:
service: common
volumes:
- cli-volume:/var/lib/backup/data:ro
```
为`cli`服务生成以下配置。请注意，现在装入的路径指向新的卷名，并且`ro`已应用标志。
```yaml
image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro
```
如果*引用的*服务定义包含`extends`映射，则将其下的项目简单地复制到新的*合并*定义中。然后再次开始合并过程，直到没有`extends`剩余键为止。
例如，下面的输入：
```yaml
services:
base:
image: busybox
user: root
common:
image: busybox
extends:
service: base
cli:
extends:
service: common
```
为`cli`服务生成以下配置。在这里，`cli`服务`user`从`common`服务中获取密钥，而服务又从服务中获取此密钥`base`。
```yaml
image: busybox
user: root
```
##### Sequences
以下键应被视为序列：`cap_add`，`cap_drop`，`configs`，`deploy.placement.constraints`，`deploy.placement.preferences`，`deploy.reservations.generic_resources`，`device_cgroup_rules`，`expose`，`external_links`，`ports`，`secrets`，`security_opt`。合并导致的所有重复项都将被删除，因此序列仅包含唯一元素。
例如，下面的输入：
```yaml
services:
common:
image: busybox
security_opt:
- label:role:ROLE
cli:
extends:
service: common
security_opt:
- label:user:USER
```
为`cli`服务生成以下配置。
```yaml
image: busybox
security_opt:
- label:role:ROLE
- label:user:USER
```
在使用情况下列表语法，下面的键也应被视为序列：`dns`，`dns_search`，`env_file`，`tmpfs`。与上述序列字段不同，不会删除合并产生的重复项。
##### Scalars
服务定义中任何其他允许的键都应视为标量。
### external_links
`external_links`将服务容器链接到此Compose应用程序外部管理的服务。`external_links`使用平台查找机制定义要检索的现有服务的名称。`SERVICE:ALIAS`可以指定表单的别名。
```yml
external_links:
- redis
- database:mysql
- database:postgresql
```
### extra_hosts
`extra_hosts`将主机名映射添加到容器网络接口配置（`/etc/hosts`对于Linux）。值必须以的形式设置其他主机的主机名和IP地址`HOSTNAME:IP`。
```yml
extra_hosts:
- "somehost:162.242.195.82"
- "otherhost:50.31.209.229"
```
Compose实现必须在容器的网络配置中创建具有IP地址和主机名的匹配条目，这意味着对于Linux，这`/etc/hosts`将获得额外的内容：
```
162.242.195.82 somehost
50.31.209.229 otherhost
```
### group_add
`group_add`指定容器内用户必须是其成员的其他组（按名称或编号）。
当多个容器（以不同用户身份运行）需要全部在一个共享卷上读取或写入同一文件时，这是一个有用的示例。该文件可以归所有容器共享的组所有，并在中指定`group_add`。
```yml
services:
myservice:
image: alpine
group_add:
- mail
```
`id`在创建的容器中运行必须显示该用户属于该`mail`组，如果`group_add`未声明，则不会是这种情况。
### healthcheck
`healthcheck`声明运行的检查以确定此服务的容器是否“healthy”。这将覆盖服务的Docker映像设置的[HEALTHCHECK Dockerfile指令](https://docs.docker.com/engine/reference/builder/#healthcheck)。
```yml
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 1m30s
timeout: 10s
retries: 3
start_period: 40s
```
`interval`，`timeout`和`start_period`被[指定为持续时间](spec.md)(specifying-durations)。
`test`定义Compose实现将运行以检查容器运行状况的命令。它可以是字符串或列表。如果它是一个列表，第一项必须是`NONE`，`CMD`或`CMD-SHELL`。如果是字符串，则等效于指定`CMD-SHELL`后跟该字符串。
```yml
# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]
```
using`CMD-SHELL`将使用容器的默认外壳程序（`/bin/sh`对于Linux）运行配置为字符串的命令。以下两种形式是等效的：
```yml
test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
```
```yml
test: curl -f https://localhost || exit 1
```
`NONE`禁用运行状况检查，并且在禁用按图像设置的运行状况检查时最有用。或者，可以通过设置禁用由图像设置的运行状况检查`disable: true`：
```yml
healthcheck:
disable: true
```
### hostname
`hostname`声明用于服务容器的自定义主机名。必须是有效的RFC 1123主机名。
### image
`image`指定从其开始容器的图像。图片必须遵循开放容器规范的[可寻址镜像格式](digests.md)，如`[<registry>/][<project>/]<image>[:<tag>|@<digest>]`。
```yml
image: redis
image: redis:5
image: redis@sha356:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
image: library/redis
image: docker.io/library/redis
image: my_private.registry:5000/redis
```
如果平台上不存在该映像，则Compose实现必须尝试基于来拉取它`pull_policy`。具有构建支持的组合实现可以为最终用户提供替代选项，以控制从源中拉出构建映像的优先级，但是拉出映像必须是默认行为。
`image`只要`build`声明了一个节，就可以从Compose文件中省略它。如果没有`image`Compose文件，缺少构建支持的Compos实施必须失败。
### init
`init`在容器内运行一个初始化进程（PID 1）以转发信号并获取进程。设置此选项可以`true`为服务启用此功能。
```yml
services:
web:
image: alpine:latest
init: true
```
使用的初始化二进制文件是特定于平台的。
### ipc
`ipc`配置服务容器设置的IPC隔离模式。可用的值是特定于平台的，但是Compose规范定义了特定的值，如果支持，则必须按照说明来实现：
* `shareable`这为容器提供了自己的私有IPC名称空间，并有可能与其他容器共享。
* `service:{name}`这使容器加入另一个（`shareable`）容器的IPC名称空间。
```yml
ipc: "shareable"
ipc: "service:[service name]"
```
### isolation
`isolation`指定容器的隔离技术。支持的值是特定于平台的。
### labels
`labels`将元数据添加到容器。您可以使用数组或映射。
建议您使用反向DNS表示法，以防止标签与其他软件使用的标签冲突。
```yml
labels:
com.example.description: "Accounting webapp"
com.example.department: "Finance"
com.example.label-with-empty-value: ""
```
```yml
labels:
- "com.example.description=Accounting webapp"
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
```
Compose实现必须创建带有规范标签的容器：
* `com.docker.compose.project`在由Compose实施创建的所有资源上设置为用户项目名称
* `com.docker.compose.service`在服务容器上设置服务名称，该名称在Compose文件中定义
该`com.docker.compose`标签的前缀被保留。在Compose文件中使用此前缀指定标签必须导致运行时错误。
### links
`links`定义到另一个服务中的容器的网络链接。既可以指定服务名称，也可以指定链接别名（`SERVICE:ALIAS`），也可以仅指定服务名称。
```yml
web:
links:
- db
- db:database
- redis
```
必须以与别名相同的主机名访问链接服务的容器，如果未指定别名，则必须以服务名访问。
不需要链接即可使服务进行通信-如果未设置特定的网络配置，则任何服务都必须能够以该服务的名称到达`default`网络上的任何其他服务。如果服务确实声明了它们所连接的网络，则`links`不应覆盖网络配置，并且未连接至共享网络的服务也将无法通信。Compose实现可能不会警告用户有关此配置不匹配的信息。
链接还以与[depends_on](spec.md)相同的方式表示服务之间的隐式依赖关系，因此它们确定了服务启动的顺序。
### logging
`logging`定义服务的日志记录配置。
```yml
logging:
driver: syslog
options:
syslog-address: "tcp://192.168.0.42:123"
```
该`driver`名称指定服务容器的日志记录驱动程序。默认值和可用值是特定于平台的。可以将特定于驱动程序的选项设置`options`为键值对。
### network_mode
`network_mode`设置服务容器网络模式。可用值是特定于平台的，但是Compose规范定义了特定值，如果受支持，则必须按照说明来实现：
* `none`禁用所有容器联网
* `host`这使容器可以原始访问主机的网络接口
* `bridge`桥接网络模式，可以隔离与主机的网络
* `service:{name}`这使容器只能访问指定的服务
```yml
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
```
### networks
`networks`定义服务容器所连接到的网络，并引用[顶级`networks`密钥](spec.md)(networks-top-level-element)下的条目。
```yml
services:
some-service:
networks:
- some-network
- other-network
```
#### aliases
`aliases`在网络上声明此服务的备用主机名。同一网络上的其他容器可以使用服务名称或此别名来连接到服务的容器之一。
由于`aliases`是网络范围的，因此同一服务在不同的网络上可以具有不同的别名。
> **注意**：网络范围内的别名可以由多个容器甚至多个服务共享。如果是这样，则不能保证名称解析到哪个容器。
通用格式如下所示：
```yml
services:
some-service:
networks:
some-network:
aliases:
- alias1
- alias3
other-network:
aliases:
- alias2
```
在下面的示例中，服务`frontend`将能够`backend`在主机名`backend`或网络`database`上访问该服务`back-tier`，并且服务`monitoring`将能够在网络或网络上访问相同的`backend`服务。`db``mysql``admin`
```yml
services:
frontend:
image: awesome/webapp
networks:
- front-tier
- back-tier
monitoring:
image: awesome/monitoring
networks:
- admin
backend:
image: awesome/backend
networks:
back-tier:
aliases:
- database
admin:
aliases:
- mysql
networks:
front-tier:
back-tier:
admin:
```
#### ipv4_address, ipv6_address
加入网络后，为此服务的容器指定一个静态IP地址。
[顶层网络部分中](spec.md)(networks)的相应网络配置必须具有一个`ipam`块，其中子网配置覆盖每个静态地址。
```yml
services:
frontend:
image: awesome/webapp
networks:
front-tier:
ipv4_address: 172.16.238.10
ipv6_address: 2001:3984:3989::10
networks:
front-tier:
ipam:
driver: default
config:
- subnet: "172.16.238.0/24"
- subnet: "2001:3984:3989::/64"
```
#### link_local_ips
`link_local_ips`指定链接本地IP的列表。本地链路IP是特殊IP，它们属于众所周知的子网，并且由运营商完全管理，通常取决于部署它们的体系结构。实现是特定于平台的。
例子：
```yaml
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
```
#### priority
`priority`指示Compose实施应以哪种顺序将服务的容器连接到其网络。如果未指定，则默认值为0。
在以下示例中，由于应用程序服务具有最高优先级，因此它首先连接到app_net_1。然后，它连接到app_net_3，然后连接到app_net_2，后者使用默认优先级值0。
```yaml
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:
```
### mac_address
`mac_address`设置服务容器的MAC地址。
### mem_limit
*弃用：使用[deploy.limits.memory](deploy.md)*
### mem_reservation
*弃用：使用[deploy.reservations.memory](deploy.md)*
### mem_swappiness
`mem_swappiness`定义为主机内核交换容器使用的匿名内存页面的百分比（0到100之间的值）。
* 值为0将关闭匿名页面交换。
* 值100会将所有匿名页面设置为可交换。
默认值是特定于平台的。
### memswap_limit
`memswap_limit`定义允许交换到磁盘的内存容器的数量。这是一个修饰符属性，仅在`memory`同时设置时才有意义。使用交换允许容器在耗尽所有可用内存后将多余的内存需求写入磁盘。经常将内存交换到磁盘的应用程序会降低性能。
* 如果`memswap_limit`设置为正整数，那么这两个`memory`和`memswap_limit`必须设定。`memswap_limit`表示可以使用的内存和交换总量，并`memory`控制非交换内存使用的总量。因此，如果`memory`\=“ 300m”和`memswap_limit`\=“ 1g”，则容器可以使用300m的内存和700m（1g-300m）的交换空间。
* 如果`memswap_limit`设置为0，则必须忽略该设置，并将该值视为未设置。
* 如果`memswap_limit`将设置为与相同的值`memory`，并且`memory`将其设置为正整数，则该容器无权进行交换。请参阅阻止容器使用交换。
* 如果`memswap_limit`未设置，并且`memory`已`memory`设置，那么如果主机容器配置了交换内存，则容器可以使用与设置一样多的交换。例如，如果未设置`memory`\=“ 300m”，`memswap_limit`则该容器总共可以使用600m的内存和交换空间。
* 如果`memswap_limit`将其显式设置为-1，则允许容器使用无限交换，最高不超过主机系统上可用的数量。
### oom_kill_disable
如果`oom_kill_disable`设置为true，则Compose实现必须配置平台，以便在内存不足时不会终止容器。
### oom_score_adj
`oom_score_adj`调整在发生内存不足的情况下容器要被平台杀死的优先级。值必须在\[-1000,1000\]范围内。
### pid
`pid`设置由Compose实现创建的容器的PID模式。支持的值是特定于平台的。
### pids_limit
`pids_limit`调整容器的PID限制。设置为-1表示无限制的PID。
```yml
pids_limit: 10
```
### platform
`platform`使用`os[/arch[/variant]]`语法定义将在其上运行此服务的目标平台容器。声明声明时，撰写实现必须使用此属性来确定将拉动映像的版本和/或在哪个平台上执行服务的构建。
```yml
platform: osx
platform: windows/amd64
platform: linux/arm64/v8
```
### ports
暴露容器端口。端口映射不得与之一起使用，`network_mode: host`否则必将导致运行时错误。
#### 短语法
简短语法是用逗号分隔的字符串，用于设置主机IP，主机端口和容器端口，格式如下：
`[HOST:]CONTAINER[/PROTOCOL]`在哪里：
* `HOST`是`[IP:](port | range)`
* `CONTAINER`是`port | range`
* `PROTOCOL`将端口限制为指定的协议。`tcp`和`udp`值由规范定义。Compose实现可以为特定于平台的协议名称提供支持。
主机IP（如果未设置）必须绑定到所有网络接口。端口可以是单个值或范围。主机和容器必须使用等效范围。
要么指定两个端口（`HOST:CONTAINER`），要么仅指定容器端口。在后一种情况下，Compose实现应自动分配任何未分配的主机端口。
`HOST:CONTAINER`应该始终将其指定为（带引号的）字符串，以避免与[yaml base-60 float](https://yaml.org/type/float.html)冲突。
例子：
```yml
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"
```
> **注意**：平台上可能不支持主机IP映射，在这种情况下，Compose实现应拒绝Compose文件，并且必须通知用户它们将忽略指定的主机IP。
#### 长语法
长格式语法允许配置其他不能以短格式表示的字段。
* `target`：集装箱港口
* `published`：公开端口
* `protocol`：端口协议（`tcp`或`udp`），未指定表示任何协议
* `mode`：`host`用于在每个节点上发布主机端口，或`ingress`用于负载平衡的端口。
```yml
ports:
- target: 80
published: 8080
protocol: tcp
mode: host
```
### privileged
`privileged`配置服务容器以提升的特权运行。支持和实际影响是特定于平台的。
### profiles
`profiles`定义要在其下启用的服务的命名配置文件列表。如果未设置，则始终启用服务。
如果存在，`profiles`则应遵循的正则表达式格式`[a-zA-Z0-9][a-zA-Z0-9_.-]+`。
### pull_policy
`pull_policy`定义Compose实现在开始提取图像时将做出的决定。可能的值为：
* `always`：撰写实现应始终从注册表中提取图像。
* `never`：撰写实现不应从注册表中提取映像，而应依赖平台缓存的映像。如果没有缓存的图像，则必须报告失败。
* `missing`：仅当平台缓存中不存在映像时，撰写实现才应拉取映像。对于没有构建支持的Compose实现，这应该是默认选项。`if_not_present`应该考虑该值的别名，以便向后兼容
* `build`：撰写实现应构建映像。撰写实现应重新构建映像（如果已存在）。
如果`pull_policy`和`build`都出现，则Compose实现应默认构建映像。撰写实现可以在工具链中覆盖此行为。
### read_only
`read_only`将服务容器配置为使用只读文件系统创建。
### restart
`restart`定义平台将在容器终止上应用的策略。
* `no`：默认的重启策略。在任何情况下都不重启容器。
* `always`：策略始终重新启动容器，直到将其移除。
* `on-failure`：如果退出代码指示错误，则策略将重新启动容器。
* `unless-stopped`：无论退出代码是什么，该策略都会重新启动容器，但是在停止或删除服务后，该策略将停止重新启动。
```yml
restart: "no"
restart: always
restart: on-failure
restart: unless-stopped
```
### runtime
`runtime`指定用于服务容器的运行时。
的值`runtime`特定于实现。例如，`runtime`可以是[OCI Runtime Spec的实现](implementations.md)的名称，例如“ runc”。
```yml
web:
image: busybox:latest
command: true
runtime: runc
```
### scale
-已弃用：使用[部署/副本](deploy.md)(replicas)_
`scale`指定要为此服务部署的默认容器数。
### secrets
`secrets`授予对每项服务根据[机密](https://github.com/compose-spec/compose-spec/blob/master/secrets)定义的敏感数据的访问权限。支持两种不同的语法变体：短语法和长语法。
如果机密在平台上不存在或未在`secrets`此Compose文件的部分中定义，则撰写实现必须报告错误。
#### 短语法
简短的语法变体仅指定秘密名称。这会授予容器对机密的访问权限，并将其以只读方式安装到`/run/secrets/<secret_name>`容器内。源名称和目标安装点都设置为机密名称。
下面的示例使用short语法向`frontend`服务授予对`server-certificate`机密的访问权限。的值`server-certificate`设置为文件的内容`./server.cert`。
```yml
services:
frontend:
image: awesome/webapp
secrets:
- server-certificate
secrets:
server-certificate:
file: ./server.cert
```
#### 长语法
长语法提供了在服务的容器中如何创建机密的更多粒度。
* `source`：机密存在于平台上的名称。
* `target`：要`/run/secrets/`在服务的任务容器中挂载的文件的名称。`source`如果未指定，则默认为。
* `uid`和`gid`：`/run/secrets/`在服务的任务容器中拥有文件的数字UID或GID。默认值为USER运行容器。
* `mode`：文件的[权限](http://permissions-calculator.org/)以`/run/secrets/`八进制表示法装入服务的任务容器中。默认值为世界可读的权限（模式`0444`）。如果设置了可写位，则必须将其忽略。可执行位可以设置。
以下示例将`server-certificate`秘密文件的名称设置为`server.crt`容器内的名称，将模式设置为`0440`（组可读），并将用户和组的名称设置为`103`。`server-certificate`秘密的价值由平台通过查找和秘密生命周期提供，而不由Compose实现直接管理。
```yml
services:
frontend:
image: awesome/webapp
secrets:
- source: server-certificate
target: server.cert
uid: "103"
gid: "103"
mode: 0440
secrets:
server-certificate:
external: true
```
服务可能被授予访问多个机密的权限。机密的长短语法可以在同一个Compose文件中使用。在顶级`secrets`MUTS中定义机密并不意味着授予对它的任何服务访问权限。这样的授予必须在服务规范中作为`secrets`服务元素是明确的。
### security_opt
`security_opt`覆盖每个容器的默认标签方案。
```yml
security_opt:
- label:user:USER
- label:role:ROLE
```
### shm_size
`shm_size`配置`/dev/shm`服务容器允许的共享内存（Linux上的分区）的大小。指定为[字节值](spec.md)(specifying-byte-values)。
### stdin_open
`stdin_open`将服务容器配置为与分配的标准输入一起运行。
### stop_grace_period
`stop_grace_period`指定[`stop_signal`](spec.md)在发送SIGKILL之前，如果Compose实现无法处理SIGTERM（或已使用指定的任何停止信号），则在尝试停止容器时，Compose实现必须等待多长时间。指定为[持续时间](spec.md)(specifying-durations)。
```yml
stop_grace_period: 1s
stop_grace_period: 1m30s
```
容器在发送SIGKILL之前退出的默认值为10秒。
### stop_signal
`stop_signal`定义Compose实现必须用于停止服务容器的信号。如果未设置的容器由Compose Implementation通过发送停止`SIGTERM`。
```yml
stop_signal: SIGUSR1
```
### storage_opt
`storage_opt`定义服务的存储驱动程序选项。
```yml
storage_opt:
size: '1G'
```
### sysctls
`sysctls`定义要在容器中设置的内核参数。`sysctls`可以使用数组或映射。
```yml
sysctls:
net.core.somaxconn: 1024
net.ipv4.tcp_syncookies: 0
```
```yml
sysctls:
- net.core.somaxconn=1024
- net.ipv4.tcp_syncookies=0
```
您只能使用内核中已命名空间的sysctls。Docker不支持更改也会修改主机系统的容器内的sysctls。有关受支持的sysctls的概述，请参阅[在运行时配置命名空间的内核参数（sysctls）](https://docs.docker.com/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime)。
### tmpfs
`tmpfs`在容器内安装一个临时文件系统。可以是单个值或列表。
```yml
tmpfs: /run
```
```yml
tmpfs:
- /run
- /tmp
```
### tty
`tty`配置服务容器使其与TTY一起运行。
### ulimits
`ulimits`覆盖容器的默认ulimit。将单个限制指定为整数，将软/硬限制指定为映射。
```yml
ulimits:
nproc: 65535
nofile:
soft: 20000
hard: 40000
```
### user
`user`覆盖用于运行容器进程的用户。默认是由映像设置的值（即Dockerfile`USER`），如果未设置，则为`root`。
### userns_mode
`userns_mode`设置服务的用户名称空间。支持的值是特定于平台的，并且可能取决于平台配置
```yml
userns_mode: "host"
```
### volumes
`volumes`定义必须由服务容器访问的装载主机路径或命名卷。
如果安装是主机路径，并且仅由单个服务使用，则可以将其声明为服务定义的一部分，而不是顶层`volumes`密钥。
要在多个服务之间重用卷，必须在[顶级`volumes`key中](spec.md)声明一个命名卷。
此示例显示了服务`backend`正在使用的命名卷`db-data`，以及为单个服务定义的绑定安装
```yml
services:
backend:
image: awesome/backend
volumes:
- type: volume
source: db-data
target: /data
volume:
nocopy: true
- type: bind
source: /var/run/postgres/postgres.sock
target: /var/run/postgres/postgres.sock
volumes:
db-data:
```
#### 短语法
简短语法使用带有逗号分隔值的单个字符串来指定卷装载（`VOLUME:CONTAINER_PATH`）或访问模式（`VOLUME:CONTAINER:ACCESS_MODE`）。
`VOLUME`可以是平台上托管容器（绑定安装）的主机路径，也可以是卷名称。`ACCESS_MODE`可以使用设置为只读，`ro`或者使用`rw`设置读写（默认）。
> **注意**：相对主机路径必须仅由部署到本地容器运行时的Compose实现支持。这是因为相对路径是从Compose文件的父目录解析的，该父目录仅在本地情况下适用。部署到非本地平台的撰写实现必须拒绝使用错误的使用相对主机路径的撰写文件。为了避免命名卷含糊不清，相对路径应始终以`.`或开头`..`。
#### 长语法
长格式语法允许配置其他不能以短格式表示的字段。
* `type`：所述安装型`volume`，`bind`，`tmpfs`或`npipe`
* `source`：安装源，绑定安装在主机上的路径或[顶级`volumes`密钥中](spec.md)定义的卷的名称。不适用于tmpfs挂载。
* `target`：安装了卷的容器中的路径
* `read_only`：将卷设置为只读的标志
* `bind`：配置其他绑定选项
* `propagation`：用于绑定的传播模式
* `volume`：配置其他音量选项
* `nocopy`：标志，用于在创建卷时禁用从容器中复制数据
* `tmpfs`：配置其他tmpfs选项
* `size`：tmpfs挂载的大小（以字节为单位）
* `consistency`：安装座的一致性要求。可用值是特定于平台的
### volumes_from
`volumes_from`从另一个服务或容器安装所有卷，可以选择指定只读访问（ro）或读写（rw）。如果未指定访问级别，则必须使用读写。
字符串值在Compose应用程序模型中定义了另一个要从中装入卷的服务。该`container:`前缀，如果支持的话，允许从不是由撰写实现管理的容器装入卷。
```yaml
volumes_from:
- service_name
- service_name:ro
- container:container_name
- container:container_name:rw
```
### working_dir
`working_dir`从图像指定的目录（即Dockerfile`WORKDIR`）覆盖容器的工作目录。
## Networks top-level element
网络是允许服务相互通信的层。公开给服务的网络模型仅限于与目标服务和外部资源的简单IP连接，而网络定义允许微调平台提供的实际实现。
可以通过在顶级`networks`区域下指定网络名称来创建网络。服务可以通过在服务[`networks`](https://github.com/compose-spec/compose-spec/blob/master/spec.md#networks)小节下指定网络名称来连接到网络
在下面的示例中，将在运行时创建网络`front-tier`和`back-tier`，并将`frontend`服务连接到`front-tier`网络和`back-tier`网络。
```yml
services:
frontend:
image: awesome/webapp
networks:
- front-tier
- back-tier
networks:
front-tier:
back-tier:
```
### driver
`driver`指定该网络应使用哪个驱动程序。如果驱动程序在平台上不可用，则Compose实现必须返回错误。
```yml
driver: overlay
```
默认值和可用值是特定于平台的。Compose规范必须支持以下特定驱动程序：`none`和`host`
* `host`使用主机的网络堆栈
* `none`禁用网络
#### host or none
使用内置网络（例如`host`和`none`）的语法是不同的，因为此类网络隐式存在于Compose实现的范围之外。要使用它们，必须使用Compose实现可以使用的名称`host`或`none`别名定义一个外部网络（`hostnet`或`nonet`在以下示例中），然后使用其别名向该网络授予服务访问权限。
```yml
services:
web:
networks:
hostnet: {}
networks:
hostnet:
external: true
name: host
```
```yml
services:
web:
...
networks:
nonet: {}
networks:
nonet:
external: true
name: none
```
### driver_opts
`driver_opts`指定选项列表作为键值对，以传递给该网络的驱动程序。这些选项取决于驱动程序-有关更多信息，请参考驱动程序的文档。可选的。
```yml
driver_opts:
foo: "bar"
baz: 1
```
### attachable
如果`attachable`设置为`true`，则除了服务之外，独立容器还应该能够连接到该网络。如果独立容器连接到网络，则它可以与也连接到网络的服务和其他独立容器进行通信。
```yml
networks:
mynet1:
driver: overlay
attachable: true
```
### enable_ipv6
`enable_ipv6`在该网络上启用IPv6网络。
### ipam
`ipam`指定自定义IPAM配置。这是一个具有多个属性的对象，每个属性都是可选的：
* `driver`：自定义IPAM驱动程序，而不是默认驱动程序。
* `config`：具有零个或多个配置元素的列表，每个元素包含：
* `subnet`：代表网段的CIDR格式的子网
* `ip_range`：从中分配容器IP的IP范围
* `gateway`：主子网的IPv4或IPv6网关
* `aux_addresses`：网络驱动程序使用的辅助IPv4或IPv6地址，作为从主机名到IP的映射
* `options`：特定于驱动程序的选项作为键值映射。
一个完整的例子：
```yml
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"
```
### internal
默认情况下，撰写实现必须提供与网络的外部连接。`internal`设置为`true`允许创建外部隔离的网络时。
### labels
使用标签将元数据添加到容器。可以使用数组或字典。
用户应使用反向DNS表示法，以防止标签与其他软件使用的标签冲突。
```yml
labels:
com.example.description: "Financial transaction network"
com.example.department: "Finance"
com.example.label-with-empty-value: ""
```
```yml
labels:
- "com.example.description=Financial transaction network"
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
```
Compose实现必须设置`com.docker.compose.project`并`com.docker.compose.network`标记。
### external
如果设置为`true`，则`external`指定该网络的生命周期保持在应用程序之外。Compose实现不应尝试创建这些网络，如果不存在，则会引发错误。
在下面的示例中，`proxy`是通往外界的门户。代替尝试创建网络，Compose实现应该询问简单调用的现有网络的平台`outside`，并将`proxy`服务的容器连接到该平台。
```yml
services:
proxy:
image: awesome/proxy
networks:
- outside
- default
app:
image: awesome/app
networks:
- default
networks:
outside:
external: true
```
### name
`name`设置此网络的自定义名称。名称字段可用于引用包含特殊字符的网络。该名称按原样使用，**不会**与项目名称一起作用域。
```yml
networks:
network1:
name: my-app-net
```
它也可以与该`external`属性一起使用，以定义Compose实现应检索的平台网络，通常是通过使用一个参数，这样Compose文件不需要对运行时特定的值进行硬编码：
```yml
networks:
network1:
external: true
name: "${NETWORK_ID}"
```
## Volumes top-level element
卷是平台实现的永久数据存储。Compose规范为安装卷的服务和配置参数（在基础结构上分配它们）提供了中立的抽象。
本`volumes`部分允许配置可在多个服务之间重用的命名卷。这是两种服务设置的示例，其中数据库的数据目录作为卷与另一服务共享，以便可以定期备份它：
```yml
services:
backend:
image: awesome/database
volumes:
- db-data:/etc/data
backup:
image: backup-service
volumes:
- db-data:/var/lib/backup/data
volumes:
db-data:
```
顶级`volumes`密钥下的条目可以为空，在这种情况下，它将使用平台的默认配置来创建卷。（可选）您可以使用以下键对其进行配置：
### driver
指定该卷应使用哪个卷驱动程序。默认值和可用值是特定于平台的。如果驱动程序不可用，则Compose实现必须返回错误并停止应用程序部署。
```yml
driver: foobar
```
### driver_opts
`driver_opts`指定选项列表作为键值对传递给该卷的驱动程序。这些选项取决于驱动程序。
```yml
volumes:
example:
driver_opts:
type: "nfs"
o: "addr=10.40.0.199,nolock,soft,rw"
device: ":/docker/example"
```
### external
如果设置为`true`，则`external`指定该卷已在平台上存在，并且其生命周期在应用程序的生命周期之外进行管理。组合实现不得尝试创建这些卷，并且如果不存在，则必须返回错误。
在下面的示例中，Compose不会尝试创建一个名为`{project_name}_data`的卷，而是查找一个简单称为的现有卷`data`并将其装入`db`服务的容器中。
```yml
services:
backend:
image: awesome/database
volumes:
- db-data:/etc/data
volumes:
db-data:
external: true
```
### labels
`labels`用于将元数据添加到卷。您可以使用数组或字典。
建议您使用反向DNS表示法，以防止标签与其他软件使用的标签冲突。
```yml
labels:
com.example.description: "Database volume"
com.example.department: "IT/Ops"
com.example.label-with-empty-value: ""
```
```yml
labels:
- "com.example.description=Database volume"
- "com.example.department=IT/Ops"
- "com.example.label-with-empty-value"
```
Compose实现必须设置`com.docker.compose.project`并`com.docker.compose.volume`标记。
### name
`name`为此卷设置一个自定义名称。名称字段可用于引用包含特殊字符的卷。该名称按原样使用，**不会**与堆栈名称一起作用域。
```yml
volumes:
data:
name: "my-app-data"
```
它也可以与该`external`属性结合使用。为此，用于在平台上查找实际卷的卷的名称与用于在Compose文件中引用该卷的名称是分开设置的：
```yml
volumes:
db-data:
external:
name: actual-name-of-volume
```
这样就可以使此查找名称成为Compose文件的参数，以便对卷的模型ID进行硬编码，但在部署期间在运行时设置平台上的实际卷ID：
```yml
volumes:
db-data:
external:
name: ${DATABASE_VOLUME}
```
## Configs top-level element
通过配置，服务无需重新构建Docker映像即可适应其行为。从服务的角度来看，配置可与卷媲美，因为它们被安装到服务的容器文件系统中。可以从Configuration定义中设置平台提供的用于获取配置的实际实现细节。
授予对配置的访问权限后，该配置内容将作为文件安装在容器中。容器中安装点的位置默认为`/<config-name>`Linux容器和`C:\<config-name>`Windows容器中的位置。
默认情况下，配置必须由运行container命令的用户所有，但可以被服务配置覆盖。默认情况下，除非服务被配置为覆盖此配置，否则该配置必须具有世界可读的权限（模式0444）。
服务仅在由[`configs`](spec.md)小节明确授予时才能访问配置。
顶级`configs`声明定义或引用可以授予此应用程序中的服务的配置数据。配置的来源是`file`或`external`。
* `file`：使用指定路径中的文件内容创建配置。
* `external`：如果设置为true，则指定此配置已创建。撰写实现不会尝试创建它，如果它不存在，则会发生错误。
* `name`：要查找的平台上的配置对象的名称。该字段可用于引用包含特殊字符的配置。该名称按原样使用，**不会**与项目名称一起作用域。
在此示例中，`http_config`是在`<project_name>_http_config`部署应用程序时创建的（如），并且`my_second_config`必须已存在于Platform上，并且将通过查找获得价值。
在此示例中，通过将as的内容注册为配置数据来在部署应用程序时`server-http_config`创建。`<project_name>_http_config``httpd.conf`
```yml
configs:
http_config:
file: ./httpd.conf
```
或者，`http_config`可以声明为外部，这样Compose实现将查找`server-certificate`以将配置数据公开给相关服务。
```yml
configs:
http_config:
external: true
```
外部配置查找还可以通过指定来使用唯一键`name`。以下示例将上一个示例修改为使用parameter来查找config`HTTP_CONFIG_KEY`。这样做将在部署时通过对变量进行[插值](spec.md)(interpolation)来设置实际的查找关键字，但会将其作为硬编码ID公开给容器`http_config`。
```yml
configs:
http_config:
external: true
name: "${HTTP_CONFIG_KEY}"
```
Compose文件需要向应用程序中的相关服务显式授予对配置的访问权限。
## Secrets top-level element
密钥是Configs的一种风格，它专注于敏感数据，对此用法有特定的限制。由于平台的实现可能与Configs明显不同，因此专用的Secrets部分允许配置相关资源。
顶级`secrets`声明定义或引用可以授予此应用程序中的服务的敏感数据。秘密的来源是`file`或`external`。
* `file`：秘密是使用指定路径中的文件内容创建的。
* `external`：如果设置为true，则指定此机密已创建。撰写实现不会尝试创建它，如果它不存在，则会发生错误。
* `name`：Docker中的秘密对象的名称。此字段可用于引用包含特殊字符的机密。该名称按原样使用，**不会**与项目名称一起作用域。
在此示例中，通过将内容注册为平台机密，在部署应用程序时`server-certificate`创建。`<project_name>_server-certificate``server.cert`
```yml
secrets:
server-certificate:
file: ./server.cert
```
或者，`server-certificate`可以声明为外部，这样Compose实现将查找`server-certificate`以将秘密公开给相关服务。
```yml
secrets:
server-certificate:
external: true
```
外部机密查找还可以通过指定来使用不同的密钥`name`。以下示例修改了上一个示例，以使用参数查找秘密`CERTIFICATE_KEY`。这样做将在部署时通过对变量进行[插值](spec.md)(interpolation)来设置实际的查找关键字，但会将其作为硬编码ID公开给容器`server-certificate`。
```yml
secrets:
server-certificate:
external: true
name: "${CERTIFICATE_KEY}"
```
Compose文件需要显式授予对应用程序中相关服务的机密的访问权限。
## Fragments
可以使用[YAML锚点](http://www.yaml.org/spec/1.2/spec.html#id2765878)重用配置片段。
```yml
volumes:
db-data: &default-volume
driver: default
metrics: *default-volume
```
在先前的示例中，基于体积规范创建了一个*锚点*。以后，它会被*别名*重用以定义卷。相同的逻辑可以应用于Compose文件中的任何元素。锚定解析必须在[变量插值](spec.md)(interpolation)之前进行，因此变量不能用于设置锚定或别名。`default-volume``db-data``*default-volume``metrics`
也可以使用[YAML合并类型](http://yaml.org/type/merge.html)部分覆盖由锚引用设置的值。在以下示例中，`metrics`卷规范使用别名来避免重复，但会覆盖`name`属性：
```yml
services:
backend:
image: awesome/database
volumes:
- db-data
- metrics
volumes:
db-data: &default-volume
driver: default
name: "data"
metrics:
<<: *default-volume
name: "metrics"
```
## Extension
特殊扩展名字段的名称可以以`x-`字符序列开头，可以采用任何格式。它们可以在Compose文件的任何结构中使用。这是Compose实现以静默方式忽略无法识别的字段的唯一例外。
```yml
x-custom:
foo:
- bar
- zot
services:
webapp:
image: awesome/webapp
x-foo: bar
```
此类字段的内容未由Compose规范指定，可用于启用自定义功能。遇到未知扩展字段的组合实现绝不能失败，但是可以警告未知字段。
对于平台扩展，强烈建议使用平台/供应商名称作为扩展名的前缀，就像浏览器添加对[自定义CSS功能的](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)支持一样
```yml
service:
backend:
deploy:
placement:
x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
x-aws-region: "eu-west-3"
x-azure-region: "france-central"
```
### Informative Historical Notes
本节内容丰富。在Compose本文时，已知存在以下前缀：
| prefix | vendor/organization |
| ---------- | ------------------- |
| docker | Docker |
| kubernetes | Kubernetes |
### Using extensions as fragments
借助对扩展字段的支持，可以如下编写Compose文件，以提高重用片段的可读性：
```yml
x-logging: &default-logging
options:
max-size: "12m"
max-file: "5"
driver: json-file
services:
frontend:
image: awesome/webapp
logging: *default-logging
backend:
image: awesome/database
logging: *default-logging
```
### specifying byte values
值表示一个字节的值作为一个字符串`{amount}{byte unit}`格式：支持的单位是`b`（字节），`k`或`kb`（千字节），`m`或`mb`（兆字节）和`g`或`gb`（千兆字节）。
```
2b
1024kb
2048k
300m
1gb
```
### specifying durations
值以形式将持续时间表示为字符串`{value}{unit}`。支持的单位是`us`（微秒），`ms`（毫秒），`s`（秒），`m`（分钟）和`h`（小时）。值可以合并多个值，并且可以不带分隔符地使用。
```
10ms
40s
1m30s
1h5m30s20ms
```
## Interpolation
可以通过变量设置Compose文件中的值，并在运行时进行插值。撰写文件使用类似Bash的语法`${VARIABLE}`
这两个`$VARIABLE`和`${VARIABLE}`语法的支持。可以使用典型的Shell语法内联定义默认值：Latest
* `${VARIABLE:-default}`计算环境中`default`是否`VARIABLE`未设置或为空。
* `${VARIABLE-default}``default`仅`VARIABLE`在环境中未设置时评估为。
同样，以下语法允许您指定必需变量：
* `${VARIABLE:?err}`退出，并显示一条错误消息，其中包含在环境中`err`是否`VARIABLE`设置为if或为空。
* `${VARIABLE?err}`退出并显示错误消息，其中包含在环境中未设置`err`if的信息`VARIABLE`。
`${VARIABLE/foo/bar}`Compose规范不支持其他扩展的Shell样式功能，例如。
`$$`当您的配置需要文字美元符号时，可以使用（双美元符号）。这也可以防止Compose插值，因此a`$$`允许您引用您不想由Compose处理的环境变量。
```yml
web:
build: .
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
```
如果Compose实现无法解析替换变量，并且未定义默认值，则它必须警告用户并将变量替换为空字符串。
由于可以使用变量替换对Compose文件中的任何值进行插值，包括复杂元素的紧凑字符串表示法，因此必须在基于每个文件合并*之前*应用插值。
