服务顶级元素

服务是应用程序中计算资源的抽象定义，可以独立于其他组件进行扩展或替换。服务由一组容器支持，这些容器由平台根据复制要求和放置约束运行。由于服务由容器支持，因此它们由 Docker 镜像和一组运行时参数定义。服务中的所有容器都使用这些参数以相同的方式创建。

Compose 文件必须声明一个services顶级元素作为映射，其键是服务名称的字符串表示形式，其值是服务定义。服务定义包含应用于每个服务容器的配置。

每个服务也可以包含一个build部分，该部分定义如何创建服务的 Docker 镜像。Compose 支持使用此服务定义构建 Docker 镜像。如果未使用，则build部分将被忽略，Compose 文件仍被视为有效。构建支持是 Compose 规范的可选方面，在Compose 构建规范文档中进行了详细描述。

每个服务定义运行时约束和要求以运行其容器。deploy部分对这些约束进行分组，并允许平台调整部署策略以最佳方式匹配容器的需求和可用资源。部署支持是 Compose 规范的可选方面，在Compose 部署规范文档中进行了详细描述。如果未实现，则deploy部分将被忽略，Compose 文件仍被视为有效。

属性

annotations

annotations定义容器的注释。annotations可以使用数组或映射。

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

attach

在 Docker Compose 版本2.20.0中引入

当attach被定义并设置为false时，Compose 不会收集服务日志，除非你明确要求它。

默认服务配置是attach: true。

build

build指定从源代码创建容器镜像的构建配置，如Compose 构建规范中定义。

blkio_config

blkio_config定义一组配置选项，用于设置服务的块 IO 限制。

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_shares

cpu_shares定义服务容器相对于其他容器的相对 CPU 权重，以整数形式表示。

cpu_period

cpu_period在平台基于 Linux 内核时配置 CPU CFS（完全公平调度程序）周期。

cpu_quota

cpu_quota在平台基于 Linux 内核时配置 CPU CFS（完全公平调度程序）配额。

cpu_rt_runtime

cpu_rt_runtime为支持实时调度程序的平台配置 CPU 分配参数。它可以是使用微秒作为单位的整数，也可以是持续时间。

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: 95000`

cpu_rt_period

cpu_rt_period为支持实时调度程序的平台配置 CPU 分配参数。它可以是使用微秒作为单位的整数，也可以是持续时间。

 cpu_rt_period: '1400us'
 cpu_rt_period: 11000`

cpus

cpus定义分配给服务容器的（可能是虚拟的）CPU 数量。这是一个小数。0.000 表示没有限制。

当设置cpus时，它必须与部署规范中的cpus属性一致。

cpuset

cpuset定义允许执行的显式 CPU。可以是范围0-3或列表0,1

cap_add

cap_add指定额外的容器功能作为字符串。

cap_add:
  - ALL

cap_drop

cap_drop指定容器功能作为字符串。

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

在 Docker Compose 版本2.15.0中引入

cgroup指定要加入的 cgroup 命名空间。未设置时，容器运行时将决定选择哪个 cgroup 命名空间（如果支持）。

host：在容器运行时 cgroup 命名空间中运行容器。
private：在容器的私有 cgroup 命名空间中运行容器。

cgroup_parent

cgroup_parent指定容器的可选父cgroup。

cgroup_parent: m-executor-abcd

command

command覆盖容器镜像声明的默认命令，例如 Dockerfile 的CMD。

command: bundle exec thin -p 3000

该值也可以是列表，方式类似于Dockerfile

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

如果该值为null，则使用镜像的默认命令。

如果该值为[]（空列表）或''（空字符串），则忽略镜像声明的默认命令，即被覆盖为空。

configs

配置允许服务在无需重新构建 Docker 镜像的情况下调整其行为。服务只能在configs属性明确授予权限时才能访问配置。支持两种不同的语法变体。

如果config在平台上不存在或未在 Compose 文件的configs顶级元素中定义，Compose 会报告错误。

为配置定义了两种语法：简短语法和长语法。

您可以授予服务对多个配置的访问权限，并且可以混合使用长语法和短语法。

简短语法

简短语法变体只指定配置名称。这授予容器对配置的访问权限，并将它作为文件挂载到服务的容器文件系统中。挂载点在容器内的位置默认在 Linux 容器中为/<config_name>，在 Windows 容器中为C:\<config-name>。

以下示例使用简短语法来授予redis服务对my_config和my_other_config配置的访问权限。my_config的值设置为文件./my_config.txt的内容，my_other_config被定义为外部资源，这意味着它已经在平台中定义。如果外部配置不存在，则部署将失败。

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

长语法

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

source：配置在平台中存在的名称。
target：要挂载到服务的任务容器中的文件路径和名称。如果未指定，则默认为/<source>。
uid和gid：在服务的任务容器中拥有已挂载的配置文件的数字 UID 或 GID。未指定时的默认值是运行容器的 USER。
mode：在服务的任务容器中挂载的文件的权限，以八进制表示。默认值为世界可读（0444）。可写位必须被忽略。可执行位可以设置。

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

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是一个字符串，它指定自定义容器名称，而不是默认生成的名称。

container_name: my-web-container

如果 Compose 文件指定了container_name，Compose 不会将服务扩展到一个容器之外。尝试这样做会导致错误。

container_name 遵循 [a-zA-Z0-9][a-zA-Z0-9_.-]+ 的正则表达式格式。

credential_spec

credential_spec 配置托管服务帐户的凭据规范。

如果您有使用 Windows 容器的服务，则可以对 credential_spec 使用 file: 和 registry: 协议。Compose 还支持针对自定义用例的附加协议。

credential_spec 必须采用 file://<filename> 或 registry://<value-name> 格式。

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

gMSA 配置示例

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

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 按照依赖项顺序创建服务。在以下示例中，db 和 redis 在 web 之前创建。
Compose 按照依赖项顺序删除服务。在以下示例中，web 在 db 和 redis 之前删除。

简单示例

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Compose 保证在启动依赖服务之前启动依赖服务。Compose 会等待依赖服务“就绪”，然后再启动依赖服务。

长语法

长格式语法支持配置简短格式无法表达的附加字段。

restart：当设置为 true 时，Compose 会在更新依赖服务后重启此服务。这适用于由 Compose 操作控制的显式重启，不包括容器在死机后由容器运行时自动重启。在 Docker Compose 版本 2.17.0 中引入。
condition：设置依赖项被认为已满足的条件
- service_started：相当于上述简短语法
- service_healthy：指定依赖项应在启动依赖服务之前“健康”（如健康检查所示）。
- service_completed_successfully：指定依赖项应在启动依赖服务之前成功完成运行。
required：当设置为 false 时，Compose 只会在依赖服务未启动或不可用时发出警告。如果未定义，required 的默认值为 true。在 Docker Compose 版本 2.20.0 中引入。

服务依赖项会导致以下行为

Compose 按照依赖项顺序创建服务。在以下示例中，db 和 redis 在 web 之前创建。
Compose 会等待标记为 service_healthy 的依赖项上的健康检查通过。在以下示例中，预计 db 在创建 web 之前是“健康的”。
Compose 按照依赖项顺序删除服务。在以下示例中，web 在 db 和 redis 之前删除。

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres

Compose 保证在启动依赖服务之前启动依赖服务。Compose 保证标记为 service_healthy 的依赖服务在启动依赖服务之前是“健康的”。

deploy

deploy 指定服务的部署和生命周期的配置，如 Compose 部署规范中所定义。

develop

在 Docker Compose 版本 2.22.0 中引入

develop 指定用于将容器与源代码同步的开发配置，如开发部分中所定义。

device_cgroup_rules

device_cgroup_rules 定义此容器的设备 cgroup 规则列表。格式与 Linux 内核在控制组设备白名单控制器中指定的相同格式。

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

devices

devices 以 HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS] 的形式定义创建的容器的设备映射列表。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

dns

dns 定义要设置在容器网络接口配置上的自定义 DNS 服务器。它可以是单个值或列表。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt 列出要传递给容器 DNS 解析器（Linux 上的 /etc/resolv.conf 文件）的自定义 DNS 选项。

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

dns_search

dns_search 定义要设置在容器网络接口配置上的自定义 DNS 搜索域。它可以是单个值或列表。

dns_search: example.com

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

domainname

domainname 声明要用于服务容器的自定义域名。它必须是有效的 RFC 1123 主机名。

driver_opts

在 Docker Compose 版本 2.27.1 中引入

driver_opts 指定要传递给驱动程序的键值对选项列表。这些选项取决于驱动程序。有关更多信息，请参阅驱动程序的文档。

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

entrypoint

entrypoint 声明服务容器的默认入口点。这会覆盖服务 Dockerfile 中的 ENTRYPOINT 指令。

如果 entrypoint 非空，Compose 将忽略图像中的任何默认命令，例如 Dockerfile 中的 CMD 指令。

另请参阅 command 以设置或覆盖由入口点进程执行的默认命令。

在简短形式中，值可以定义为字符串

entrypoint: /code/entrypoint.sh

或者，值也可以是列表，方式类似于 Dockerfile 中的定义。

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

如果值为 null，则使用图像中的默认入口点。

如果值为 []（空列表）或 ''（空字符串），则会忽略图像声明的默认入口点，即将其覆盖为空。

env_file

env_file 属性用于指定一个或多个包含要传递给容器的环境变量的文件。

env_file: .env

env_file 也可以是列表。列表中的文件将从上到下处理。对于在两个 env 文件中指定的相同变量，将使用列表中最后一个文件的值。

env_file:
  - ./a.env
  - ./b.env

列表元素也可以声明为映射，这样您就可以设置一个额外的属性 required。这默认为 true。当 required 设置为 false 且 .env 文件不存在时，Compose 会静默忽略该条目。

env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false

required 属性适用于 Docker Compose 版本 2.24.0 或更高版本。

相对路径将从 Compose 文件的父文件夹解析。由于绝对路径会阻止 Compose 文件的可移植性，因此 Compose 会在使用此类路径设置 env_file 时发出警告。

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

Env_file 格式

.env 文件中的每一行都必须采用 VAR[=[VAL]] 格式。以下语法规则适用

以 # 开头的行将被视为注释并被忽略。
空行将被忽略。
未加引号和双引号 (") 值将应用插值。
每一行代表一个键值对。值可以可选地加引号。
- VAR=VAL -> VAL
- VAR="VAL" -> VAL
- VAR='VAL' -> VAL
未加引号值的内联注释必须以空格开头。
- VAR=VAL # comment -> VAL
- VAR=VAL# not a comment -> VAL# not a comment
加引号值的内联注释必须跟在结束引号之后。
- VAR="VAL # not a comment" -> VAL # not a comment
- VAR="VAL" # comment -> VAL
单引号 (') 值将按字面使用。
- VAR='$OTHER' -> $OTHER
- VAR='${OTHER}' -> ${OTHER}
引号可以使用 \ 转义。
- VAR='Let\'s go!' -> Let's go!
- VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
常见的 shell 转义序列（包括 \n、\r、\t 和 \\）在双引号值中受支持。
- VAR="some\tvalue" -> some value
- VAR='some\tvalue' -> some\tvalue
- VAR=some\tvalue -> some\tvalue

可以省略 VAL，在这种情况下，变量值为空字符串。可以省略 =VAL，在这种情况下，变量将被取消设置。

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"

environment

environment 属性定义在容器中设置的环境变量。environment 可以使用数组或映射。任何布尔值；true、false、yes、no 应包含在引号中，以确保它们不会被 YAML 解析器转换为 True 或 False。

环境变量可以通过单个键（没有值等于符号）声明。在这种情况下，Compose 依赖于您来解析值。如果值未解析，则变量将被取消设置并从服务容器环境中删除。

映射语法

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

数组语法

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

当为服务同时设置 env_file 和 environment 时，environment 设置的值具有优先级。

expose

expose 定义 Compose 从容器中公开的（传入）端口或端口范围。这些端口必须可供链接的服务访问，不应发布到主机。只能指定内部容器端口。

语法是 <portnum>/[<proto>] 或 <startport-endport>/[<proto>]（用于端口范围）。如果未显式设置，则使用 tcp 协议。

expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp"

注意
如果图像的 Dockerfile 已经公开端口，那么即使在 Compose 文件中未设置 expose，它也对网络上的其他容器可见。

extends

extends 允许您在不同的文件中共享通用配置，甚至可以在不同的项目之间共享。使用 extends，您可以在一个地方定义一组通用的服务选项，并从任何地方引用它。您可以引用另一个 Compose 文件并选择您想在自己的应用程序中使用的服务，并且能够根据自己的需求覆盖某些属性。

您可以在任何服务上使用 extends，以及其他配置键。extends 值必须是使用必填 service 和可选 file 键定义的映射。

extends:
  file: common.yml
  service: webapp

service：定义被引用为基础的服务的名称，例如 web 或 database。
file：定义该服务的 Compose 配置文件的位置。

当服务使用 extends 时，它也可以指定对其他资源的依赖关系，例如显式 volumes 声明。但是，请注意，extends 不会自动将目标卷定义合并到扩展的 Compose 文件中。相反，您有责任确保扩展服务存在等效的资源以保持一致性。Docker Compose 会验证 Compose 模型中是否存在具有所引用 ID 的资源。

extends 目标中对其他资源的依赖关系可以是

通过 volumes、networks、configs、secrets、links、volumes_from 或 depends_on 的显式引用
在命名空间声明（ipc、pid、network_mode）中使用 service:{name} 语法对其他服务的引用

不支持使用 extends 进行循环引用，Compose 在检测到循环引用时会返回错误。

查找引用服务

file 值可以是

不存在。这表明正在引用同一个 Compose 文件中的另一个服务。
文件路径，可以是
- 相对路径。此路径被视为相对于主 Compose 文件的位置。
- 绝对路径。

由 service 表示的服务必须存在于识别的引用 Compose 文件中。如果 Compose 返回错误，则

未找到由 service 表示的服务。
未找到由 file 表示的 Compose 文件。

合并服务定义

两个服务定义，一个是当前 Compose 文件中的主要定义，另一个是由 extends 指定的引用定义，以以下方式合并

映射：主要服务定义中的映射键会覆盖引用服务定义中的映射键。未被覆盖的键将原样包含在内。
序列：将项目合并到一个新的序列中。元素的顺序保持不变，引用项在前面，主项在后面。
标量：主要服务定义中的键优先于引用服务定义中的键。

以下键应被视为映射：annotations、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，除非引用映射也指定 disable: true。在这种情况下，Compose 会返回错误。

例如，以下输入

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

为 cli 服务生成以下配置。如果使用数组语法，也会生成相同的输出。

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 下的项目也被视为映射，其中键是容器内的目标路径。

例如，以下输入

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 标志。

image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro

如果引用服务定义包含 extends 映射，则该映射下的项目将直接复制到新的合并定义中。然后再次启动合并过程，直到没有 extends 键为止。

例如，以下输入

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

为 cli 服务生成以下配置。在这里，cli 服务从 common 服务获取 user 键，而 common 服务又从 base 服务获取此键。

image: busybox
user: root

序列

以下键应被视为序列：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。合并产生的任何重复项都会被移除，因此序列中只包含唯一元素。

例如，以下输入

services:
  common:
    image: busybox
    security_opt:
      - label:role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label:user:USER

为 cli 服务生成以下配置。

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

如果使用列表语法，以下键也应被视为序列：dns、dns_search、env_file、tmpfs。与上面提到的序列字段不同，合并产生的重复项不会被移除。

标量

服务定义中任何其他允许的键都应被视为标量。

external_links

external_links 将服务容器链接到 Compose 应用程序外部管理的服务。external_links 定义了使用平台查找机制检索的现有服务的名称。可以指定 SERVICE:ALIAS 形式的别名。

external_links:
  - redis
  - database:mysql
  - database:postgresql

extra_hosts

extra_hosts 将主机名映射添加到容器网络接口配置（Linux 的 /etc/hosts）。

简短语法

简短语法在列表中使用纯字符串。值必须以 HOSTNAME=IP 的形式设置附加主机的 hostname 和 IP 地址。

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 地址可以括在方括号中，例如

extra_hosts:
  - "myhostv6=[::1]"

分隔符 = 是首选，但也可以使用 :。在 Docker Compose 版本 2.24.1 中引入。例如

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

长语法

或者，可以将 extra_hosts 设置为 hostname 和 IP 之间的映射

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose 在容器的网络配置中创建具有 IP 地址和主机名的匹配条目，这意味着对于 Linux /etc/hosts，将获得额外的行

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

group_add

group_add 指定容器内用户必须属于的额外组，按名称或编号指定。

此功能在多个容器（以不同用户身份运行）需要在共享卷上读取或写入同一个文件时非常有用。该文件可以由所有容器共享的组拥有，并在 group_add 中指定。

services:
  myservice:
    image: alpine
    group_add:
      - mail

在创建的容器内运行 id 必须显示用户属于 mail 组，如果没有声明 group_add，则不会出现这种情况。

healthcheck

healthcheck 属性声明一个检查，该检查用于确定服务容器是否“健康”。它的工作原理相同，并且具有与服务 Docker 镜像设置的 HEALTHCHECK Dockerfile 指令集相同的默认值。您的 Compose 文件可以覆盖 Dockerfile 中设置的值。

有关 HEALTHCHECK 的更多信息，请参阅 Dockerfile 参考。

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

interval、timeout、start_period 和 start_interval 以持续时间指定。在 Docker Compose 版本 2.20.2 中引入

test 定义 Compose 运行的命令以检查容器健康状况。它可以是字符串或列表。如果它是列表，第一个项目必须是 NONE、CMD 或 CMD-SHELL。如果它是字符串，则等效于指定 CMD-SHELL，后面跟着该字符串。

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

使用 CMD-SHELL 使用容器的默认 shell（Linux 的 /bin/sh）运行配置为字符串的命令。以下两种形式是等效的

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

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

NONE 禁用健康检查，主要用于禁用服务 Docker 镜像设置的 Healthcheck Dockerfile 指令集。或者，可以通过设置 disable: true 来禁用镜像设置的健康检查

healthcheck:
  disable: true

hostname

hostname 声明一个用于服务容器的自定义主机名。它必须是一个有效的 RFC 1123 主机名。

image

image 指定要从中启动容器的镜像。image 必须遵循 Open Container Specification 可寻址镜像格式，如 [<registry>/][<project>/]<image>[:<tag>|@<digest>]。

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

如果平台上不存在镜像，Compose 会根据 pull_policy 尝试拉取它。如果您也使用 Compose Build Specification，则有其他选项可用于控制拉取优先级，而不是从源代码构建镜像，但是拉取镜像是默认行为。

只要声明了 build 部分，就可以从 Compose 文件中省略 image。如果您未使用 Compose Build Specification，如果 Compose 文件中缺少 image，Compose 将无法正常工作。

init

init 在容器内运行一个 init 进程（PID 1），该进程转发信号并回收进程。将此选项设置为 true 以为服务启用此功能。

services:
  web:
    image: alpine:latest
    init: true

使用的 init 二进制文件是特定于平台的。

ipc

ipc 配置服务容器设置的 IPC 隔离模式。

shareable：为容器提供自己的私有 IPC 命名空间，并有可能与其他容器共享。
service:{name}：使容器加入另一个容器的（shareable）IPC 命名空间。

    ipc: "shareable"
    ipc: "service:[service name]"

isolation

isolation 指定容器的隔离技术。支持的值是特定于平台的。

labels

labels 向容器添加元数据。您可以使用数组或映射。

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

Compose 创建具有规范标签的容器

com.docker.compose.project 设置在 Compose 创建的所有资源上，设置为用户项目名称
com.docker.compose.service 设置在服务容器上，使用 Compose 文件中定义的服务名称

com.docker.compose 标签前缀是保留的。在 Compose 文件中指定带有此前缀的标签会导致运行时错误。

links

links 定义对另一个服务中容器的网络链接。指定服务名称和链接别名（SERVICE:ALIAS）或只指定服务名称。

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

链接服务的容器可以通过与别名相同的 hostname 访问，或者如果未指定别名，则通过服务名称访问。

不需要链接来启用服务之间的通信。当未设置特定的网络配置时，任何服务都可以通过 default 网络上的服务名称访问任何其他服务。如果服务确实声明了它们连接到的网络，则 links 不会覆盖网络配置，未连接到共享网络的服务将无法通信。Compose 不会警告您配置不匹配。

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

logging

logging 定义服务的日志记录配置。

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

driver 名称指定服务容器的日志记录驱动程序。默认值和可用值是特定于平台的。可以使用 options 作为键值对来设置特定于驱动程序的选项。

mac_address

在 Docker Compose 版本 2.24.0 及更高版本中可用。

mac_address 为服务容器设置 MAC 地址。

注意容器运行时可能会拒绝此值（例如 Docker Engine >= v25.0）。在这种情况下，您应该改用 networks.mac_address。

mem_limit

mem_limit 配置容器可以分配的内存量的限制，以表示字节值的字符串形式设置。

设置后，mem_limit 必须与部署规范中的 limits.memory 属性一致。

mem_reservation

mem_reservation 配置容器可以分配的内存量的预留量，以表示字节值的字符串形式设置。

设置后，mem_reservation 必须与部署规范中的 reservations.memory 属性一致。

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，则容器允许使用无限交换，直到主机系统上可用的量。

network_mode

network_mode 设置服务容器的网络模式。

none：关闭所有容器网络。
host：让容器直接访问主机的网络接口。
service:{name}：让容器仅访问指定的服务。有关更多信息，请参阅容器网络。

    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"

设置后，将不允许使用 networks 属性，Compose 会拒绝任何包含这两个属性的 Compose 文件。

networks

networks 属性定义服务容器连接到的网络，引用 networks 顶级元素下的条目。networks 属性有助于管理容器的网络方面，提供对服务在 Docker 环境中如何分段和交互的控制。这用于指定该服务的容器应该连接到哪些网络。这对于定义容器如何相互通信以及与外部通信非常重要。

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

有关 networks 顶级元素的更多信息，请参阅网络。

别名

aliases 为网络上的服务声明备用主机名。同一网络上的其他容器可以使用服务名称或别名来连接到服务的某个容器。

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

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

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

在以下示例中，服务 frontend 能够在 back-tier 网络上以主机名 backend 或 database 访问 backend 服务。服务 monitoring 能够在 admin 网络上以 backend 或 mysql 访问相同的 backend 服务。

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier:
  back-tier:
  admin:

ipv4_address、ipv6_address

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

在顶级网络部分中的对应网络配置必须具有一个 ipam 属性，其中包含覆盖每个静态地址的子网配置。

services:
  frontend:
    image: example/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，它们属于一个众所周知的子网，并且完全由操作员管理，通常取决于它们部署的架构。

示例

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

mac_address

在 Docker Compose 版本 2.23.2 中引入

mac_address 设置服务容器在连接到此特定网络时使用的 MAC 地址。

优先级

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

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

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:

oom_kill_disable

如果设置了 oom_kill_disable，Compose 会配置平台，以便在内存不足的情况下不会杀死容器。

oom_score_adj

oom_score_adj 调整在内存不足的情况下，平台杀死容器的偏好。值必须在 -1000、1000 范围内。

pid

pid 设置 Compose 创建的容器的 PID 模式。支持的值是特定于平台的。

pids_limit

pids_limit 调整容器的 PIDs 限制。设置为 -1 表示无限 PIDs。

pids_limit: 10

设置后，pids_limit 必须与部署规范中的 pids 属性一致。

platform

platform 定义服务容器运行的目标平台。它使用 os[/arch[/variant]] 语法。

os、arch 和 variant 的值必须符合 OCI 镜像规范中使用的约定。

Compose 使用此属性来确定要拉取哪个版本的镜像，以及在哪个平台上执行服务的构建。

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

ports

ports 用于定义主机和容器之间的端口映射。这对于允许外部访问容器中运行的服务至关重要。它可以使用简短语法定义简单端口映射，也可以使用长语法定义，其中包含其他选项，例如协议类型和网络模式。

注意
端口映射不能与 network_mode: host 一起使用，否则会发生运行时错误。

简短语法

简短语法是用冒号分隔的字符串，用于设置主机 IP、主机端口和容器端口，形式为

[HOST:]CONTAINER[/PROTOCOL]，其中

HOST 是 [IP:](port | range)
CONTAINER 是 port | range
PROTOCOL 用于将端口限制为指定协议。tcp 和 udp 值由规范定义，Compose 提供对平台特定协议名称的支持。

如果未设置主机 IP，则它绑定到所有网络接口。端口可以是单个值或范围。主机和容器必须使用等效的范围。

可以指定两个端口（HOST:CONTAINER），也可以只指定容器端口。在后一种情况下，容器运行时会自动分配主机上的任何未分配端口。

HOST:CONTAINER 应始终指定为（引用的）字符串，以避免与 yaml 基数-60 浮点数冲突。

示例

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

注意
如果容器引擎不支持主机 IP 映射，Compose 会拒绝 Compose 文件并忽略指定的主机 IP。

长语法

长形式语法允许配置在简短形式中无法表达的其他字段。

target：容器端口
published：公开的端口。它定义为一个字符串，可以使用语法 start-end 设置为一个范围。这意味着实际端口被分配了一个剩余的可用端口，该端口在设定的范围内。
host_ip：主机 IP 映射，未指定表示所有网络接口（0.0.0.0）。
protocol：端口协议（tcp 或 udp）。默认为 tcp。
app_protocol：此端口用于的应用程序协议（TCP/IP 第 4 层/OSI 第 7 层）。这是可选的，可以用作提示，以便 Compose 为其理解的协议提供更丰富的行为。在 Docker Compose 版本 2.26.0 中引入。
mode：host：在每个节点上发布主机端口，或 ingress 使端口负载平衡。默认为 ingress。
name：端口的人类可读名称，用于记录其在服务中的使用情况。

ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host

privileged

privileged 配置服务容器以提升的权限运行。支持和实际影响是特定于平台的。

profiles

profiles 定义服务要启用的命名配置文件列表。如果没有分配，则始终启动服务，但如果分配了，则仅在激活配置文件时启动服务。

如果存在，profiles 遵循 [a-zA-Z0-9][a-zA-Z0-9_.-]+ 的正则表达式格式。

services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

pull_policy

pull_policy 定义 Compose 在开始拉取镜像时做出的决定。可能的值是

always：Compose 始终从注册表拉取镜像。
never：Compose 不会从注册表拉取镜像，而是依赖于平台缓存的镜像。如果没有缓存的镜像，则会报告错误。
missing：Compose 仅在平台缓存中没有镜像时才会拉取镜像。如果您没有使用 Compose 构建规范，这是默认选项。if_not_present 被认为是此值的别名，为了向后兼容。
build：Compose 构建镜像。如果镜像已经存在，Compose 会重建镜像。

read_only

read_only 配置服务容器以只读文件系统创建。

restart

restart 定义平台在容器终止时应用的策略。

no：默认重启策略。它在任何情况下都不会重启容器。
always：此策略始终重启容器，直到将其删除。
on-failure[:max-retries]：如果退出代码表示错误，则此策略会重启容器。可选地，限制 Docker 守护进程尝试的重启重试次数。
unless-stopped：此策略会重启容器，无论退出代码如何，但当服务停止或删除时停止重启。

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

您可以在 Docker run 参考页面重启策略（--restart）部分找到有关重启策略的更详细的信息。

runtime

runtime 指定用于服务的容器的运行时。

例如，runtime 可以是 OCI 运行时规范的实现的名称，例如 "runc"。

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

默认值为 runc。要使用其他运行时，请参阅替代运行时。

scale

scale 指定为该服务部署的容器的默认数量。当两者都设置时，scale 必须与部署规范中的 replicas 属性一致。

secrets

secrets 属性允许服务访问由 Compose 文件顶级元素定义的敏感数据。服务可以被授权访问多个 secrets。

Compose 支持两种不同的语法变体：短语法和长语法。Compose 文件中可以同时使用长语法和短语法。

如果 secret 在平台上不存在或未在 Compose 文件的 secrets 顶级部分中定义，Compose 会报告错误。

在顶级 secrets 中定义一个 secret 并不意味着授权任何服务访问它。这种授权必须在服务规范中作为 secrets 服务元素明确指定。

简短语法

短语法变体只指定 secret 名称。这会授予容器访问 secret 的权限，并将它以只读方式挂载到容器中的 /run/secrets/<secret_name>。源名称和目标挂载点都设置为 secret 名称。

以下示例使用短语法授予 frontend 服务访问 server-certificate secret 的权限。server-certificate 的值设置为文件 ./server.cert 的内容。

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

长语法

长语法提供更细粒度的控制，可以自定义 secret 在服务容器中的创建方式。

source：secret 在平台上的名称。
target：在服务任务容器的 /run/secrets/ 中挂载的文件名，或者如果需要使用其他位置，则为文件的绝对路径。如果未指定，则默认为 source。
uid 和 gid：在服务任务容器的 /run/secrets/ 中拥有该文件的数字 UID 或 GID。默认值为运行容器的 USER。
mode：在服务任务容器的 /run/secrets/ 中挂载文件的权限，以八进制表示。默认值为世界可读权限（模式 0444）。如果设置了可写位，则必须忽略它。可以设置可执行位。

以下示例将 server-certificate secret 文件的名称设置为容器中的 server.cert，将模式设置为 0440（组可读），并将用户和组设置为 103。server-certificate 的值设置为文件 ./server.cert 的内容。

services:
  frontend:
    image: example/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0440
secrets:
  server-certificate:
    file: ./server.cert

security_opt

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

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

有关可以覆盖的其他默认标签方案，请参阅安全配置.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

默认值为 10 秒，容器在发送 SIGKILL 之前退出。

stop_signal

stop_signal 定义 Compose 用于停止服务容器的信号。如果未设置，Compose 通过发送 SIGTERM 停止容器。

stop_signal: SIGUSR1

storage_opt

storage_opt 定义服务的存储驱动程序选项。

storage_opt:
  size: '1G'

sysctls

sysctls 定义要在容器中设置的内核参数。sysctls 可以使用数组或映射。

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

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

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

tmpfs

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

tmpfs: /run

tmpfs:
  - /run
  - /tmp

tty

tty 配置服务容器以使用 TTY 运行。这与使用 -t 或 --tty 标志运行容器相同。有关更多信息，请参阅分配伪终端.

支持的值为 true 或 false。

ulimits

ulimits 覆盖容器的默认 ulimits。它以整数形式指定单个限制，或者以映射形式指定软限制/硬限制。

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

user

user 覆盖用于运行容器进程的用户。默认值由映像设置（例如 Dockerfile 的 USER）。如果没有设置，则为 root。

userns_mode

userns_mode 设置服务的用户名空间。支持的值特定于平台，可能取决于平台配置。

userns_mode: "host"

uts

在 Docker Compose 版本 2.15.1 中引入。

uts 配置为服务容器设置的 UTS 命名空间模式。当未指定时，如果支持，则由运行时决定是否分配 UTS 命名空间。可用值为

'host'：导致容器使用与主机相同的 UTS 命名空间。

    uts: "host"

volumes

volumes 属性定义服务容器可以访问的挂载主机路径或命名卷。可以使用 volumes 定义多种类型的挂载：volume、bind、tmpfs 或 npipe。

如果挂载是主机路径，并且只被单个服务使用，则可以将其声明为服务定义的一部分。要跨多个服务重用卷，必须在 volumes 顶级元素中声明命名卷。

以下示例展示了 backend 服务使用的命名卷 (db-data)，以及为单个服务定义的绑定挂载。

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

有关 volumes 顶级元素的更多信息，请参阅卷.

简短语法

短语法使用带冒号分隔值的单个字符串来指定卷挂载 (VOLUME:CONTAINER_PATH)，或访问模式 (VOLUME:CONTAINER_PATH:ACCESS_MODE)。

VOLUME：可以是托管容器的平台上的主机路径（绑定挂载）或卷名称。
CONTAINER_PATH：在容器中挂载卷的路径。
ACCESS_MODE：用逗号分隔的 , 选项列表
- rw：读写访问。如果未指定，则为默认值。
- ro：只读访问。
- z：SELinux 选项，指示绑定挂载主机内容在多个容器之间共享。
- Z：SELinux 选项，指示绑定挂载主机内容是私有的，不与其他容器共享。

注意
SELinux 重新标记绑定挂载选项在没有 SELinux 的平台上会被忽略。

注意相对主机路径只受部署到本地容器运行时的 Compose 支持。这是因为相对路径是从 Compose 文件的父目录解析的，这仅适用于本地情况。当 Compose 部署到非本地平台时，它会拒绝使用相对主机路径的 Compose 文件，并显示错误。为了避免与命名卷的歧义，相对路径应始终以 . 或 .. 开头。

长语法

长形式语法允许配置在简短形式中无法表达的其他字段。

type：挂载类型。可以是 volume、bind、tmpfs、npipe 或 cluster
source：挂载的来源，对于绑定挂载，是主机上的路径，或者是在顶级 volumes 键中定义的卷的名称。不适用于 tmpfs 挂载。
target：在容器中挂载卷的路径。
read_only：将卷设置为只读的标志。
bind：用于配置其他绑定选项
- propagation：用于绑定的传播模式。
- create_host_path：如果主机上的源路径不存在，则创建一个目录。如果路径上存在内容，Compose 不会执行任何操作。为了向后兼容 docker-compose 遗留，这由短语法自动隐式实现。
- selinux：SELinux 重新标记选项 z（共享）或 Z（私有）
volume：配置其他卷选项
- nocopy：标志，用于在创建卷时禁用从容器复制数据。
- subpath：卷内的路径，用于挂载，而不是卷的根目录。
tmpfs：配置其他 tmpfs 选项
- size：tmpfs 挂载的大小，以字节为单位（可以是数字或字节单位）。
- mode：tmpfs 挂载的文件模式，以 Unix 权限位表示，用八进制数表示。在 Docker Compose 版本 2.14.0 中引入。
consistency：挂载的一致性要求。可用值特定于平台。

提示
使用大型仓库或单体仓库，或者使用不再随着代码库扩展的虚拟文件系统？Compose 现在利用了同步文件共享，并自动为绑定挂载创建文件共享。确保你已使用付费订阅登录 Docker，并在 Docker Desktop 的设置中启用“访问实验性功能”和“使用 Compose 管理同步文件共享”。

volumes_from

volumes_from 挂载来自另一个服务或容器的所有卷。可以选择指定只读访问 ro 或读写访问 rw。如果未指定访问级别，则使用读写访问。

你还可以使用 container: 前缀从 Compose 不管理的容器中挂载卷。

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

working_dir

working_dir 覆盖容器的工作目录，该目录由映像指定，例如 Dockerfile 的 WORKDIR。