在将一个实际在用的Go 语言编写的 REST API 项目迁移到 Rust 的过程中，跨平台编译和部署是第一需要解决的一个关键环节。本文介绍如何通过 Docker 构建适用于 CentOS 7 的 Rust 可执行文件。

为什么需要 Docker 构建？

在 Windows 开发环境下直接使用 cargo build –release 编译出的可执行文件无法在 Linux 系统上运行。即使使用交叉编译，CentOS 7 的 glibc 版本较旧，可能导致兼容性问题。

采用 Docker 在 Linux 环境下编译，并使用 musl 工具链进行静态链接，可以生成不依赖系统动态库的可执行文件，确保在不同 Linux 发行版上都能正常运行。

项目初始化

创建 Rust 项目：

cargo new my-rust-rest
cd my-rust-rest

Docker 构建配置

网络问题处理

开始使用 rust:1.75 作为基础镜像进行构建时，遇到了无法连接 Docker Hub 的问题。解决方案有两种：

1. 配置 Docker 镜像加速器（推荐用于生产环境）
2. 使用本地已有的镜像

本文示例使用 rust:latest 作为基础镜像，确保使用最新稳定版本。

常见问题：构建缓存导致的问题

在部署过程中，可能遇到可执行文件运行后没有预期输出的情况。即使源代码中包含 println! 宏，程序也可能不产生任何输出。

问题缘由：

Docker 构建时使用了层缓存机制，如果源代码层没有变化，Docker 会直接使用缓存的编译结果，导致最新的代码修改未被编译。

解决方案：

1. 使用 –no-cache 参数强制重新构建：
2. docker build –no-cache -f Dockerfile.centos7 -t my-rust-rest:centos7 .
3. 修改源代码触发重新编译（例如添加 io::stdout().flush() 调用）
4. 确保 Dockerfile 中源代码的复制步骤能够正确触发缓存失效

完整的构建流程

以下是完整的构建和部署流程：

1. 准备 Dockerfile

使用 musl 工具链进行静态链接，生成不依赖系统动态库的可执行文件：

FROM rust:latest AS builder

# 安装 musl 工具链
RUN rustup target add x86_64-unknown-linux-musl && 
    apt-get update && 
    apt-get install -y musl-tools && 
    apt-get clean && 
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 先复制依赖文件，利用 Docker 缓存
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && 
    echo "fn main() {}" > src/main.rs && 
    cargo build --release --target x86_64-unknown-linux-musl && 
    rm -rf src

# 再复制源代码，重新编译
COPY src ./src
RUN cargo build --release --target x86_64-unknown-linux-musl

# 最终阶段：只包含可执行文件
FROM scratch
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/my-rust-rest /my-rust-rest
ENTRYPOINT ["/my-rust-rest"]

2. 构建镜像

docker build -f Dockerfile.centos7 -t my-rust-rest:centos7 .

3. 提取可执行文件

# 创建临时容器
docker create --name rust-container my-rust-rest:centos7

# 复制可执行文件
docker cp rust-container:/my-rust-rest ./my-rust-rest

# 清理临时容器
docker rm rust-container

4. 部署到服务器

将可执行文件传输到 CentOS 7 服务器，添加执行权限后即可运行：

> chmod +x my-rust-rest
> ./my-rust-rest
Hello, world!

技术要点总结

1. 网络问题处理

在无法连接 Docker Hub 的情况下，可以通过以下方式解决：

• 配置 Docker 镜像加速器（推荐用于生产环境）
• 使用本地已有的镜像进行构建

2. Docker 缓存机制

Docker 的层缓存机制能够显著提升构建速度，但在某些情况下可能导致代码更新未被编译。提议：

• 在代码更新后使用 –no-cache 参数强制重新构建
• 合理设计 Dockerfile 的层结构，确保源代码变更能够触发重新编译

3. 静态链接的优势

使用 musl 工具链进行静态链接的优势：

• 兼容性：生成的可执行文件不依赖系统动态库，可在不同 Linux 发行版上运行
• 部署简单：特别适用于 glibc 版本较旧的系统（如 CentOS 7）
• 文件大小：静态链接的可执行文件一般为 500KB 左右，体积适中

4. 多阶段构建

采用多阶段构建的优势：

• 镜像体积小：最终镜像仅包含可执行文件，不包含编译工具链
• 安全性高：减少攻击面，不包含不必要的系统组件
• 构建效率：利用 Docker 缓存机制，提升构建速度

总结

通过 Docker 容器化构建和 Rust 的静态链接特性，可以实现跨平台部署的简化。本文介绍的构建流程适用于需要将 Rust 项目部署到 CentOS 7 等传统 Linux 环境的场景。

该方案的优势在于：

• 不依赖目标系统的编译环境
• 生成的可执行文件具有良好兼容性
• 构建过程可重复且易于自动化

对于需要迁移到 Rust 的项目，该构建和部署方案提供了一个可靠的解决方案。