.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 标记构建完成状态

2. 多架构合并清单

.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 目录作为构建上下文，专门用于构建 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

CNB 平台特殊指令

cnb:resolve

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

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

cnb:await

用于等待其他任务完成：

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

artifact:remove-tag

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

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

使用指南

1. 准备工作

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

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

2. 触发构建

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

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

3. 监控构建过程

CNB 平台会自动：

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

4. 拉取镜像

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

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

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

最佳实践

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

故障排除

常见问题

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

调试技巧

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

总结

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

About

No description, topics, or website provided.

284.00 KiB

5 forks 0 stars 1 branches 0 TagREADME

Release
0

Tag

Contributors
2

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111

CNB 多架构 Docker 镜像构建流程

概述

CNB 平台特性

构建流程架构

1. 单架构构建模板