切换语言

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 提供了一个将构建的镜像推送到 registry 的选项。这样做时，它不会尝试推送没有 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: Docker 镜像是使用 webapp 子目录构建的，该子目录位于 Compose 文件的父文件夹内，作为 Docker 构建上下文。如果此文件夹中缺少 Dockerfile，则会引发错误。
  • example/database: Docker 镜像是使用 Compose 文件父文件夹中的 backend 子目录构建的。backend.Dockerfile 文件用于定义构建步骤，该文件是相对于上下文路径进行搜索的，这意味着 .. 解析为 Compose 文件的父文件夹，因此 backend.Dockerfile 是一个同级文件。
  • Docker 镜像是使用 custom 目录构建的，并以用户的 HOME 目录作为 Docker 上下文。Compose 会显示一条关于构建镜像时使用了非可移植路径的警告。

推送时，example/webapp 和 example/database 两个 Docker 镜像被推送到默认注册表。由于未设置 image 属性，custom 服务镜像被跳过，Compose 会针对此缺失属性显示警告。

属性

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

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

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

    services:
  webapp:
    build: ./dir

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

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

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

additional_contexts

引入于 Docker Compose 版本 2.17.0

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，就像 上下文 那样。其他上下文类型 必须添加前缀以避免与 type:// 前缀产生歧义。

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

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

参数

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

以以下 Dockerfile 为例：

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

args 可以在 Compose 文件中的 build 键下设置，以定义 GIT_COMMIT。args 可以设置为映射或列表：

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

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

args:
  - GIT_COMMIT

上下文

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 Build 实现可能支持自定义类型，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

引入于 Docker Compose 版本 2.17.0

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

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

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

授权

引入于 Docker Compose 版本 2.27.1

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 指定构建的容器隔离技术。就像 隔离，支持的值 是平台特定的。

标签

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"

网络

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

build:
  context: .
  network: host
build:
  context: .
  network: custom_network_1

在构建期间使用 none 来禁用网络：

build:
  context: .
  network: none

no_cache

no_cache 禁用镜像构建器缓存，并强制对所有镜像层从源代码进行完整重建。这仅适用于 Dockerfile 中声明的层，只要标签在仓库中更新，引用的镜像就可以随时从本地镜像存储中检索（参见 拉取）。

平台

platforms 定义了一个目标 平台列表。

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

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

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

Composes 在以下情况下报告错误：

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

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

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

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

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

特权

Docker Compose 版本引入 2.15.0

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

build:
  context: .
  privileged: true

拉取

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

密钥

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。默认值为运行容器的 USER。
  • 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 认证（例如，克隆私有仓库）。

  • default: 让构建器连接到 SSH-agent。
  • ID=path: ID 和相关路径的键值对定义。它可以是 PEM 文件，或者是 ssh-agent 套接字的路径。
build:
  context: .
  ssh:
    - default   # mount the default SSH agent

or

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 定义了必须与构建镜像关联的标签映射列表。此列表是对 image 服务部分中定义的属性的补充

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

目标

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

build:
  context: .
  target: prod

ulimits

引入于 Docker Compose 版本 2.23.1

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

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