在 Docker Compose 中定义服务

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

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

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

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

示例

简单示例

以下示例演示了如何定义两个简单服务，设置它们的镜像，映射端口，并使用 Docker Compose 配置基本的环境变量。

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb

高级示例

在以下示例中，proxy 服务使用 Nginx 镜像，将本地 Nginx 配置文件挂载到容器中，暴露端口 80 并依赖于 backend 服务。

backend 服务从 backend 目录中位于 builder 阶段的 Dockerfile 构建镜像。

services:
  proxy:
    image: nginx
    volumes:
      - type: bind
        source: ./proxy/nginx.conf
        target: /etc/nginx/conf.d/default.conf
        read_only: true
    ports:
      - 80:80
    depends_on:
      - backend

  backend:
    build:
      context: backend
      target: builder

有关更多 Compose 文件示例，请浏览 Awesome Compose 示例。

属性

annotations

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

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

attach

当定义 attach 并将其设置为 false 时，Compose 不会收集服务日志，直到您明确请求。

默认服务配置为 attach: true。

build

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

blkio_config

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

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 内核的平台上的 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

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

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

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

注意

与 Dockerfile 中的 CMD 指令不同，command 字段不会自动在镜像中定义的 SHELL 指令的上下文中运行。如果您的 command 依赖于 shell 特定的功能，例如环境变量扩展，您需要明确地在 shell 中运行它。例如

command: /bin/sh -c 'echo "hello $$HOSTNAME"'

该值也可以是列表，类似于 Dockerfile 使用的 exec-form 语法。

configs

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 容器，则可以将 file: 和 registry: 协议用于 credential_spec。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: 指定在启动依赖服务之前，依赖项应处于“健康”状态（由 healthcheck 指示）。
  • 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 Deploy 规范中所定义。

develop

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"

devices 还可以依赖 CDI 语法，让容器运行时选择设备

devices:
  - "vendor1.com/device=gpu"

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

driver_opts 指定要传递给驱动程序的键值对选项列表。这些选项依赖于驱动程序。

services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.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

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

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

env_file 也可以是列表。列表中的文件从上到下处理。对于在两个环境变量文件中指定的同一变量，列表中的最后一个文件中的值有效。

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

格式

format 属性允许您为 env_file 使用备用文件格式。如果未设置，env_file 将根据 Env_file 格式中概述的 Compose 规则进行解析。

raw 格式允许您使用包含 key=value 项的 env_file，但 Compose 不会尝试解析该值进行插值。这允许您按原样传递值，包括引号和 $ 符号。

env_file:
  - path: ./default.env
    format: raw

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、networks、configs、secrets、links、volumes_from 或 depends_on 等属性显式定义。或者，依赖项可以在命名空间声明（如 ipc、pid 或 network_mode）中使用 service:{name} 语法引用另一个服务。

Compose 不会自动将这些引用的资源导入到扩展模型中。您有责任确保所有必需的资源都在依赖 extends 的模型中明确声明。

不支持 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 形式设置附加主机的主机名和 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 可以设置为主机名和 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

gpus

gpus 指定要为容器使用分配的 GPU 设备。这等同于具有隐式 gpu 功能的 设备请求。

services:
  model:
    gpus:
      - driver: 3dfx
        count: 2

gpus 也可以设置为字符串 all，以将所有可用的 GPU 设备分配给容器。

services:
  model:
    gpus: all

group_add

group_add 指定用户在容器内必须是其成员的额外组（按名称或编号）。

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

services:
  myservice:
    image: alpine
    group_add:
      - mail

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

healthcheck

healthcheck 属性声明一个检查，用于确定服务容器是否“健康”。它的工作方式与 HEALTHCHECK Dockerfile 指令相同，并且具有与 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 必须遵循开放容器规范 可寻址镜像格式，格式为 [<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 部分，就可以从 Compose 文件中省略 image。如果您不使用 Compose 构建规范，如果 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 文件中指定带有此前缀的标签会导致运行时错误。

label_file

label_file 属性允许您从外部文件或文件列表加载服务的标签。这提供了一种方便的方式来管理多个标签，而无需使 Compose 文件混乱。

该文件使用键值格式，类似于 env_file。您可以将多个文件指定为列表。当使用多个文件时，它们按照在列表中出现的顺序进行处理。如果在多个文件中定义了相同的标签，则列表中最后一个文件中的值将覆盖较早的值。

services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels

如果标签在 label_file 和 labels 属性中都定义，则 labels 中的值优先。

links

links 定义到另一个服务中容器的网络链接。既可以指定服务名称和链接别名 (SERVICE:ALIAS)，也可以只指定服务名称。

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

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

不需要链接即可使服务进行通信。当未设置特定网络配置时，任何服务都可以在 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，则容器被允许使用无限量的交换，直至主机系统上可用的量。

models

models 定义服务在运行时应使用的 AI 模型。每个引用的模型必须在 models 顶级元素下定义。

services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

当服务链接到模型时，Docker Compose 会注入环境变量，以将连接详细信息和模型标识符传递给容器。这允许应用程序在运行时动态定位并与模型通信，而无需硬编码值。

长语法

长语法让您可以更好地控制环境变量名称。

• endpoint_var 设置保存模型运行器 URL 的环境变量的名称。
• model_var 设置保存模型标识符的环境变量的名称。

如果两者之一被省略，Compose 会根据模型键使用以下规则自动生成环境变量名称

• 将模型键转换为大写
• 将所有 '-' 字符替换为 '_'
• 为端点变量附加 _URL

network_mode

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

• none: 关闭所有容器网络。
• host: 授予容器对主机网络接口的原始访问权限。
• service:{name}: 授予容器通过引用其服务名称访问指定容器的权限。
• container:{name}: 授予容器通过引用其容器 ID 访问指定容器的权限。

有关容器网络的更多信息，请参阅 Docker Engine 文档。

    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 顶级元素的更多信息，请参阅 网络。

隐式默认网络

如果 networks 在 Compose 文件中为空或缺失，Compose 会为服务定义一个隐式定义，即连接到 default 网络

services:
  some-service:
    image: foo

此示例实际上等同于

services:
  some-service:
    image: foo
    networks:
      default: {}

如果您希望服务不连接到网络，则必须设置 network_mode: none。

别名

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: {}

interface_name

interface_name 允许您指定用于将服务连接到给定网络的网络接口的名称。这确保了跨服务和网络的一致且可预测的接口命名。

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

运行示例 Compose 应用程序显示

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

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

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

driver_opts

driver_opts 指定一个选项列表，作为键值对传递给驱动程序。这些选项是驱动程序特定的。请查阅驱动程序的文档以获取更多信息。

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

gw_priority

具有最高 gw_priority 的网络被选为服务容器的默认网关。如果未指定，默认值为 0。

在以下示例中，app_net_2 将被选为默认网关。

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

priority

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

如果容器运行时接受服务级别的 mac_address 属性，则它将应用于具有最高 priority 的网络。在其他情况下，请使用属性 networks.mac_address。

priority 不影响哪个网络被选为默认网关。请改用 gw_priority 属性。

priority 不控制网络连接添加到容器的顺序，它不能用于确定容器中的设备名称 (eth0 等)。

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 调整容器的 PID 限制。设置为 -1 表示无限 PID。

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 一起使用。这样做会导致运行时错误，因为 network_mode: host 已经直接将容器端口暴露给主机网络，因此不需要端口映射。

短语法

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

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

• HOST 是 [IP:](port | range)（可选）。如果未设置，它将绑定到所有网络接口 (0.0.0.0)。
• CONTAINER 是 port | range。
• PROTOCOL 将端口限制为指定协议 tcp 或 udp（可选）。默认为 tcp。

端口可以是单个值或范围。HOST 和 CONTAINER 必须使用等效的范围。

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

HOST:CONTAINER 应始终指定为（带引号的）字符串，以避免与 YAML base-60 float 冲突。

IPv6 地址可以括在方括号中。

示例

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"
  - "::1:6000:6000"
  - "[::1]:6001:6001"
  - "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：指定端口在 Swarm 设置中如何发布。如果设置为 host，则在 Swarm 中的每个节点上发布端口。如果设置为 ingress，则允许在 Swarm 中的节点之间进行负载均衡。默认为 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

post_start

post_start 定义容器启动后运行的一系列生命周期钩子。命令运行的确切时间不作保证。

• command：指定容器启动后要运行的命令。此属性是必需的，您可以选择使用 shell 形式或 exec 形式。
• user：运行命令的用户。如果未设置，则命令以与主服务命令相同的用户身份运行。
• privileged：允许 post_start 命令以特权访问运行。
• working_dir：运行命令的工作目录。如果未设置，则在与主服务命令相同的工作目录中运行。
• environment：专门为 post_start 命令设置环境变量。虽然该命令继承了为服务主命令定义的环境变量，但此部分允许您添加新变量或覆盖现有变量。

services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

有关更多信息，请参阅 使用生命周期钩子。

pre_stop

pre_stop 定义容器停止前运行的一系列生命周期钩子。如果容器自行停止或突然终止，这些钩子将不会运行。

配置等同于 post_start。

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

provider

provider 可用于定义 Compose 不直接管理的服务。Compose 将服务生命周期委托给专用或第三方组件。

  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        foo: bar
  app:
    image: myapp
    depends_on:
       - database

当 Compose 运行应用程序时，awesomecloud 二进制文件用于管理 database 服务的设置。依赖服务 app 接收以服务名称为前缀的额外环境变量，以便它可以访问资源。

为了说明，假设 awesomecloud 执行产生了变量 URL 和 API_KEY，则 app 服务使用环境变量 DATABASE_URL 和 DATABASE_API_KEY 运行。

当 Compose 停止应用程序时，awesomecloud 二进制文件用于管理 database 服务的拆卸。

Compose 将服务生命周期委托给外部二进制文件的机制在此处描述：here。

有关使用 provider 属性的更多信息，请参阅 使用提供程序服务。

type

type 属性是必需的。它定义了 Compose 用于管理设置和拆卸生命周期事件的外部组件。

options

options 特定于所选提供程序，并且未经验证 Compose 规范

pull_policy

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

• always：Compose 始终从注册表拉取镜像。
• never：Compose 不从注册表拉取镜像，并依赖平台缓存的镜像。如果没有缓存的镜像，则报告失败。
• missing：Compose 仅在平台缓存中不可用时才拉取镜像。如果您不使用 Compose 构建规范，这是默认选项。if_not_present 被视为此值的别名以实现向后兼容性。
• build：Compose 构建镜像。如果镜像已存在，Compose 会重建镜像。
• daily：如果上次拉取发生在 24 小时之前，Compose 会检查注册表是否有镜像更新。
• weekly：如果上次拉取发生在 7 天之前，Compose 会检查注册表是否有镜像更新。
• every_<duration>：如果上次拉取发生在 <duration> 之前，Compose 会检查注册表是否有镜像更新。持续时间可以用周 (w)、天 (d)、小时 (h)、分钟 (m)、秒 (s) 或它们的组合表示。

services:
  test:
    image: nginx
    pull_policy: every_12h

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 运行参考页面的 重启策略 (--restart) 部分找到有关重启策略的更详细信息。

runtime

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

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

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

默认值为 runc。要使用不同的运行时，请参阅 备用运行时。

scale

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

secrets

secrets 属性以每个服务为基础授予对由 secrets 顶级元素定义的敏感数据的访问权限。服务可以被授予对多个 secrets 的访问权限。

支持两种不同的语法变体；短语法和长语法。secrets 的长短语法可以在同一个 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：秘密在平台上存在的名称。
• target：要挂载到服务任务容器中 /run/secrets/ 的文件名，如果需要备用位置，则为文件的绝对路径。如果未指定，默认为 source。
• uid 和 gid：拥有服务任务容器中 /run/secrets/ 文件数值 uid 或 gid。默认值为 USER。
• mode：要挂载到服务任务容器中 /run/secrets/ 文件的 权限，采用八进制表示法。默认值是全局可读权限（模式 0444）。如果设置了可写位，则必须忽略它。可执行位可以设置。

请注意，当 secret 的来源是 file 时，Docker Compose 不支持 uid、gid 和 mode 属性。这是因为底层使用的绑定挂载不允许 uid 重新映射。

以下示例将 server-certificate 秘密文件的名称设置为容器中的 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: 0o440
secrets:
  server-certificate:
    file: ./server.cert

security_opt

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

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

有关您可以覆盖的更多默认标签方案，请参阅 安全配置。

shm_size

shm_size 配置服务容器允许的共享内存大小（Linux 上的 /dev/shm 分区）。它以 字节值 指定。

stdin_open

stdin_open 配置服务容器以分配的 stdin 运行。这与使用 -i 标志运行容器相同。有关更多信息，请参阅 保持 stdin 打开。

支持的值为 true 或 false。

stop_grace_period

stop_grace_period 指定当容器不处理 SIGTERM（或使用 stop_signal 指定的任何停止信号）时，Compose 在发送 SIGKILL 之前应等待多长时间。它以 持续时间 指定。

    stop_grace_period: 1s
    stop_grace_period: 1m30s

默认值是容器在发送 SIGKILL 之前退出需要等待 10 秒。

stop_signal

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

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)。

tmpfs

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

tmpfs:
 - <path>
 - <path>:<options>

• path：tmpfs 将挂载到容器内的路径。
• options：tmpfs 挂载选项的逗号分隔列表。

可用选项

• mode：设置文件系统权限。
• uid：设置拥有挂载 tmpfs 的用户 ID。
• gid：设置拥有挂载 tmpfs 的组 ID。

services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

tty

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

支持的值为 true 或 false。

ulimits

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

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

use_api_socket

当设置 use_api_socket 时，容器能够通过 API socket 与底层容器引擎进行交互。您的凭据被挂载到容器内部，因此容器作为您的命令的纯粹委托，与容器引擎相关。通常，容器运行的命令可以 pull 和 push 到您的注册表。

user

user 覆盖用于运行容器进程的用户。默认由镜像设置，例如 Dockerfile USER。如果未设置，则为 root。

userns_mode

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

userns_mode: "host"

uts

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 文件并报错。为避免与命名卷产生歧义，相对路径应始终以 . 或 .. 开头。

注意

对于绑定挂载，如果源路径在主机上不存在，短语法会在该路径创建目录。这是为了向后兼容旧版 docker-compose。通过使用长语法并将 create_host_path 设置为 false 可以防止这种情况。

长语法

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

• type：挂载类型。可以是 volume、bind、tmpfs、image、npipe 或 cluster
• source：挂载的来源，对于绑定挂载是主机上的路径，对于镜像挂载是 Docker 镜像引用，或者是 顶级 volumes 键 中定义的卷名称。不适用于 tmpfs 挂载。
• target：卷在容器中挂载的路径。
• read_only：将卷设置为只读的标志。
• bind：用于配置额外的绑定选项
  • propagation：绑定使用的传播模式。
  • create_host_path：如果主机上没有内容，则在源路径创建目录。默认为 true。
  • selinux：SELinux 重新标记选项 z（共享）或 Z（私有）
• volume：配置额外的卷选项
  • nocopy：禁用在创建卷时从容器复制数据的标志。
  • subpath：要挂载的卷内的路径，而不是卷根目录。
• tmpfs：配置额外的 tmpfs 选项
  • size：tmpfs 挂载的大小（以字节为单位，可以是数字或字节单位）。在 Docker Compose 2.14.0 版本中引入。
  • mode：tmpfs 挂载的文件模式，作为八进制数字的 Unix 权限位。在 Docker Compose 2.14.0 版本中引入。
• image：配置额外的镜像选项
  • subpath：要挂载的源镜像内的路径，而不是镜像根目录。在 Docker Compose 版本 2.35.0 中可用
• consistency：挂载的一致性要求。可用值是平台特定的。

提示

是否正在使用大型仓库或 monorepos，或者文件系统不再与您的代码库一起扩展？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。