Rust 交叉编译 Docker 镜像方案 — 从 ARM64 到 AMD64

1. 背景

博客项目 rabitlogic-blog 使用 Rust + Dioxus 构建，需要在 Docker 容器中部署到 AMD64 Linux 服务器。但开发机是 Apple Silicon Mac（ARM64 架构），直接 docker build 出来的镜像是 linux/arm64，部署到 AMD64 服务器时会报平台不匹配：

! app The requested image's platform (linux/arm64) does not match
  the detected host platform (linux/amd64/v4)

2. 方案选型

方案 A：QEMU 模拟（❌ 慢）

FROM --platform=$TARGETPLATFORM rust:bookworm AS builder

让 Docker BuildKit 用 QEMU 模拟 AMD64 环境来编译 Rust。缺点：QEMU 的 x86_64 模拟在 ARM64 上极慢，完全编译一次可能需要 30 分钟以上，而且容易 OOM。

方案 B：宿主机交叉编译（❌ 工具链复杂）

在 macOS 上安装 x86_64-unknown-linux-gnu-gcc 交叉链接器。缺点：macOS 上的交叉编译工具链维护麻烦，glibc sysroot 需要手动配置，ring 这类含 C 代码的 crate 容易出问题。

方案 C：专用交叉编译 Docker 镜像（✅ 最优）

创建一个基于 rust:bookworm 的 Docker 镜像，安装好交叉链接器。编译时用这个镜像运行 cargo build，rustc 本身跑在原生 ARM64 上，只有链接器是跨架构的。比 QEMU 快 5-10 倍。

本文最终采用方案 C。

3. 实现架构

                          ┌──────────────────────────┐
                          │   docker/cross.Dockerfile │
                          │   rust:bookworm + gcc-    │
                          │   x86-64-linux-gnu        │
                          └──────────┬───────────────┘
                                     │ docker build
                                     ▼
                    ┌────────────────────────────┐
                    │  rabitlogic-blog-cross:${target}  │  ← 编译环境镜像
                    │  (ARM64 native, cached)    │
                    └──────────┬─────────────────┘
                               │ docker run -v $(pwd):/build
                               │ cargo build --target x86_64-...
                               ▼
                    ┌────────────────────────────┐
                    │  target/x86_64-unknown-    │  ← AMD64 二进制
                    │  linux-gnu/release/        │
                    │  rabitlogic-blog (ELF x86-64)     │
                    └──────────┬─────────────────┘
                               │ DOCKER_DEFAULT_PLATFORM=linux/amd64
                               │ docker compose build
                               ▼
                    ┌────────────────────────────┐
                    │  rabitlogic-blog-app:latest       │  ← AMD64 运行时镜像
                    │  (deployable!)             │
                    └────────────────────────────┘

为什么快？

关键区别在于 rustc（Rust 编译器）本身是 ARM64 原生运行的，不需要模拟。只有链接器（x86_64-linux-gnu-gcc）需要处理 AMD64 目标。Rust 编译的绝大部分时间花在 rustc 上（类型检查、代码生成、优化），链接只是最后几步。所以整体速度接近原生编译。

4. 核心文件

FROM rust:bookworm

ARG TARGET_TRIPLE=x86_64-unknown-linux-gnu
ARG CROSS_LINKER_PKG=gcc-x86-64-linux-gnu
ARG CROSS_LINKER_BIN=x86_64-linux-gnu-gcc
ARG LIBC_DEV_PKG=libc6-dev-amd64-cross

# 安装交叉链接器 + C 标准库头文件
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    ${CROSS_LINKER_PKG} \
    ${LIBC_DEV_PKG} \
    && rm -rf /var/lib/apt/lists/*

# 添加 Rust 目标
RUN rustup target add ${TARGET_TRIPLE}

# 配置 cargo 使用交叉链接器
ENV CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=x86_64-linux-gnu-gcc
ENV CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc

ARG TARGET_TRIPLE=x86_64-unknown-linux-gnu

FROM node:20-alpine AS tailwind
# ... 构建 Tailwind CSS ...

FROM debian:bookworm-slim
# 直接复制交叉编译好的二进制
COPY target/${TARGET_TRIPLE}/release/rabitlogic-blog /app/rabitlogic-blog
# ... 复制其他资源 ...

default = ["web", "server"]
web = ["dioxus/web", "wasm-bindgen", "web-sys"]

cargo build --target x86_64-unknown-linux-gnu \
    --release \
    --no-default-features \
    --features server

# 默认 AMD64
./deploy.sh package

# 指定平台
./deploy.sh package linux/amd64
./deploy.sh package linux/arm64

# 1. 构建交叉编译镜像（仅首次，后续缓存）
docker build -t rabitlogic-blog-cross:x86_64-unknown-linux-gnu \
  --build-arg TARGET_TRIPLE=x86_64-unknown-linux-gnu \
  --build-arg CROSS_LINKER_PKG=gcc-x86-64-linux-gnu \
  --build-arg CROSS_LINKER_BIN=x86_64-linux-gnu-gcc \
  --build-arg LIBC_DEV_PKG=libc6-dev-amd64-cross \
  -f docker/cross.Dockerfile .

# 2. 交叉编译 Rust 二进制
docker run --rm \
  -v "$(pwd):/build" -w /build \
  -v rabitlogic-blog-cargo-cache:/usr/local/cargo/registry \
  rabitlogic-blog-cross:x86_64-unknown-linux-gnu \
  cargo build --target x86_64-unknown-linux-gnu \
    --release --no-default-features --features server

# 3. 构建运行时镜像
DOCKER_DEFAULT_PLATFORM=linux/amd64 \
  docker compose build --build-arg TARGET_TRIPLE=x86_64-unknown-linux-gnu

# 4. 验证架构
file target/x86_64-unknown-linux-gnu/release/rabitlogic-blog
# 输出: ELF 64-bit LSB pie executable, x86-64, ... for GNU/Linux

file target/x86_64-unknown-linux-gnu/release/rabitlogic-blog
# ✅ ELF 64-bit LSB pie executable, x86-64, ... for GNU/Linux

docker inspect rabitlogic-blog-app:latest --format '{{.Architecture}}'
# ✅ amd64

# 打包
./deploy.sh package

# 上传到服务器
scp rabitlogic-blog-bundle.tar.gz root@<server>:/root/

# 服务器上解压运行
ssh root@<server>
tar xzf rabitlogic-blog-bundle.tar.gz
gunzip -c rabitlogic-blog-app.tar.gz | docker load
docker compose up -d

# ❌ cargo config.d/cross.toml 有时不生效
echo "linker = \"x86_64-linux-gnu-gcc\"" > config.d/cross.toml

# ✅ 环境变量方式可靠
ENV CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=x86_64-linux-gnu-gcc

no matching manifest for linux/arm64/v8 in the manifest list entries