agrozyme/podman-qemu

podman-qemu 镜像文档

镜像概述

本镜像基于Alpine构建，集成podman和qemu工具，旨在简化跨平台Docker镜像的构建流程。受https://hub.docker.com/r/jonoh/docker-buildx-qemu%E5%90%AF%E5%8F%91%EF%BC%8C%E5%B7%B2%E5%9C%A8GitLab CI环境（gitlab.com）中测试验证。

核心功能与特性

• 跨平台构建支持：通过qemu实现多架构环境模拟，支持多种目标架构的镜像构建
• GitLab CI集成：提供预定义CI模板，简化多平台镜像的自动化构建流程
• 灵活的环境配置：支持通过环境变量自定义构建参数，满足不同场景需求
• 构建优化机制：提供钩子脚本（before_script.sh/after_script.sh），可在构建前后执行自定义操作，提升构建效率

支持架构

模拟架构

可通过qemu模拟多种环境，支持的架构由GOARCH值定义，具体参考：

• GOARCH官方文档
• https://github.com/docker-library/official-images#architectures-other-than-amd64

运行架构

镜像本身可在以下架构环境中运行（Alpine与QEMU支持的交集）：

• amd64
• 386
• arm64
• arm
• ppc64le
• riscv64

GitLab CI模板

提供两种CI模板文件，用于构建多平台Docker镜像：

单分支模板（Single）

适用于单分支仓库，将main分支构建并部署为latest标签

多分支模板（Multiple）

适用于多分支仓库，每个分支映射为一个Docker镜像标签，仓库名称与Docker Registry保持一致

模板路径

Docker Hub

• 单分支：/.gitlab/ci/single/docker-hub.yaml
• 多分支：/.gitlab/ci/multiple/docker-hub.yaml

GitLab容器仓库

• 单分支：/.gitlab/ci/single/gitlab.yaml
• 多分支：/.gitlab/ci/multiple/gitlab.yaml

工作流程

1. 使用镜像的main标签进行构建测试
2. build-one-arch作业推送main标签的镜像
3. 当build-one-arch作业成功后，其他构建作业推送多平台镜像
4. 镜像推送完成后，build-metadata-push作业更新Docker Hub仓库描述：
   • 短描述：取自项目的描述设置
   • 完整描述：取自项目的README.md文件

环境变量

建议将所有Docker镜像仓库归类到一个Group，并在Group的CI/CD设置中配置变量。

变量覆盖优先级

按以下顺序覆盖默认值（从高到低）：

1. .gitlab-ci.yml中的阶段变量
2. .gitlab-ci.yml中的全局变量
3. 项目CI/CD设置中的变量
4. 组CI/CD设置中的变量

必选变量（仅Docker Hub）

无默认值，必须显式设置：

• DOCKER_HUB_USER：Docker Hub登录用户名
• DOCKER_HUB_PASS：Docker Hub访问令牌（参考：Docker访问令牌文档）
• DOCKER_HUB_NAMESPACE：用户名或组织名，将作为ARG传递给Dockerfile

可选变量

• DOCKER_HUB_API_URL：Docker Registry API URL，仅可通过.gitlab-ci.yml覆盖，默认：https://hub.docker.com/v2
• DOCKER_REGISTRY：Docker登录服务器，仅可通过.gitlab-ci.yml覆盖，将作为ARG传递给Dockerfile，默认：docker.io
• DOCKER_ARCH：目标构建架构，默认：amd64
• DOCKER_TAG_SUFFIX：多平台镜像的标签后缀，会覆盖DOCKER_ARCH

钩子脚本

提供两个bash脚本用于在构建和推送前后执行自定义操作：

• before_script.sh：在构建开始前执行
• after_script.sh：在构建结束后执行

注意：

• 如需在镜像构建过程中下载文件，可通过编写before_script.sh并在Dockerfile中使用COPY命令实现
• 钩子脚本仅执行一次，有助于加速多平台镜像构建

构建作业

定义了以下可组合的构建任务：

.build-one-arch

构建与CI运行器相同架构的镜像，用于快速测试构建脚本

.build-all-arch

构建DOCKER_ARCH指定的架构镜像

.build-update-manifest

使用DOCKER_ARCH创建并推送镜像清单

.build-update-metadata

更新元数据到Docker仓库

使用示例

以下是GitLab CI配置示例，展示如何使用本镜像：

yaml
include:
  - project: agrozyme-docker/podman-qemu
    ref: main
    file: /.gitlab/ci/single/docker-hub.yaml

variables:
  DOCKER_ARCH: amd64,arm64

build-one-arch:
  extends:
    - .build-one-arch

build-all-arch:
  extends:
    - .build-all-arch
  parallel:
    matrix:
      - DOCKER_TAG_SUFFIX: [amd64, arm64]
  needs: ['build-one-arch']

build-manifest-create:
  extends:
    - .build-manifest-create
  needs: ['build-all-arch']

build-metadata-push:
  extends:
    - .build-metadata-push
  needs: ['build-manifest-create']