Docker Buildx 多平台镜像构建的项目实践

# 安装 Buildx（Docker 19.03+ 已内置，如需手动安装执行）
docker buildx install
# 验证安装成功
docker buildx version

# 特权模式安装 QEMU 静态二进制文件
docker run --privileged --rm tonistiigi/binfmt --install all

# 验证支持的架构
docker buildx ls

# 创建并启用构建器（--bootstrap 自动初始化）
docker buildx create --name multi-arch-builder --use --bootstrap

# 查看构建器详情（确认支持的架构列表）
docker buildx inspect multi-arch-builder --bootstrap

docker buildx build \
  --platform linux/amd64,linux/arm64 \  # 指定目标架构（多个用逗号分隔）
  -t registry.example.com/app/multi-arch:v1.0 \  # 镜像标签（含仓库地址）
  --push \  # 推送到仓库（必选参数）
  .  # Dockerfile 所在目录

docker buildx build \
  --platform linux/arm64 \
  -t app/arm64-test:v1.0 \
  --load \  # 加载到本地 Docker 镜像列表
  .

# 优先选择官方多架构基础镜像（如 alpine、eclipse-temurin）
FROM alpine:3.19

# Buildx 内置变量：TARGETARCH（架构）、TARGETOS（操作系统）
ARG TARGETARCH
ARG TARGETOS

# 示例：安装不同架构的二进制依赖
RUN if [ "$TARGETARCH" = "amd64" ]; then \
      wget https://example.com/bin-amd64 -O /usr/local/bin/app; \
    elif [ "$TARGETARCH" = "arm64" ]; then \
      wget https://example.com/bin-arm64 -O /usr/local/bin/app; \
    fi

# 权限优化（生产环境推荐非 root 用户运行）
RUN chmod +x /usr/local/bin/app && adduser -D appuser
USER appuser

WORKDIR /app
CMD ["/usr/local/bin/app"]

# 定义变量（默认值可通过命令行覆盖）
variable "TAG" {
  default = "latest"
}
# 生产环境镜像目标
target "prod" {
  dockerfile = "Dockerfile"
  contexts = {
    src = "."
  }
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["registry.example.com/app/prod:${TAG}"]
  buildArgs = {
    APP_ENV = "production"
  }
}
# 测试环境镜像目标（继承 prod 配置并修改参数）
target "test" {
  inherits = ["prod"]
  buildArgs = {
    APP_ENV = "test"
  }
  tags = ["registry.example.com/app/test:${TAG}"]
}

# 构建生产环境镜像
docker buildx bake prod

# 构建测试环境镜像（覆盖 TAG 变量）
docker buildx bake test --set variable.TAG=v1.0

stages:
  - build-multi-arch
build-multi-arch:
  stage: build-multi-arch
  image: docker:20.10-git
  services:
    - docker:20.10-dind  # 依赖 Docker-in-Docker 服务
  variables:
    DOCKER_REGISTRY: registry.example.com  # 私有仓库地址
    IMAGE_NAME: app/microservice
    IMAGE_TAG: $CI_COMMIT_SHA  # 用 Commit ID 作为版本，避免冲突
  before_script:
    # 1. 登录私有仓库
    - echo "$REGISTRY_PWD" | docker login $DOCKER_REGISTRY -u $REGISTRY_USER --password-stdin
    # 2. 初始化 Buildx 和 QEMU
    - docker buildx install
    - docker run --privileged --rm tonistiigi/binfmt --install all
    - docker buildx create --name builder --use --bootstrap
  script:
    # 3. 构建并推送，启用远程缓存加速
    - docker buildx build 
        --platform linux/amd64,linux/arm64 
        --cache-from=type=registry,ref=$DOCKER_REGISTRY/$IMAGE_NAME:cache 
        --cache-to=type=registry,ref=$DOCKER_REGISTRY/$IMAGE_NAME:cache,mode=max 
        -t $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG 
        -t $DOCKER_REGISTRY/$IMAGE_NAME:latest 
        --push 
        .
  after_script:
    # 清理构建器
    - docker buildx rm builder
  only:
    - main  # 仅主分支触发生产镜像构建

# 迁移多平台镜像（源仓库 -> 目标仓库）
docker buildx imagetools create \
  -t registry.example.com/app/multi-arch:v1.0 \
  docker.io/original/app:v1.0

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/app/multi-arch:v1.0 \
  --push \
  --build-arg BASE_IMAGE=docker.io/original/app:v1.0 \
  - <<EOF
FROM \$BASE_IMAGE
EOF