Compose构建规范

构建是 Compose 规范的可选部分。它告诉 Compose 如何从源代码（重新）构建应用程序，并允许您以可移植的方式在 Compose 文件中定义构建过程。build 可以指定为定义上下文路径的单个字符串，也可以指定为详细的构建定义。

在前一种情况下，整个路径用作 Docker 上下文来执行 Docker 构建，并在目录的根目录中查找规范的Dockerfile。路径可以是绝对路径或相对路径。如果它是相对路径，则从包含 Compose 文件的目录解析。如果它是绝对路径，则该路径会阻止 Compose 文件的可移植性，因此 Compose 会显示警告。

在后一种情况下，可以指定构建参数，包括备用的Dockerfile 位置。路径可以是绝对路径或相对路径。如果它是相对路径，则从包含 Compose 文件的目录解析。如果它是绝对路径，则该路径会阻止 Compose 文件的可移植性，因此 Compose 会显示警告。

使用build 和 image

当 Compose 同时遇到服务的build 子部分和image 属性时，它将遵循pull_policy 属性定义的规则。

如果服务定义中缺少pull_policy，Compose 将首先尝试拉取镜像，然后在注册表或平台缓存中找不到镜像时再从源代码构建。

发布构建的镜像

支持build 的 Compose 提供了一个将构建的镜像推送到注册表的选项。这样做时，它不会尝试推送没有image 属性的服务镜像。Compose 会警告您缺少的image 属性，这会阻止镜像被推送。

示例

以下示例使用具体的示例应用程序说明了 Compose 构建规范的概念。此示例是非规范性的。

services:
  frontend:
    image: example/webapp
    build: ./webapp

  backend:
    image: example/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom

当用于从源代码构建服务镜像时，Compose 文件会创建三个 Docker 镜像

• example/webapp：使用 Compose 文件父文件夹中的webapp 子目录作为 Docker 构建上下文构建 Docker 镜像。此文件夹中缺少Dockerfile 将引发错误。
• example/database：使用 Compose 文件父文件夹中的backend 子目录构建 Docker 镜像。backend.Dockerfile 文件用于定义构建步骤，此文件相对于上下文路径进行搜索，这意味着.. 解析为 Compose 文件的父文件夹，因此backend.Dockerfile 是同级文件。
• 使用custom 目录和用户的 HOME 作为 Docker 上下文构建 Docker 镜像。Compose 会显示一条警告，提示构建镜像时使用了不可移植的路径。

推送时，example/webapp 和 example/database Docker 镜像都会被推送到默认注册表。custom 服务镜像将被跳过，因为未设置image 属性，并且 Compose 会显示有关此缺少属性的警告。

属性

build 子部分定义了 Compose 用于从源代码构建 Docker 镜像的配置选项。build 可以指定为包含构建上下文路径的字符串，也可以指定为详细的结构

使用字符串语法，只能配置构建上下文为：

• Compose 文件父文件夹的相对路径。此路径必须是目录，并且必须包含Dockerfile

  services:
    webapp:
      build: ./dir

• Git 存储库 URL。Git URL 在其片段部分接受上下文配置，用冒号 (:) 分隔。第一部分表示 Git 签出的引用，可以是分支、标签或远程引用。第二部分表示用作构建上下文的存储库内的子目录。

  services:
    webapp:
      build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory

或者，build 可以是一个对象，其字段定义如下

additional_contexts

additional_contexts 定义镜像构建器在镜像构建期间应使用的命名上下文的列表。

additional_contexts 可以是映射或列表

build:
  context: .
  additional_contexts:
    - resources=/path/to/resources
    - app=docker-image://my-app:latest
    - source=https://github.com/myuser/project.git

build:
  context: .
  additional_contexts:
    resources: /path/to/resources
    app: docker-image://my-app:latest
    source: https://github.com/myuser/project.git

用作列表时，语法遵循NAME=VALUE 格式，其中VALUE 是字符串。除此之外的验证由镜像构建器负责（并且是构建器特定的）。Compose 至少支持指向目录的绝对路径和相对路径以及 Git 存储库 URL，就像context 一样。其他上下文类型必须加前缀以避免与type:// 前缀产生歧义。

如果镜像构建器不支持其他上下文，Compose 会向您发出警告，并可能列出未使用的上下文。

可以在此处找到 Buildx 如何使用此功能的示例。

args

args 定义构建参数，即 Dockerfile ARG 值。

例如，使用以下 Dockerfile

ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"

可以在build 密钥下的 Compose 文件中设置args 来定义GIT_COMMIT。args 可以设置为映射或列表

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19

build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

在指定构建参数时可以省略值，在这种情况下，其构建时的值必须通过用户交互获得，否则在构建 Docker 镜像时不会设置构建参数。

args:
  - GIT_COMMIT

context

context 定义包含 Dockerfile 的目录的路径，或指向 git 存储库的 URL。

当提供的值为相对路径时，它将被解释为相对于项目目录。Compose 会警告您用于定义构建上下文的绝对路径，因为这些路径会阻止 Compose 文件的可移植性。

build:
  context: ./dir

services:
  webapp:
    build: https://github.com/mycompany/webapp.git

如果未显式设置，context 默认值为项目目录 (.)。

cache_from

cache_from 定义镜像构建器应用于缓存解析的源列表。

缓存位置语法遵循全局格式[NAME|type=TYPE[,KEY=VALUE]]。简单的NAME 实际上是type=registry,ref=NAME 的快捷表示法。

Compose 构建实现可能支持自定义类型，Compose 规范定义了必须支持的规范类型

• registry 用于从由键ref 设置的 OCI 镜像中检索构建缓存

build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

不支持的缓存将被忽略，并且不会阻止您构建镜像。

cache_to

cache_to 定义要用于与将来的构建共享构建缓存的导出位置列表。

build:
  context: .
  cache_to:
   - user/app:cache
   - type=local,dest=path/to/cache

缓存目标使用cache_from 定义的相同type=TYPE[,KEY=VALUE] 语法定义。

不支持的缓存将被忽略，并且不会阻止您构建镜像。

dockerfile

dockerfile 设置备用 Dockerfile。相对路径将从构建上下文解析。Compose 会警告您用于定义 Dockerfile 的绝对路径，因为它会阻止 Compose 文件的可移植性。

设置后，不允许使用dockerfile_inline 属性，Compose 将拒绝同时设置这两个属性的任何 Compose 文件。

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline

dockerfile_inline 将 Dockerfile 内容定义为 Compose 文件中的内联字符串。设置后，不允许使用dockerfile 属性，Compose 将拒绝同时设置这两个属性的任何 Compose 文件。

建议使用 YAML 多行字符串语法来定义 Dockerfile 内容

build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN some command    

entitlements

entitlements 定义在构建过程中允许的额外特权权限。

entitlements:
  - network.host
  - security.insecure

extra_hosts

extra_hosts 在构建时添加主机名映射。使用与extra_hosts相同的语法。

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"

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

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

isolation

isolation 指定构建的容器隔离技术。与isolation类似，支持的值是特定于平台的。

labels

labels 向生成的镜像添加元数据。labels 可以设置为数组或映射。

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

build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""

build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

network

设置构建期间RUN 指令连接的网络容器。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

使用none 禁用构建期间的网络。

build:
  context: .
  network: none

no_cache

no_cache 禁用镜像构建缓存，并强制对所有镜像层从源代码进行完全重建。这仅适用于Dockerfile中声明的层，只要注册表上的标签已更新，就可以从本地镜像存储中检索引用的镜像（参见pull）。

platforms

platforms 定义目标平台列表。

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"

省略platforms 属性时，Compose 将服务的平台包含在默认构建目标平台列表中。

定义platforms 属性时，Compose包含服务的平台，否则用户将无法运行他们构建的镜像。

在以下情况下，Compose会报告错误

• 列表包含多个平台，但实现无法存储多平台镜像。

• 列表包含不受支持的平台。

  build:
    context: "."
    platforms:
      - "linux/amd64"
      - "unsupported/unsupported"

• 列表非空且不包含服务的平台。

  services:
    frontend:
      platform: "linux/amd64"
      build:
        context: "."
        platforms:
          - "linux/arm64"

privileged

privileged 将服务镜像配置为以提升的权限进行构建。支持和实际影响是特定于平台的。

build:
  context: .
  privileged: true

pull

pull 要求镜像构建器拉取引用的镜像（FROM Dockerfile 指令），即使这些镜像已存在于本地镜像存储中。

secrets

secrets 按服务构建为基础，授予对由secrets定义的敏感数据的访问权限。支持两种不同的语法变体：简短语法和长语法。

如果在该Compose文件的secrets部分中未定义密钥，则Compose会报告错误。

简短语法

简短语法变体仅指定密钥名称。这允许容器访问密钥，并将其作为只读方式挂载到容器内的/run/secrets/<secret_name>。源名称和目标挂载点都设置为密钥名称。

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

services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

长语法

长语法提供了更细粒度的控制，用于在服务的容器内创建密钥。

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

以下示例将server-certificate 密钥文件的名称设置为容器内的server.crt，将模式设置为0440（组可读），并将用户和组设置为103。server-certificate 密钥的值由平台通过查找提供，密钥生命周期不是由Compose直接管理的。

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: server.cert
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true

服务构建可以被授予对多个密钥的访问权限。可以在同一个Compose文件中使用密钥的长语法和简短语法。在顶级secrets 中定义密钥并不意味着授予任何服务构建对其的访问权限。此类授权必须在服务规范中作为secrets 服务元素明确指定。

ssh

ssh 定义镜像构建器在镜像构建期间（例如，克隆私有存储库）应使用的SSH身份验证。

ssh 属性语法可以是

• default：让构建器连接到SSH代理。
• ID=path：ID及其关联路径的键/值定义。它可以是PEM文件，或SSH代理套接字的路径。

build:
  context: .
  ssh:
    - default   # mount the default SSH agent

或者

build:
  context: .
  ssh: ["default"]   # mount the default SSH agent

使用自定义ID myproject 和本地SSH密钥的路径

build:
  context: .
  ssh:
    - myproject=~/.ssh/myproject.pem

然后，镜像构建器可以依靠它在构建期间挂载SSH密钥。

为了说明，SSH 挂载 可用于挂载由ID设置的SSH密钥并访问安全资源。

RUN --mount=type=ssh,id=myproject git clone ...

shm_size

shm_size 设置为构建Docker镜像分配的共享内存（Linux上的/dev/shm 分区）的大小。指定为表示字节数的整数，或指定为表示字节值的字符串。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

tags

tags 定义必须与构建镜像关联的标签映射列表。此列表除了服务部分中定义的image属性之外。

tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"

target

target 定义要在多阶段Dockerfile 中构建的阶段。

build:
  context: .
  target: prod

ulimits

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

services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000