Compose 构建规范

目录

build 是 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 是一个同级文件。
  • 以用户的 $HOME 中的 custom 目录作为 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

要求： 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，类似于 context 的用法。其他类型的上下文必须加上前缀 type:// 以避免歧义。

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

关于如何在 Buildx 中使用此功能的示例说明可以在这里找到。

additional_contexts 也可以引用由另一个服务构建的镜像。这使得可以使用另一个服务镜像作为基础镜像来构建服务镜像，并在服务镜像之间共享层。

services:
 base:
  build:
    context: .
    dockerfile_inline: |
      FROM alpine
      RUN ...
 my-service:
  build:
    context: .
    dockerfile_inline: |
      FROM base # image built for service base
      RUN ...
    additional_contexts:
      base: service:base

args

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

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

entitlements

要求： 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

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

要求： Docker Compose 2.15.0 及更高版本

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

build:
  context: .
  privileged: true

pull

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

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。默认值为 USER。
  • mode：将在服务的任务容器中挂载到 /run/secrets/ 的文件权限，以八进制表示法。默认值为全局可读权限（模式 0444）。如果设置了可写位，必须忽略。可执行位可以设置。

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

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

服务构建可以被授予访问多个 secrets 的权限。secrets 的长语法和短语法可以在同一个 Compose 文件中使用。在顶级 secrets 中定义一个 secret 不应暗示授予任何服务构建访问它的权限。此类授予必须在服务规范中明确指定，作为 secrets 服务元素。

ssh

ssh 定义了镜像构建器在镜像构建期间应使用的 SSH 认证信息（例如，克隆私有仓库）。

ssh 属性的语法可以是：

  • default：让构建器连接到 SSH-agent。
  • ID=path：一个 ID 及其关联路径的键/值定义。它可以是一个 PEM 文件，或 ssh-agent socket 的路径。
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 mounts 可用于挂载由 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

要求： Docker Compose 2.23.1 及更高版本

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

services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000
页面选项