本项目基于 CNB (Cloud Native Build) 平台实现自动化多架构 Docker 镜像构建流程，支持 linux/amd64 和 linux/arm64 两种架构的并行构建与合并。

CNB 平台提供了以下关键功能，使多架构构建变得简单高效：

• 并行构建：支持不同架构的构建任务并行执行，显著提高构建效率
• 架构标签：通过 cnb:arch:amd64 和 cnb:arch:arm64:v8 标签自动分配到对应架构的运行器
• 任务同步：使用 cnb:await 和 cnb:resolve 实现跨任务的状态同步
• 清单管理：通过 cnbcool/manifest 工具自动创建和管理多架构镜像清单
• 资源清理：使用 artifact:remove-tag 自动清理中间构建标签

.build-arch-template: &build-arch-template
  services:
    - docker
  stages:
    - name: 构建并推送 Docker 镜像
      script: |
        docker buildx build \
          --platform linux/${ARCH_KEY} \
          -t ${IMAGE_TAG} \
          --push \
          ${DOCKER_BUILD_PATH}
    - name: 标记构建完成（供后续等待使用）
      type: cnb:resolve
      options:
        key: build-${ARCH_KEY}

此模板定义了单个架构的构建流程，包括：

• 使用 Docker Buildx 进行多架构构建
• 构建完成后自动推送到注册表
• 使用 cnb:resolve 标记构建完成状态

.build-manifest: &build-manifest
  services:
    - docker
  runner:
    cpus: 1
  env:
    IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
  stages:
    - name: 等待 amd64 构建完成
      type: cnb:await
      options:
        key: build-amd64
    - name: 等待 arm64 构建完成
      type: cnb:await
      options:
        key: build-arm64
    - name: 创建多平台镜像清单
      image: cnbcool/manifest
      settings:
        target: ${IMAGE_TAG}
        template: ${IMAGE_TAG}-OS-ARCH
        platforms:
          - linux/amd64
          - linux/arm64
    - name: 清理中间架构标签
      type: artifact:remove-tag
      options:
        name: ${CNB_REPO_NAME}
        tags:
          - latest-linux-amd64
          - latest-linux-arm64
        type: docker

此阶段负责：

• 使用 cnb:await 等待所有架构构建完成
• 创建多架构 Docker 清单
• 清理中间构建标签

标准构建流水线使用项目根目录作为构建上下文：

.build-pipeline:
  # amd64 构建任务（使用当前目录）
  - <<: *build-arch-template
    runner:
      tags: cnb:arch:amd64
      cpus: 1
    env:
      ARCH_KEY: amd64
      DOCKER_BUILD_PATH: .
      IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest-linux-amd64

  # arm64 构建任务（使用当前目录）
  - <<: *build-arch-template
    runner:
      tags: cnb:arch:arm64:v8
      cpus: 1
    env:
      ARCH_KEY: arm64
      DOCKER_BUILD_PATH: .
      IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest-linux-arm64

  # 合并 manifest
  - *build-manifest

IDE 构建流水线使用 .ide 目录作为构建上下文，专门用于构建 IDE 相关镜像：

.build-ide-pipeline:
  # amd64 构建任务（使用 .ide 目录）
  - <<: *build-arch-template
    runner:
      tags: cnb:arch:amd64
      cpus: 1
    env:
      ARCH_KEY: amd64
      DOCKER_BUILD_PATH: .ide
      IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest-linux-amd64

  # arm64 构建任务（使用 .ide 目录）
  - <<: *build-arch-template
    runner:
      tags: cnb:arch:arm64:v8
      cpus: 1
    env:
      ARCH_KEY: arm64
      DOCKER_BUILD_PATH: .ide
      IMAGE_TAG: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest-linux-arm64

  # 合并 manifest
  - *build-manifest

用于标记任务完成状态，供其他任务等待：

- name: 标记构建完成
  type: cnb:resolve
  options:
    key: build-${ARCH_KEY}

用于等待其他任务完成：

- name: 等待 amd64 构建完成
  type: cnb:await
  options:
    key: build-amd64

用于清理构建过程中产生的临时标签：

- name: 清理中间架构标签
  type: artifact:remove-tag
  options:
    name: ${CNB_REPO_NAME}
    tags:
      - latest-linux-amd64
      - latest-linux-arm64
    type: docker

确保项目根目录或 .ide 目录包含有效的 Dockerfile：

FROM alpine:latest
CMD ["echo", "Hello, CNB!"]

在 CNB 平台上配置构建流水线，选择适当的构建类型：

• 使用 .build-pipeline 进行标准构建
• 使用 .build-ide-pipeline 进行 IDE 构建

CNB 平台会自动：

• 分配对应架构的运行器
• 并行执行多架构构建
• 等待所有架构构建完成
• 创建多架构清单
• 清理临时资源

构建完成后，可以使用以下命令拉取多架构镜像：

docker pull ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

Docker 会自动根据当前架构拉取对应的镜像版本。

1. 构建上下文优化：确保 Dockerfile 和相关文件位于正确的构建上下文目录中
2. 多阶段构建：使用多阶段构建减少最终镜像大小
3. 缓存利用：合理利用 Docker Buildx 缓存机制提高构建速度
4. 标签管理：遵循语义化版本标签规范，便于版本管理

1. 构建超时：检查 Dockerfile 是否存在耗时操作，考虑优化构建步骤
2. 架构不匹配：确保基础镜像支持目标架构
3. 推送失败：检查注册表权限和网络连接

1. 查看构建日志了解详细错误信息
2. 使用 docker buildx build 本地测试构建过程
3. 检查环境变量是否正确设置

CNB 平台通过提供并行构建、任务同步和清单管理等特性，大大简化了多架构 Docker 镜像的构建流程。本项目提供的构建模板可以作为标准参考，帮助快速实现高效的多架构 CI/CD 流程。