切换语言

Compose Build 规范

目录

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

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

在后一种情况下，可以指定 build 参数，包括替代Dockerfile位置。路径可以是绝对路径，也可以是相对路径。如果是相对的，则解析 从包含 Compose 文件的目录中。如果为 absolute，则路径会阻止 Compose 文件可移植，因此 Compose 会显示警告。

用build和image

当 Compose 同时遇到buildsubsection 表示服务，而image属性，它遵循pull_policy属性。

如果pull_policy，则 Compose 会先尝试提取镜像，然后在注册表或平台缓存中找不到镜像，然后从源构建镜像。

发布构建的镜像

编写方式buildSupport 提供了一个选项，用于将构建的镜像推送到注册表。执行此作时，它不会尝试在没有image属性。Compose 会警告您缺少image属性，以防止推送镜像。

说明示例

以下示例通过具体示例应用程序说明了 Compose Build Specification 概念。样本是非规范的。

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子目录中，作为 Docker 构建上下文。缺少Dockerfile在此文件夹中引发错误。
  • example/database：Docker 镜像是使用backend子目录中。backend.Dockerfilefile 用于定义构建步骤，则此文件将相对于上下文路径进行搜索，这意味着..resolves 解析为 Compose 文件的父文件夹，因此backend.Dockerfile是同级文件。
  • Docker 镜像是使用custom目录中，并将用户的 HOME 作为 Docker 上下文。Compose 会显示一条警告，说明用于构建镜像的非可移植路径。

按下时，两者example/webapp和example/databaseDocker 镜像被推送到默认注册表。这custom服务镜像被跳过，因为 noimage属性，并且 Compose 会显示有关此缺失属性的警告。

属性

这buildsubsection 定义 Compose 应用于从源构建 Docker 镜像的配置选项。build可以指定为包含生成上下文路径的字符串，也可以指定为详细结构：

使用 string 语法，只能将构建上下文配置为：

  • 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可以是 mapping 或 list：

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 中找到如何在 Buildx 中使用它的说明性示例。

参数

args定义构建参数，即 DockerfileARG值。

以以下 Dockerfile 为例：

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

args可以在 Compose 文件中的build键来定义GIT_COMMIT.args可以设置为 map 或 list：

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

指定 build 参数时可以省略 values，在这种情况下，它在 build 时的值必须由用户交互获取。 否则，在构建 Docker 镜像时不会设置 build arg。

args:
  - GIT_COMMIT

上下文

context定义包含 Dockerfile 的目录的路径或 Git 仓库的 URL。

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

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

如果未显式设置，则context默认为 project directory （.).

cache_from

cache_from定义镜像生成器应用于缓存分辨率的源列表。

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

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

  • registry从键设置的 OCI 镜像中检索构建高速缓存ref
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

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

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

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]"

separator 是首选，但=:也可以使用。在 Docker Compose 版本 2.24.1 中引入。例如：

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

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

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

隔离

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

标签

labels将元数据添加到生成的镜像中。labels可以设置为 array 或 map。

建议您使用反向 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禁用 Image Builder 缓存，并对所有 Image 图层强制从源进行完全重建。仅此 适用于 Dockerfile 中声明的层，无论何时标记，都可以从本地镜像存储中检索引用的镜像 已在 Registry 上更新（参见 pull）。

平台

platforms定义目标平台的列表。

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

当platforms属性，则 Compose 会包含该服务的平台 在 Default Build Target platforms 列表中。

当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需要镜像生成器提取引用的镜像 （FROMDockerfile 指令），即使这些指令已经是 在本地镜像存储中可用。

秘密

secrets基于每个服务构建授予对 secret 定义的敏感数据的访问权限。二 支持不同的语法变体：短语法和长语法。

如果未在secrets部分。

短语法

短语法变体仅指定密钥名称。这将授予 容器访问密钥并将其作为只读挂载到/run/secrets/<secret_name>在容器内。源名称和目标挂载点均已设置 添加到密钥名称。

以下示例使用 short 语法授予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：拥有其中文件的数字 UID 或 GID/run/secrets/在服务的任务容器中。默认值为 USER running container。
  • mode：要挂载的文件的权限/run/secrets/在服务的任务容器中，采用八进制表示法。 默认值为全局可读权限（模式0444). 如果设置了 writable bit，则必须忽略该 writable bit 。可以设置可执行位。

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

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

可以向服务构建授予对多个密钥的访问权限。secret 的 long 和 short 语法可以在 相同的 Compose 文件。在顶级中定义密钥secrets不得暗示授予对它的任何 Service Build 访问权限。 此类授权必须在服务规范中作为 secrets 服务元素显式指定。

ssh

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

sshproperty 语法可以是：

  • default：让生成器连接到 SSH 代理。
  • ID=path：ID 和关联路径的键/值定义。它可以是 PEM 文件，也可以是 ssh-agent 套接字的路径。
build:
  context: .
  ssh:
    - default   # mount the default SSH agent

或

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

使用自定义 IDmyproject替换为本地 SSH 密钥的路径：

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

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

例如，SSH 挂载可用于挂载由 ID 设置的 SSH 密钥并访问受保护的资源：

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

shm_size

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

build:
  context: .
  shm_size: '2gb'
build:
  context: .
  shm_size: 10000000

标签

tags定义必须与构建镜像关联的标签映射列表。此列表是对 这image service 部分中定义的属性

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