docker-compose文件属性（14）build

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

在前一种情况下，整个路径将被用作 Docker 上下文来执行 Docker 构建，并在该目录的根目录中寻找默认的 Dockerfile。该路径可以是绝对路径或相对路径。如果是相对路径，则从包含 Compose 文件的目录开始解析。如果是绝对路径，则会影响 Compose 文件的便携性，因此 Compose 会显示警告。

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

执行命令docker compose build会根据build的信息进行镜像的构建，但是docker compose up会构建但是不应用tags。docker stack deploy不会构建。

# 以下情况会触发构建：
docker compose up                    # 镜像不存在时
docker compose up --build           # 强制构建
docker compose up --no-build        # 不构建（仅当镜像存在时可用）

# 以下情况不会构建：
docker compose up                   # 镜像已存在且是最新

使用 build 和 image

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

如果服务定义中缺少 pull_policy，Compose 会首先尝试拉取镜像；如果该镜像在镜像仓库或平台缓存中找不到，则从源代码构建。

推送构建镜像

支持构建的 Compose 提供了一个选项，可以将构建好的镜像推送到镜像仓库。执行此操作时，它不会尝试推送没有 image 属性的服务镜像。Compose 会警告你缺少 image 属性，这会导致镜像无法被推送。

说明示例

version: '3.8'

services:
  webapp:
    image: example/webapp          # 镜像名 1
    build: ./webapp                # 构建上下文：当前目录下的 webapp 子目录
    # 预期在 ./webapp/Dockerfile 找到构建文件

  database:
    image: example/database        # 镜像名 2
    build: 
      context: ./backend           # 构建上下文：当前目录下的 backend 子目录
      dockerfile: ../backend.Dockerfile # Dockerfile 路径：回到上一级，找与 backend 目录同级的文件
    # 这里比较特殊：context 是 ./backend，但 dockerfile 是 ../backend.Dockerfile
    # 这意味着构建时，只有 ./backend 下的文件会发送给 Docker 守护进程作为上下文
    # 但指令从 ./backend.Dockerfile 这个上层文件读取

  custom:
    # 注意：这里没有 image 属性！
    build: ~/custom                # 构建上下文：绝对路径，指向用户家目录下的 custom 目录
    # 预期在 ~/custom/Dockerfile 找到构建文件

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

example/webapp：使用 webapp 子目录（位于 Compose 文件所在文件夹内）作为 Docker 构建上下文构建 Docker 镜像。如果此文件夹内缺少 Dockerfile 文件，则会返回错误。

example/database：使用 backend 子目录（位于 Compose 文件所在文件夹内）构建 Docker 镜像。使用 backend.Dockerfile 文件来定义构建步骤；该文件是相对于上下文路径（即 backend 目录）来查找的。这意味着 .. 会解析到 Compose 文件所在的文件夹，因此 backend.Dockerfile 实际上是一个同级文件。

一个 Docker 镜像使用 custom 目录构建，并以用户的 $HOME 目录作为 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 可以是一个对象，其字段定义如下：

1、additional_contexts

需要Docker Compose 2.17.0及以上版本。定义了一个命名上下文的列表，镜像构建器在构建镜像时应使用这些上下文。其值可以是一个映射或者列表：

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:// 格式）以避免歧义。

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

有关示例用法，请参考 docker buildx build --build-context 的参考文档。

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

2、args

定义了构建参数，即 Dockerfile 中的 ARG 值。

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

#在Compose文件 build 键下面设置args属性定义GIT_COMMIT 参数。args值可以是映射也可以是列表
build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
    
build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

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

args:
  - GIT_COMMIT

3、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

不受支持的缓存类型会被忽略，不会阻止你构建镜像。

4、cache_to

定义了一个导出位置列表，用于与未来的构建共享构建缓存

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

缓存目标使用与 cache_from 定义的相同的 type=TYPE[,KEY=VALUE] 语法来定义。不受支持的缓存会被忽略，不会阻止您构建镜像。

cache_to 支持的所有类型与 cache_from 完全一致：

|--------------|-------------------------------|----------------------------------------|----------------|
| 类型 | cache_from 示例 | cache_to 示例 | 说明 |
| registry | type=registry,ref=myapp:cache | type=registry,ref=myapp:cache,mode=max | 镜像仓库 |
| local | type=local,src=./cache | type=local,dest=./cache,mode=max | 本地目录 |
| gha | type=gha | type=gha,mode=max | GitHub Actions |
| s3 | type=s3,bucket=mycache | type=s3,bucket=mycache,mode=max | AWS S3 |
| azblob | type=azblob,container=cache | type=azblob,container=cache,mode=max | Azure Blob |
| inline | N/A（仅输出） | type=inline | 内联缓存 |

各类型说明对应的具体格式如下：

1. type=local：本地缓存，将构建缓存直接写入本地文件系统，使用 BuildKit 的本地缓存存储格式，创建特殊的缓存清单文件和层数据文件，

零网络延迟：直接磁盘读写；完全控制：无需外部权限；空间管理：需手动清理旧缓存；不可共享：仅限于单机使用

- type=local,dest=${WORKSPACE_CACHE}
存储位置：
${WORKSPACE_CACHE} 目录结构示例：
├── index.json              # 缓存索引清单
├── manifest.json           # 缓存清单描述
├── blobs/                  # 实际缓存层数据
│   ├── sha256:abc123...    # 镜像层二进制数据
│   └── sha256:def456...
└── ingest/                 # 写入时的临时目录

cache_from（读取）

- type=local,src=/path/to/cache

|----------|----|-----------|--------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 local | local |
| src | 是 | 源目录路径 | ./.cache |
| readonly | 否 | 只读模式 | true / false |

cache_to（写入）

- type=local,dest=/path/to/cache,mode=max

|-------------|----|-----------|-------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 local | local |
| dest | 是 | 目标目录路径 | ./.cache |
| mode | 否 | 缓存模式 | min , max |
| compression | 否 | 压缩算法 | gzip , zstd |

1. type=registry：将缓存打包为特殊的Docker镜像推送到仓库，镜像包含缓存清单和层数据，使用 OCI 镜像规范存储。多人可访问同一缓存，支持标签和摘要，需要仓库访问权限，与普通镜像兼容

   • type=registry,ref=${TEAM_REGISTRY}/cache/shared

   Docker Registry 中的特殊镜像：
   ${TEAM_REGISTRY}/cache/shared:latest
   ├── config blob # 缓存配置（约1KB）
   ├── layer 0 # 缓存清单（JSON格式）
   ├── layer 1 # 实际缓存数据层1
   ├── layer 2 # 实际缓存数据层2
   └── ...

cache_from（读取）

- type=registry,ref=myregistry.com/myapp:cache

|----------------|----|--------------|--------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 registry | registry |
| ref | 是 | 镜像引用地址 | myapp:cache |
| compression | 否 | 压缩算法 | gzip , zstd |
| oci-mediatypes | 否 | 使用 OCI 媒体类型 | true / false |

cache_to（写入）

- type=registry,ref=myapp:cache,mode=max,compression=zstd

|----------------|----|--------------|-----------------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 registry | registry |
| ref | 是 | 镜像引用地址 | myapp:cache |
| mode | 否 | 缓存模式 | min , max |
| compression | 否 | 压缩算法 | gzip , zstd , estargz |
| oci-mediatypes | 否 | 使用 OCI 媒体类型 | true / false |
| image-manifest | 否 | 是否创建镜像清单 | true / false |

1. type=s3：使用 S3 对象存储作为缓存后端，BuildKit 将缓存数据序列化为对象，支持多部分上传和并行下载。无缝集成 AWS 生态，自动扩容，无需管理，IAM 策略、加密、版本控制，仅支付实际使用量。

   • type=s3,region={COMPANY_REGION},bucket=dept-backup,prefix={TEAM}

   S3 Bucket 结构：
   s3://dept-backup/
   └── ${TEAM}/ # 团队前缀
   ├── manifests/ # 缓存清单
   │ └── latest.json # 最新缓存引用
   ├── blobs/ # 缓存数据块
   │ ├── sha256:xxx/ # 按哈希分目录
   │ └── sha256:yyy/
   └── index/ # 索引文件

2. type=azblob：使用 Azure Blob Storage 存储缓存，与 S3类似但使用 Azure 专属 API，支持块 blob 和追加 blob

内置审计日志，与 Active Directory 集成，支持热/冷/归档层，自动生命周期管理

- type=azblob,account=compliance,container=audit-trail,prefix=${PROJECT}/${DATE}

Azure Blob Container 结构：
https://compliance.blob.core.windows.net/audit-trail/
└── ${PROJECT}/${DATE}/     # 项目/日期前缀
    ├── index.json          # 缓存索引
    ├── manifest/           # 清单文件
    └── blobs/              # 数据块

cache_from（读取）

- type=azblob,account=mystorage,container=cache

|-------------------|----|------------|------------------------------------------------------------------------------------------------------------------------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 azblob | azblob |
| account | 是 | 存储账户名称 | mystorage |
| container | 是 | 容器名称 | build-cache |
| account_url | 否 | 账户 URL | https://mystorage.blob.core.windows.net |
| prefix | 否 | Blob 前缀 | project/cache/ |
| secret_access_key | 否 | 访问密钥 | ${AZURE_STORAGE_KEY} |

cache_to（写入）

- type=azblob,account=mystorage,container=cache

|-------------------|----|------------|----------------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 azblob | azblob |
| account | 是 | 存储账户名称 | mystorage |
| container | 是 | 容器名称 | build-cache |
| mode | 否 | 缓存模式 | min , max |
| prefix | 否 | Blob 前缀 | project/cache/ |
| secret_access_key | 否 | 访问密钥 | ${AZURE_STORAGE_KEY} |

1. type=gha：缓存专门为 GitHub Actions 工作流设计，它利用 GitHub 的缓存服务来存储和恢复构建缓存。

cache_from（读取）

- type=gha

|-------|----|----------|------------------------------------------------------------------------------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 gha | gha |
| scope | 否 | 缓存范围 | workflow , branch , ref |
| url | 否 | 自定义缓存服务器 | https://cache.example.com |
| token | 否 | 认证令牌 | ${GITHUB_TOKEN} |

cache_to（写入）

- type=gha,mode=max,scope=branch

|-------|----|----------|------------------------------------------------------------------------------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 gha | gha |
| mode | 否 | 缓存模式 | min , max |
| scope | 否 | 缓存范围 | workflow , branch , ref |
| url | 否 | 自定义缓存服务器 | https://cache.example.com |
| token | 否 | 认证令牌 | ${GITHUB_TOKEN} |

1. type=inline：缓存是一种特殊类型的缓存，它将缓存数据直接嵌入到构建的镜像中，而不是存储在外部的独立位置。

仅支持 cache_to（写入）

cache_to:
  - type=inline

|-------------------|----|-------------|--------------|
| 参数 | 必填 | 说明 | 示例值 |
| type | 是 | 固定为 inline | inline |
| compression | 否 | 压缩算法 | gzip , zstd |
| force-compression | 否 | 强制压缩 | true / false |
| oci-mediatypes | 否 | 使用 OCI 媒体类型 | true / false |

注意：inline 不支持 cache_from，因为它不是独立的缓存源，而是从镜像中读取。

#1、通用性兼容配置
# 确保在任何环境下都能工作的配置
x-cache-safe: &cache-safe
  cache_from:
    - type=registry,ref=${PROJECT}:cache-latest
    - type=local,src=${LOCAL_CACHE:-./.cache}
  
  cache_to:
    - type=registry,ref=${PROJECT}:cache-latest,mode=max
    - type=local,dest=${LOCAL_CACHE:-./.cache},mode=max

services:
  app:
    build:
      context: .
      <<: *cache-safe
      
      
#2、环境感知配置
# 根据环境自动调整缓存策略
services:
  app:
    build:
      context: .
      cache_to:
        # 基础配置（所有环境）
        - type=local,dest=./.cache,mode=max
        
        # 条件性配置（仅在某些环境生效）
        - ${CI:+type=gha,mode=max,scope=${CI_REF}}
        - ${AWS_ACCESS_KEY_ID:+type=s3,region=${AWS_REGION},bucket=${CACHE_BUCKET},mode=max}
        - ${AZURE_STORAGE_KEY:+type=azblob,account=${AZURE_ACCOUNT},container=cache,mode=max}
        
        # 实验性功能（可能被忽略）
        - type=custom,url=${CUSTOM_CACHE_URL}

#3. 团队协作配置
# 适合不同技术栈团队成员的配置
cache_to:
  # 必需目标（所有人可用）
  - type=local,dest=./.cache
  
  # 团队共享目标（需要权限）
  - ${HAS_TEAM_ACCESS:+type=registry,ref=team-registry.com/shared/cache:${USER}}
  
  # 平台特定目标（按需使用）
  - ${USE_AWS:+type=s3,bucket=team-aws-cache}
  - ${USE_AZURE:+type=azblob,account=team-azure-cache}
  - ${USE_GCP:+type=gcs,bucket=team-gcp-cache}  # 自定义类型，可能被忽略
  
  # 调试目标
  - type=local,dest=/tmp/debug-cache  # 调试用，所有人可用
  
#4 企业标准配置模板
x-enterprise-cache: &enterprise-cache
  cache_to:
    # 个人工作区
    - type=local,dest=${WORKSPACE_CACHE}
    
    # 团队共享（基础架构团队维护）
    - type=registry,ref=${TEAM_REGISTRY}/cache/shared
    
    # 部门级备份（IT部门要求）
    - type=s3,region=${COMPANY_REGION},bucket=dept-backup,prefix=${TEAM}
    
    # 合规性归档（法务要求）
    - type=azblob,account=compliance,container=audit-trail,prefix=${PROJECT}/${DATE}

# 不同团队继承并定制
services:
  data-team-service:
    build:
      <<: *enterprise-cache
      cache_to:
        - *enterprise-cache.cache_to
        - type=s3,region=us-east-1,bucket=data-team-cache  # 数据团队专用
  
  web-team-service:
    build:
      <<: *enterprise-cache
      cache_to:
        - *enterprise-cache.cache_to
        - type=registry,ref=web-team-registry/cache  # Web团队专用

5、no_cache

会禁用镜像构建器的缓存，并强制从源代码完全重建所有镜像层。这仅适用于 Dockerfile 中声明的层，当镜像标签在镜像仓库中更新时，被引用的镜像仍然可以从本地镜像存储中检索（参见 pull 策略）。

6、context

定义了包含 Dockerfile 的目录路径，或者是 Git 仓库的 URL。

当提供的值是相对路径时，它被解释为相对于项目目录。如果使用绝对路径定义构建上下文，Compose 会发出警告，因为这会影响 Compose 文件的可移植性。

build:
  context: ./dir

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

如果不显式设置，context 默认为项目目录（.）。

7、dockerfile

dockerfile 设置一个备用的 Dockerfile。相对路径是基于构建上下文解析的。如果使用绝对路径来定义 Dockerfile，Compose 会

发出警告，因为这会影响 Compose 文件的可移植性。

当设置了 dockerfile 属性时，不允许同时设置 dockerfile_inline 属性，如果 Compose 文件中两者都设置了，Compose 会拒绝这样的文件。

build:
  context: .
  dockerfile: webapp.Dockerfile

8、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

9、entitlements

需要Docker Compose 2.27.1及以上版本。定义在构建过程中允许的额外特权授权。

entitlements:
  - network.host
  - security.insecure

10、extra_hosts

在构建时添加主机名映射，与顶部元素services 元素中的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

11、isolation

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

Windows 支持的值：

1. 1. process - 进程隔离（默认，较少的开销）
   2. hyperv - Hyper-V 隔离（更强的隔离性，接近虚拟机级别）

Linux 通常只支持：default - 默认的命名空间隔离（cgroups、namespaces）

#Windows平台
build:
  context: .
  isolation: process   # Windows 默认，进程隔离
  # 或
  isolation: hyperv    # Hyper-V 隔离，需要 Windows 10/Server 2016+
  
        
#Linux平台                    
build:
  context: .
  isolation: default   # Linux 默认，使用命名空间隔离

12、labels

给结果镜像添加元数据。值可以设置为一个数组或者映射。建议使用反向DNS表示法来防止您的标签与其他软件发生冲突。

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

13、network

在镜像构建期间，设置 RUN 指令所使用的网络。

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

设置为 none时会在构建的时候禁用网络

build:
  context: .
  network: none

常用选项：

1. 1. host：使用宿主机网络栈，通常最快且能直接使用主机代理等设置。
   2. bridge：默认的桥接网络模式。
   3. none：无网络，适用于完全离线的构建。
   4. 自定义网络名：连接到用户预先创建的自定义 Docker 网络。

14、paltforms

定义一个平台列表

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

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

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

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

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

2. 当列表中包含不受支持的平台时。

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

3. 当列表非空但不包含该服务的平台时。

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

15、privileged

需要Docker Compose 2.15.0及以上版本。privileged 配置服务镜像以提升的权限进行构建。其支持度和实际影响是平台特定的。

功能：允许构建容器在构建期间以特权模式运行。

平台差异：在 Linux 上通常意味着禁用大部分安全限制（如 AppArmor、SELinux），在 Windows 或其他平台上可能有不同表现或根本不支持。

典型用例：构建过程中需要执行需要特殊权限的操作（如挂载文件系统、使用特定设备）。

安全警告：启用此选项会降低构建环境的安全性，应谨慎使用。

build:
  context: .
  privileged: true

16、provenance

需要Docker Compose 2.39.0及以上版本。provenance 配置构建器为发布的镜像添加来源证明（镜像是如何构建的）。

该值可以是布尔值（启用/禁用来源证明），也可以是键=值字符串以设置来源配置。您可以通过设置 mode 参数来选择包含在来源证明中的详细程度。

1. 功能：为镜像添加可验证的构建来源元数据，增强供应链安全。

2. 模式选择：通常支持 min（最小信息）或 max（最大信息，包含构建依赖等完整记录）等模式。

3. 平台要求：需要构建器支持（如 BuildKit）并在支持来源证明的镜像仓库中发布。

   build:
   context: .
   provenance: true

   build:
   context: .
   provenance: mode=max

典型工作流：

1. 构建时生成包含来源证明的镜像
2. 将镜像和证明一起推送到支持证明的镜像仓库
3. 部署时或审计时验证镜像的来源和完整性

17、pull

pull 要求镜像构建器拉取引用的镜像（FROM Dockerfile 指令中的基础镜像），即使这些镜像在本地镜像存储中已存在可用版本。它有三种配置选项：

1. pull: true 或 pull: "always"

2. pull: false 或 pull: "never"

3. pull: "if_not_present"（默认）

   version: '3.8'
   services:
   webapp:
   build:
   context: ./frontend
   dockerfile: Dockerfile.dev
   pull: if_not_present # 默认，本地没有才拉取

   database:
   image: postgres:15-alpine
   # 对于 image 直接指定的，也有 pull_policy 控制

   ci-builder:
   build:
   context: .
   dockerfile: Dockerfile.ci
   pull: true # CI中总是拉取最新基础镜像
   profiles: ["ci"] # 只在ci配置文件中启用

   services:
   production:
   build:
   context: .
   dockerfile: Dockerfile.multi
   pull:
   - if_not_present # 对于第一阶段
   - always # 对于第二阶段
   - never # 对于第三阶段

18、sbom

需要Docker Compose 2.39.0及以上版本。sbom 配置构建器为发布的镜像添加软件物料清单（镜像的内容）。该值可以是布尔值（启用/禁用 SBOM 证明），也可以是键=值字符串以设置 SBOM 生成器配置。这允许您选择替代的 SBOM 生成器镜像

build:
  context: .
  sbom: true
  
build:
  context: .
  sbom: generator=docker/scout-sbom-indexer:latest # Use an alternative SBOM generator  

19、secrets

根据每个服务构建的 secrets 所定义的敏感数据授予访问权限。支持两种不同的语法变体：短格式语法和长格式语法。

如果在顶部属性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

长格式语法：提供了更精细的控制，用于指定密钥在服务容器内的创建方式。

1. source：平台上存在的密钥名称。
2. target：在 Dockerfile 中声明的密钥 ID。如果未指定，则默认为 source。
3. uid 和 gid：在服务的任务容器内，拥有 /run/secrets/ 目录下文件的数字用户 ID（uid）或组 ID（gid）。默认值为 USER。
4. mode：在服务的任务容器内，挂载到 /run/secrets/ 目录下的文件权限，以八进制表示。默认值为全局可读权限（模式 0444）。如果设置了可写位，则必须忽略。可执行位可以设置。

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

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

# Dockerfile
FROM nginx
RUN --mount=type=secret,id=cert,required=true,target=/root/cert ...

20、ssh

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

ssh 属性的语法可以是以下两种形式：

1. default：让构建器连接到 SSH 代理。

2. ID=path：一个 ID 与关联路径的键值对定义。path 可以是一个 PEM 文件，也可以是 ssh-agent 套接字的路径。

   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 ...

21、shm_size

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

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

22、tags

tags 定义了一组必须与构建镜像关联的标签映射列表。此列表是对服务（service）部分中已定义的 image 属性的补充。

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

23、target

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

build:
  context: .
  target: prod

24、ulimits

需要Docker Compose 2.23.1及以上版本。为构建镜像的容器（即构建环境）本身设置资源限制，而不是为最终生成的镜像设置限制。

ulimits 可覆盖容器的默认 ulimits 限制。可通过整数指定单一限制值，或通过映射关系分别指定软限制和硬限制。

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