docker compose 官方文档翻译（20240129更新）

为什么要对官方文档做翻译

使用一个工具，不管如何，始终离不开使用说明书的查阅，docker compose自然也不例外。虽然现在K8S在容器编排领域独占鳌头，但是对于大多数中小公司或是业务需要不复杂的公司来说K8S的入门门槛过高，反而是需要像docker compose这样轻量化的容器编排工具。所以我就有了萌生对docker compose文档翻译的想法，希望我的这个文档能对使用工具的技术人员们有所帮助。但限于个人能力有限，更新速度会较慢，翻译错漏的地方也请在评论区中提出。再次感谢各位读者！

注意 ：

1.重要的部分我会带英文原文

2.部分翻译带有自己的理解

3.本翻译借助了GLM-4大语言模型，真的感谢科技发展，GLM4大语言模型真的是国内少有能与GPT-4抗衡的模型。

Docker compose文档翻译

文档地址：

Overview

New to Compose?

Find more information about the key features and use cases of Docker Compose or try the get started guide.

The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a Compose file which is used to configure your Docker application’s services, networks, volumes, and more.

Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI.

The Compose Specification on Docker Docs is the Docker Compose implementation. If you wish to implement your own version of the Compose Specification, see the Compose Specication repository.

Note

Compose V1 no longer receives updates and is not available in new releases of Docker Desktop.

Compose V2 is included with all currently supported versions of Docker Desktop. For more information, see Migrate to Compose V2.

Use the following links to navigate key sections of the Compose Specification.

概述

这是文档的首页，该英文最主要的信息有一下几点

1. Compose V1 不再接收更新，也不再包含在 Docker Desktop 的新版本中。
2. Compose 文件格式的旧版本 2.x 和 3.x 已被合并到 Compose 规范中,统称 Compose V2

从首页可以直接导航到一下几个页面

1. 版本和名称(version)顶级元素 了解compose的版本和名称属性。
2. 服务(server)-顶级元素 探索所有compose的服务属性。
3. 网络(network)-顶级元素 查找compose的所有网络属性。
4. 存储卷(volumes)的顶级元素 探索所有compose的存储卷属性。
5. 配置(configs)的顶级元素 了解compose的配置。
6. 加密(secrets)的顶级元素 了解compose中的加密项属性。

Version top-level element

The top-level version property is defined by the Compose Specification for backward compatibility. It is only informative.

Compose doesn't use version to select an exact schema to validate the Compose file, but prefers the most recent schema when it's implemented.

Compose validates whether it can fully parse the Compose file. If some fields are unknown, typically because the Compose file was written with fields defined by a newer version of the Specification, you'll receive a warning message.

Name top-level element

The top-level name property is defined by the Specification as the project name to be used if you don't set one explicitly. Compose offers a way for you to override this name, and sets a default project name to be used if the top-level name element is not set.

Whenever a project name is defined by top-level name or by some custom mechanism, it is exposed for interpolation and environment variable resolution as COMPOSE_PROJECT_NAME

Version 字段

这段文字主要介绍了 Docker Compose 文件中的两个顶级元素：版本（version）和名称（name）。

版本（version）：这是一个信息性属性，用于保持向后兼容性。Compose 不会根据版本号选择一个确切的模式来验证 Compose 文件，而是使用它实现时的最新模式。如果 Compose 文件中包含未知字段（通常是因为使用了新版本的规范中定义的字段），Compose 会发出警告信息。

名称（name）：这是项目的名称，如果在 Compose 文件中没有明确设置，将使用默认值。用户可以通过某种自定义机制覆盖这个名称。定义的项目名称将作为环境变量 COMPOSE_PROJECT_NAME 用于插值和环境变量解析。

以下是COMPOSE_PROJECT_NAME的使用样例

1.services:
2.  foo:
3.    image: busybox
4.    environment:
5.      - COMPOSE_PROJECT_NAME
6.    command: echo "I'm running ${COMPOSE_PROJECT_NAME}"

Services top-level elements

A service is an abstract definition of a computing resource within an application which can be scaled or replaced independently from other components. Services are backed by a set of containers, run by the platform according to replication requirements and placement constraints. As services are backed by containers, they are defined by a Docker image and set of runtime arguments. All containers within a service are identically created with these arguments.

A Compose file must declare a services top-level element as a map whose keys are string representations of service names, and whose values are service definitions. A service definition contains the configuration that is applied to each service container.

Each service may also include a build section, which defines how to create the Docker image for the service. Compose supports building docker images using this service definition. If not used, the build section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the Compose Build Specification documentation.

Each service defines runtime constraints and requirements to run its containers. The deploy section groups these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with available resources. Deploy support is an optional aspect of the Compose Specification, and is described in detail in the Compose Deploy Specification documentation. If not implemented the deploy section is ignored and the Compose file is still considered valid.

attach

When attach is defined and set to false Compose does not collect service logs, until you explicitly request it to.

The default service configuration is attach: true.

build

build specifies the build configuration for creating a container image from source, as defined in the Compose Build Specification.

服务(server)-顶级标签

这段文字主要介绍了 Docker Compose 文件中的一个顶级元素server字段

1. 服务定义：服务是应用中计算资源的抽象，可以独立扩展或替换。每个服务由一个 Docker 镜像和运行时参数定义，并可以在 Compose 文件中通过 services 顶级元素进行配置。
2. 构建配置：服务的 build 部分定义了如何从源代码创建 Docker 镜像。这是可选的，如果不使用，则忽略该部分。
3. 部署配置：服务的 deploy 部分定义了运行容器的运行时约束和要求，允许平台根据资源调整部署策略。这也是可选的，如果未实现，则忽略该部分。
4. 日志收集配置：服务的 attach 属性定义了是否自动收集服务日志。默认值为 true，即自动收集日志；如果设置为 false，则不会自动收集。

在原官方文档中，对照表冗长，不适合在使用时快速从查询以及索引，为了方便在工程应用中快速查询及索引， 现对官方文档的字段解释汇总成对照表。

服务(Service)标签功能字段（KEY）对照表

一级标签	详细说明	实例
blkio_config（不常用键值） blkio_config defines a set of configuration options to set block IO limits for a service. 限制容器的硬盘（块）IO		(顶层标签) services:   foo:     image: busybox     blkio_config:
	device_read_bps device_write_bps 限制容器对硬盘设备的读/写 每秒字节数 参数: Path，硬盘设备的路径 Rate，限制硬盘设备的读写速率bps，可以是整数类型，也可以是字符串（例如“12mb”，建议使用该方式，这样的可读性会较高）	device_read_bps:          - path: /dev/sdb            rate: '12mb'        device_write_bps:          - path: /dev/sdb            rate: '1024k'
	device_read_iops device_write_iops 限制容器对硬盘设备的 每秒操作数 参数: Path，硬盘设备的路径 Rate，整数值，每秒允许的操作次数iops。	device_read_iops:          - path: /dev/sdb            rate: 120        device_write_iops:          - path: /dev/sdb            rate: 30
	Weight 权重 设定相对于其他服务分配给一个服务的带宽比例。取一个介于 10 到 1000 之间的整数值，默认值为 500。	weight: 300
	weight_device 设备权重 设置设备的带宽分配权重 参数： path: 定义受影响设备的硬盘路径。 weight: 一个介于 10 到 1000 之间的整数值。	weight_device:          - path: /dev/sda            weight: 400
cpu_count	定义了容器可使用的 CPU 数量
cpu_percent	定义了可用 CPU 的可使用百分比。
cpu_shares	定义了服务容器的相对其他容器的 CPU 权重，以整数值表示。
cpu_period	配置了当平台基于 Linux 内核时 CPU CFS（完全公平调度器）的周期。
cpu_quota	配置了当平台基于 Linux 内核时 CPU CFS（完全公平调度器）的配额。
cpu_rt_runtime	配置了支持实时调度器的平台上的 CPU 分配参数。它可以是一个使用微秒作为单位的整数值，或者一个持续时间。	cpu_rt_runtime: '400ms'  cpu_rt_runtime: 95000`
cpu_rt_period	配置了支持实时调度器的平台上的 CPU 分配参数。它可以是一个使用微秒作为单位的整数值，或者一个持续时间。	cpu_rt_period: '1400us'  cpu_rt_period: 11000`
Cpus（已弃用） 使用 deploy.limits.cpus替代	定义了分配给服务容器的（可能是虚拟的）CPU 数量。这是一个分数值。0.000 表示没有限制。
cpuset	指定容器运行在哪个物理CPU上，值可以是范围0-3或者列表0，1
cap_add cap是capbilities的缩写	指定额外的容器功能 值是字符串类型。	官方给出的容器功能查询表地址 Index of /linux /man-pages/man7 /capabilities.7.html
cap_drop	关闭特定的容器功能（其实就是Linux内核功能） 值是字符串的类型	cap_drop:   - NET_ADMIN   - SYS_ADMIN
cgroup	指定了容器应该加入的 cgroup 命名空间。如果未指定，并且容器运行时支持 cgroup 命名空间，那么容器运行时将决定使用哪一个 cgroup 命名空间。	该功能不要乱用，cgroup也是linux内核的命名空间，如果使用不当，会出现不可预料的错误，正常情况下，由容器运行时自行决定就好。
cgroup_parent	指定容器的可选父 cgroup。	同上，该功能不要乱用
Command（常用）	指定容器启动时运行的命令，或者覆盖容器镜像声明的默认命令，例如 Dockerfile 中的 CMD 如果该值为 null，则使用镜像中的默认命令。 如果该值为 []（空列表）或 ‘’（空字符串），则忽略镜像中声明的默认命令，即被覆盖为空。	command: bundle exec thin -p 3000 也可以是一个列表 command: [ "bundle", "exec", "thin", "-p", "3000" ]
config	可以让容器在不重启的情况下重新改变容器的配置文件配置项 该字段支持两种形式的表达式 short syntax（简单模式） Long syntax（详细模式）
config	short syntax（简单模式） 简短格式只指定配置的名称。这样做可以让容器访问配置，并将其作为文件挂载到服务容器的文件系统中。在 Linux 容器中，配置的默认挂载点位于 /<配置名称>，而在 Windows 容器中位于 C:<配置名称>。	以下示例使用短语法授予 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
config	long syntax（详细模式） 该模式下在运行容器内创建配置文件提供了更细致的控制参数 source: 引用的配置名称。 target: 在服务任务容器中挂载的文件的路径和名称。如果未指定，默认为 /。 uid 和 gid: 容器内配置文件所有者的UID或者GID的编号，如果为指定，默认为容器本身 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: my-web-container
credential_spec	为托管服务帐户配置凭据规范，该字段看官方的描述应该是作用于Windows容器，讲本地凭据的文件，使用使用file，对应的值是文件路径。  registry，对应的值是宿主机上的注册表值，注册表中的路径必须在 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs 这个字段中	services: myservice:   image:myimage:latest  credential_spec:      config: my_credential_specconfigs: my_credentials_spec:    file: ./my-credential-spec.json
depends_on	定义容器服务之间启动/关闭的依赖关系 分为长语法或者短语法 短语语法的实例的含义是： db和redis在web构建前创建 Web 在db 和 redis 之前删除。 长语法 长语法形式允许配置在短语法中无法表达的额外字段。 长语法实例的含义 Compose 按照依赖顺序创建服务。在以下示例中，db 和 redis 在 web 之前创建。 Compose 等待标记为 service_healthy 的依赖上的健康检查通过。在以下示例中，db 需要在 web 创建之前被认为是“健康”的。 Compose 按照依赖顺序删除服务。在以下示例中，web 在 db 和 redis 之前删除。	services:   web:     build: .     depends_on:       - db       - redis   redis:     image: redis   db: image: postgres services:   web:     build: .     depends_on:       db:         condition: service_healthy         restart: true       redis:         condition: service_started   redis:     image: redis   db:     image: postgres
device_cgroup_rules	定义了此容器的设备 cgroup 规则列表。该格式与 Linux 内核在控制组设备白名单控制器中指定的格式相同。该字段直接使用了Linux内核的cgroup命名空间，如果对cgroup不熟悉，建议不要轻易使用	device_cgroup_rules:   - 'c 1:3 mr'   - 'a 7:* rmw'
devices	把本地的硬件设备（例如USB，硬盘）映射到容器中	devices: -"/dev/ttyUSB0:/dev/ttyUSB0"   - "/dev/sda:/dev/xvda:rwm"
dns	设置容器的DNS，可以是一个，也可以是多个	dns:   - 8.8.8.8   - 9.9.9.9
dns_opt	通过列表的方式自定义DNS选项，这些选项将被传递到容器的 DNS 解析器（在 Linux 上的 /etc/resolv.conf 文件）。	dns_opt:   - use-vc   - no-tld-query
dns_search	定义容器的DNS搜索域	dns_search:   - dc1.example.com   - dc2.example.com
domainname	声明容器的域名，遵循RFC 1123标准（就是常见域名样式）	dns_search:   - dc1.example.com   - dc2.example.com
entrypoint	定义容器启动时的入口点，与Dockerfile的ENTRYPOINT 指令功能相同，优先级高于Dockerfile，可以执行多个命令 如果该值为 null，则使用镜像中的默认入口点。 如果该值为 []（空列表）或 ‘’（空字符串），则忽略镜像中声明的默认入口点，即被覆盖为空。	entrypoint:   - php   - -d   - -d   - memory_limit=-1   - vendor/bin/phpunit
env_file （正常情况下）	加载环境变量文件到容器 如果是多个环境变量文件，则是按顺序加载，对于两个 env_file 中指定的同一变量，列表中最后一个文件的值将生效。 列表元素也可以声明为映射，这样就可以设置一个额外的属性 required，默认值为 true。当 required 设置为 false 且 .env 文件缺失时，Compose 会静默忽略该条目。 引用环境变量文件时，官方建议使用相对路径，绝对路径会影响容器的可移植性，compose会给出警告。 环境变量文件的书写格式： Env_file 格式 每个 .env 文件中的行都必须以 VAR[=[VAL]] 格式出现。以下语法规则适用： 以 # 开头的行被视为注释并忽略。 空行被忽略。 Unquoted and double-quoted (") values have Interpolatio applied.（有时候真的觉得英语这表示真是恶心。如果采用直译的话会很拗口，所以这段我采用了我的理解。） 不带引号和双引号（"）都表示一个值。 每行代表一个键值对。值可以有选择性地被引号包围。 不带引号值的注释必须紧跟一个空格。 双引号值的内联注释必须紧跟闭合的双引号。 单引号（'）值按字面意思使用。 可以用 \ 转义引号。 在双引号值中支持包括 \n, \r, \t 和 \ 的常见 shell 转义序列。 VAL 可以省略，在这种情况下，变量的值是空字符串。=VAL 可以省略，在这种情况下，变量被取消设置。	env_file:   - ./a.env   - ./b.env env_file:   - path: ./default.env     required: true # default   - path: ./override.env required: false VAR=VAL -> VAL VAR=“VAL” -> VAL VAR=‘VAL’ -> VAL VAR=VAL # 注释 -> VAL VAR=VAL# 不是注释 -> VAL# 不是注释 VAR=“VAL # 不是注释” -> VAL # 不是注释 VAR=“VAL” # 注释 -> VAL VAR=“some\tvalue”->some value VAR=‘some\tvalue’->some\tvalue VAR=some\tvalue -> some\tvalue
environment	直接定义容器的环境变量 可以使用任意值，任何布尔值（true、false、yes、no）都应被引号包围，以确保它们不被 YAML 解析器转换为 True 或 False。环境变量可以通过一个键（不用等号）来声明。在这种情况下，Compose 依赖于你赋予的解析值，如果值没有解析出来，变量将被取消设置，并从服务容器环境中移除。 当为服务设置了 env_file 和 environment 时，environment的值优先。	映射的形式 environment:   RACK_ENV: development   SHOW: "true"   USER_INPUT: 数组的形式 environment:   - RACK_ENV=development   - SHOW=true   - USER_INPUT
expose	从容器中公开的端口。这些端口供相互链接的服务访问，但不会发布到宿主机上。只能指定容器内部的端口，且默认协议为 TCP。端口的值可以是单个端口号，也可以是端口范围，并且可以选择协议类型。左边的样例中3个值均是有效的	expose:   - "3000"   - "8000"   - "8080-8085/tcp
Extends（这个键值看官方的文档描述是非常拗口的，而且使用这个会有循环依赖的问题，因此官方给这个关键词加了很多限制条件，所以在实践过程中，不推荐使用依赖文件进行配置的复用，万一哪天你依赖的基础配置文件不见了，那你就慢慢排查报错吧。）	容器配置的继承。通过使用 extends，你可以在一个文件中定义一组服务的通用配置，然后在其他文件或项目中引用这些配置。引用时，你可以选择性地覆盖某些配置属性以适应特定的需求。extends 的使用不限于特定的服务，可以与其他配置键结合使用。在定义 extends 时，需要指定要继承的服务，以及可选的配置文件路径。 使用该字段时，必须包含”service ”和”file”两个关键字	extends:   file: common.yml   service: webapp
注意事项 Restrictions 限制条件	不能将依赖于其他服务的服务作为基础服务。因此，任何引入对另一个服务依赖的键都与 extends 不兼容。 这类键包括（包括但不限于）： links, volumes_from, container 标签（在 ipc, pid, network_mode 和 net ），service标签（在 ipc, pid 和 network_mode），depends_on。 服务不能通过 extends 有循环引用。 出现以上情况，Compose 都会返回一个错误
被引用的 file	值可以是： None。这表明正在引用同一 Compose 文件中的另一个服务。 文件路径，可以是： 相对路径。这个路径被认为是相对于主 Compose 文件的位置。 绝对路径。 在识别的引用 Compose 文件中必须存在由 service 指定的服务。如果发生以下情况，Compose 将返回一个错误： 指定的服务未找到。 指定的 Compose 文件未找到。
合并service的定义	当前 Compose 文件中的主服务定义和通过 extends 指定的被引用服务定义，按照以下方式合并： 映射（Mappings）：主服务定义中的映射键会覆盖被引用服务定义中的映射键。未覆盖的键将原样包含。 序列（Sequences）：项目被组合成一个新的序列。元素的顺序被保留，首先是引用的项目，然后是主项目。 标量（Scalars）：主服务定义中的键优先于被引用服务定义中的键。

 服务(Service)标签完整实例

Blkio_config配置文件实例（完整）

1.services:
2.  foo:
3.    image: busybox
4.    blkio_config:
5.       weight: 300
6.       weight_device:
7.         - path: /dev/sda
8.           weight: 400
9.       device_read_bps:
10.         - path: /dev/sdb
11.           rate: '12mb'
12.       device_read_iops:
13.         - path: /dev/sdb
14.           rate: 120
15.       device_write_bps:
16.         - path: /dev/sdb
17.           rate: '1024k'
18.       device_write_iops:
19.         - path: /dev/sdb
20.           rate: 30