多平台镜像构建与 Docker Buildx：从 Amd64 到 Arm64 的跨架构交付

主流架构：
  - amd64（x86_64）：绝大多数服务器、云主机
  - arm64（aarch64）：Apple Silicon、Arm 服务器（AWS Graviton 等）、手机芯片
  - arm/v7：Raspberry Pi、低功耗设备
  - ppc64le / s390x：IBM 大型机、POWER 服务器

痛点：
  服务要同时部署到 x86 集群与 Arm 集群 → 需要两套镜像
  用户在 Apple Silicon 上 pull x86 镜像 → 性能差 / 无法运行
  → 多平台镜像用一个 tag 承载多份架构

没有多平台：image:v1 只代表 amd64
  在 arm64 主机上 pull → 直接报错或跑模拟（性能差）

有了多平台：image:v1 = manifest list
  {
    amd64:  sha256:aa..（真实 amd64 镜像）
    arm64:  sha256:bb..（真实 arm64 镜像）
  }
  docker pull image:v1
  → amd64 主机拉 sha256:aa
  → arm64 主机拉 sha256:bb

传统 docker build 的局限：
  - 只面向"当前宿主机架构"构建
  - 无法直接产出其他架构的镜像
  - 也没有 manifest list 的组装能力

Buildx（Docker CLI 插件，基于 BuildKit）：
  - 可同时为多个平台构建
  - 支持 QEMU 模拟（binfmt）
  - 支持交叉编译提示（--platform 传入构建参数）
  - 支持 buildkit 远程缓存、bake 编排

buildx 需要一个"构建器（builder）"来执行构建：
  - docker 驱动：复用 Docker daemon，功能有限（不支持多平台同时产多个）
  - docker-container 驱动：独立的 BuildKit 容器，
    支持多平台、缓存导出、远程缓存 —— 多平台构建的推荐驱动

创建 docker-container 构建器：
  docker buildx create --name mybuilder --driver docker-container --use
  docker buildx ls     # 查看构建器与平台支持

在 x86 主机上构建 arm64 镜像，有两种思路：

思路一：交叉编译（cross-compile）
  在构建命令里直接产出 arm64 机器码（如 GOARCH=arm64）
  → 快，但需要应用/语言工具链支持交叉编译

思路二：QEMU 模拟（emulation）
  用 QEMU 在 x86 上"假装"运行 arm64 指令
  → 通用，但每条指令都被翻译，构建慢 2~10 倍

Buildx 通常的做法：
  以 QEMU 兜底模拟 + 应用层交叉编译加速（如 Go/Rust）
  对无法交叉编译的语言（如多数解释型包下载）用模拟

# 安装 QEMU 用户态模拟 + binfmt 注册（让 Linux 认识 arm64 可执行文件）
docker run --privileged --rm tonistiigi/binfmt --install all

# 验证：构建器应能看到多平台
docker buildx inspect mybuilder --bootstrap
docker buildx ls
# 输出应包含 linux/amd64, linux/arm64, linux/arm/v7 等

# 前提：先用 binfmt 装好 QEMU，并创建 docker-container 构建器
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push .        # 直接推送到 registry

拆解：
  --platform  指定要构建的平台列表（逗号分隔）
  --push      构建后直接推（多平台必须 push，本机无法同时存在）
  --builder   指定使用 docker-container 构建器（多平台必需）

# 交叉编译优先：在构建参数里拿到目标平台
ARG TARGETOS
ARG TARGETARCH
RUN curl -fsSL https://downloads/myapp-${TARGETOS}-${TARGETARCH} -o /usr/local/bin/myapp \
    && chmod +x /usr/local/bin/myapp
# TARGETOS/TARGETARCH 是 BuildKit 自动注入的平台构建变量

# Go 应用的交叉编译（官方 golang 镜像自带 GOARCH 支持）
FROM golang:1.23 AS build
ARG TARGETOS
ARG TARGETARCH
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /app

FROM gcr.io/distroless/static
COPY --from=build /app /app
ENTRYPOINT ["/app"]

docker buildx build --push 后，registry 上保存：
  - manifest list（索引）：列出各平台的 manifest
  - 每平台一个 manifest + 对应层

客户端 docker pull / containerd / k8s 会：
  1. 先拉 manifest list
  2. 根据 runtime.GOARCH 选择对应条目
  3. 拉该条目的层
→ 用户无感知，一个 tag 全平台可跑

# 查看镜像支持哪些平台
docker buildx imagetools inspect myapp:latest
# 输出：Platform: linux/amd64, linux/arm64 ...

# 多平台镜像在任意架构主机上：
docker pull myapp:latest   # 自动选对应架构

# GitHub Actions：Setup buildx + QEMU，然后多平台构建推送
- uses: docker/setup-qemu-action@v3        # 安装 binfmt/QEMU
- uses: docker/setup-buildx-action@v3      # 创建 docker-container 构建器

- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: registry/myapp:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

多平台构建的缓存要点：
  - 每个平台一套层缓存（架构不同，层不能共用）
  - 用 cache-to: type=gha,mode=max 缓存全部中间层
  - 或 registry 型缓存（cache-from/cache-to type=registry）

规律：多平台构建时长 ≈ 平台数 × 单平台构建（模拟更慢）
  实际做法：并行构建 + 只对 CI 内变化的层重建

□ 创建 docker-container 构建器（多平台必需）
□ 装好 binfmt（QEMU），构建器 ls 能看到多平台
□ Dockerfile 用 TARGETOS/TARGETARCH 做交叉编译
□ CGO_ENABLED=0 + 静态链接，最大化交叉编译收益
□ --platform + --push 一条命令产出 manifest list
□ CI 里 setup-qemu + setup-buildx + build-push-action
□ 用 gha/registry 缓存，别让多平台构建天天全量重建
□ 上线前用 imagetools inspect 验证平台覆盖

多平台镜像 = 一个 tag 承载多份架构，
Buildx + QEMU + 交叉编译让一份代码交付到所有主流架构。