rust-crossbuild 镜像文档

1. 镜像概述和主要用途

rust-crossbuild 是一个集成交叉编译工具链的 Rust 镜像，专为与 docker buildx 配合实现跨平台构建而设计。其核心用途是简化 Rust 应用的多平台 Docker 镜像构建流程，通过预配置的 cargo 交叉编译环境，实现原生环境下的高效编译，无需依赖 qemu 模拟，显著提升构建速度。

2. 核心功能和特性

• 内置交叉编译工具链：预配置 cargo 以支持跨平台编译，无需手动配置工具链，简化构建流程。
• 高效原生编译：相比使用普通 Rust 镜像的 docker buildx，本镜像通过原生环境编译（无需 qemu 模拟）大幅提升构建效率。
• 多平台支持：支持多种构建平台和目标平台，覆盖主流 CPU 架构需求。
• 与 docker buildx 无缝集成：专为 docker buildx 设计，支持多平台并行构建和镜像推送。

3. 使用场景和适用范围

• 适用于需要为多种 CPU 架构（如 amd64、arm64、arm/v7）构建 Rust 应用 Docker 镜像的场景。
• 适合开发者或 CI/CD 流程中，通过 docker buildx 进行跨平台镜像构建并推送到容器仓库的需求。

4. 详细使用方法和配置说明

4.1 Dockerfile 编写

构建阶段需使用 jonoh/rust-crossbuild 镜像，并通过 --platform=$BUILDPLATFORM 确保构建阶段使用原生平台。示例 Dockerfile：

# 构建阶段：使用 rust-crossbuild 镜像，指定原生构建平台
FROM --platform=$BUILDPLATFORM jonoh/rust-crossbuild AS builder
WORKDIR /usr/src/myapp
COPY . .  # 复制项目源码
RUN cargo install --path .  # 编译并安装应用

# 运行阶段：使用轻量级基础镜像
FROM debian:buster-slim
# 安装运行时依赖（根据实际需求调整）
RUN apt-get update && apt-get install -y extra-runtime-dependencies && rm -rf /var/lib/apt/lists/*
# 从构建阶段复制编译产物
COPY --from=builder /usr/local/cargo/bin/myapp /usr/local/bin/myapp
CMD ["myapp"]  # 启动应用

关键说明：--platform=$BUILDPLATFORM 确保构建阶段镜像与主机原生平台一致，避免 qemu 模拟开销；运行阶段镜像则针对目标平台构建。

4.2 docker buildx 构建命令

通过 docker buildx 执行跨平台构建，支持同时指定多个目标平台并推送镜像。示例命令：

# 构建并推送支持 amd64 和 arm64 架构的镜像
docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .

参数说明：

• --platform：指定目标平台列表，多个平台用逗号分隔（支持的目标平台见 5.2 节）。
• -t myapp：指定镜像标签（格式为 仓库地址/镜像名:标签，如 docker.io/username/myapp:v1）。
• --push：构建完成后自动推送到指定仓库（需提前通过 docker login 登录仓库）。

5. 支持的平台

5.1 构建平台（Build platforms）

指构建过程中使用的原生平台，即运行 docker buildx 的主机架构：

• linux/amd64
• linux/arm64

5.2 目标平台（Target platforms）

指最终生成的 Docker 镜像支持的运行平台：

• linux/amd64
• linux/arm64
• linux/arm/v7