多架构容器镜像构建流水线设计（x86_64 + ARM64）+ 可复现 CI 配置模板 + 交叉构建踩坑手册

背景

我们团队有 3 个嵌入式网关项目（ARM64 目标平台：Cortex-A72 / A53，Ubuntu 22.04 基础镜像），同时还有 2 个 x86_64 后端服务需要统一镜像仓库。目前手动 docker buildx 构建，每次发版都要切机器、改 QEMU 注册、处理 glibc 差异，效率极低且容易漏架构。

最终要什么

一份可直接落地的多架构镜像构建 CI 流水线方案，覆盖从源码 commit 到多架构镜像推送到私有 registry 的全链路。具体要求：

1. CI 配置模板（二选一，优先 GitLab CI）：

   • 支持 x86_64 原生构建 + ARM64 交叉构建（QEMU binfmt 注册）
   • 构建产物推送到指定 registry，tag 格式含 git short SHA + 架构标识
   • 失败时保留构建上下文日志 ≥ 7 天
   • 至少包含 1 个多阶段 Dockerfile 示例（compiler stage → runtime stage，最终镜像 < 80MB）

2. 踩坑手册（Markdown，≥ 2000 字）：

   • QEMU binfmt_misc 注册/注销的完整命令与常见错误（如 docker buildx create 后 QEMU 段错误）
   • glibc 交叉编译时 ld-linux-aarch64.so.1 缺失的 3 种解法
   • ARM64 下 ld 链接顺序与 x86_64 差异导致的 undefined reference 实例
   • 多阶段构建中 --platform 参数遗漏导致架构混叠的排查方法
   • 至少 5 个真实场景的报错日志 + 根因 + 修复命令

3. 验证脚本（Bash）：

   • 一条命令拉取指定 tag 的 manifest，验证 x86_64 和 arm64 两个平台都存在
   • 输出每个架构的镜像大小、层数、OS/arch 字段

输入与上下文

• 目标平台：x86_64（原生）+ aarch64（交叉）
• 基础镜像：Ubuntu 22.04 / Debian 12 slim
• CI 环境：GitLab Runner（Docker executor），可安装 QEMU
• registry：Harbor 2.8（支持 OCI manifest list）
• 不需要支持 Windows / s390x

交付格式

• 1 个 Markdown 文件（踩坑手册，含所有命令与日志片段）
• 1 个 .gitlab-ci.yml（或 GitHub Actions workflow YAML）
• 1 个多阶段 Dockerfile 示例
• 1 个 Bash 验证脚本
• 全部文件打包，附 README 说明各文件用途与执行顺序