cargo-chef

缓存Rust项目的依赖项并加速Docker构建。

cargo-chef最初是为《Zero to Production In Rust》的部署章节开发的，这是一本使用Rust编程语言进行后端开发的实践指南。


cargo-chef

用法:
    cargo chef <子命令>

子命令:
    cook       重新构建由`cargo chef prepare`识别的最小项目骨架，并构建它以缓存依赖项
    prepare    分析当前项目，确定构建项目和缓存依赖项所需的最小文件子集（Cargo.lock和Cargo.toml清单）

prepare命令会检查你的项目并生成一个_配方_，捕获构建依赖项所需的信息集。

cargo chef prepare --recipe-path recipe.json

这里没有什么神秘的，你可以查看recipe.json文件：它包含了项目的骨架（例如所有Cargo.toml文件及其相对路径，Cargo.lock文件等）以及一些额外的信息。特别是，它确保所有库和二进制文件都在各自的Cargo.toml文件中明确声明，即使它们可以在默认位置找到（二进制文件为src/main.rs，库为src/lib.rs）。

recipe.json相当于Python的requirements.txt文件 - 它是cargo chef cook命令所需的唯一输入，该命令将构建我们的依赖项：

cargo chef cook --recipe-path recipe.json

如果你想以--release模式构建：

cargo chef cook --release --recipe-path recipe.json

你还可以选择覆盖使用哪个Rust工具链。例如，强制使用nightly工具链：

cargo +nightly chef cook --recipe-path recipe.json

cargo-chef设计用于在Dockerfile中使用：

FROM lukemathwalker/cargo-chef:latest-rust-1 AS chef
WORKDIR /app

FROM chef AS planner
COPY . .
RUN cargo chef prepare --recipe-path recipe.json

FROM chef AS builder 
COPY --from=planner /app/recipe.json recipe.json
# 构建依赖项 - 这是缓存的Docker层！
RUN cargo chef cook --release --recipe-path recipe.json
# 构建应用
COPY . .
RUN cargo build --release --bin app

# 运行二进制文件不需要Rust工具链！
FROM debian:bookworm-slim AS runtime
WORKDIR /app
COPY --from=builder /app/target/release/app /usr/local/bin
ENTRYPOINT ["/usr/local/bin/app"]

我们使用了三个阶段：第一个阶段计算配方文件，第二个阶段缓存依赖项并构建二进制文件，第三个阶段是我们的运行时环境。只要你的依赖项不变，recipe.json文件就保持不变，因此cargo chef cook --release --recipe-path recipe.json的结果将被缓存，大大加快构建速度（在一些商业项目中测得的加速可达5倍）。

预构建镜像

我们提供lukemathwalker/cargo-chef作为预构建的Docker镜像，其中同时包含Rust和cargo-chef。标签方案为 <cargo-chef 版本>-rust-<rust 版本>。例如，0.1.22-rust-1.56.0。你可以选择使用以下方式获取 cargo-chef 或 rust 的最新版本：

latest-rust-1.56.0（使用最新的 cargo-chef 和特定的 Rust 版本）；
0.1.22-rust-latest（使用最新的 Rust 和特定的 cargo-chef 版本）。你可以在 Dockerhub 上找到所有可用的标签。

:警告: 你必须在所有阶段使用相同的 Rust 版本 如果你在某个阶段使用了不同的 Rust 版本，缓存将无法按预期工作。

不使用预构建镜像

如果你不想使用 lukemathwalker/cargo-chef 镜像，可以在 Dockerfile 中直接安装 CLI：

FROM rust:1 AS chef 
# 我们只需支付一次安装成本，
# 从第二次构建开始就会被缓存
RUN cargo install cargo-chef 
WORKDIR app

FROM chef AS planner
COPY . .
RUN cargo chef prepare  --recipe-path recipe.json

FROM chef AS builder
COPY --from=planner /app/recipe.json recipe.json
# 构建依赖项 - 这是缓存的 Docker 层！
RUN cargo chef cook --release --recipe-path recipe.json
# 构建应用程序
COPY . .
RUN cargo build --release --bin app

# 我们不需要 Rust 工具链来运行二进制文件！
FROM debian:bookworm-slim AS runtime
WORKDIR app
COPY --from=builder /app/target/release/app /usr/local/bin
ENTRYPOINT ["/usr/local/bin/app"]

在 Alpine 中运行二进制文件

如果你想使用 alpine 发行版运行应用程序，需要创建一个完全静态的二进制文件。推荐的方法是使用 muslrust 为 x86_64-unknown-linux-musl 目标构建。 cargo-chef 适用于 x86_64-unknown-linux-musl，但我们是在交叉编译 - 必须明确指定目标工具链。

示例 Dockerfile 如下：

# 使用 `rust-musl-builder` 作为基础镜像，而不是
# 官方 Rust 工具链
FROM clux/muslrust:stable AS chef
USER root
RUN cargo install cargo-chef
WORKDIR /app

FROM chef AS planner
COPY . .
RUN cargo chef prepare --recipe-path recipe.json

FROM chef AS builder
COPY --from=planner /app/recipe.json recipe.json
# 注意我们正在指定 --target 标志！
RUN cargo chef cook --release --target x86_64-unknown-linux-musl --recipe-path recipe.json
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-musl --bin app

FROM alpine AS runtime
RUN addgroup -S myuser && adduser -S myuser -G myuser
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/app /usr/local/bin/
USER myuser
CMD ["/usr/local/bin/app"]

优点与局限性

cargo-chef 已在一些开源项目和商业项目上进行了测试，但我们的测试肯定没有涵盖 cargo build 自定义的所有可能性，我们确信还有一些需要改进的粗糙边缘 - 请在 GitHub 上提交问题。

`cargo-chef` 的优点：

一种常见的替代方法是将最小的 main.rs 与 Cargo.toml 和 Cargo.lock 一起加载到容器中，以构建仅包含依赖项的 Docker 层（更多信息请点击这里）。与 cargo-chef 相比，这种方法较为脆弱，因为 cargo-chef 可以：

自动选择工作空间中的所有 crate（以及新添加的 crate）
在文件或 crate 被移动时继续工作，而"手动"方法则需要对 Dockerfile 进行手动编辑
生成更少的中间 Docker 层（对于工作空间）

局限性和注意事项：

cargo chef cook 和 cargo build 必须从相同的工作目录执行。如果你使用 cat 检查项目 target/debug/deps 下的 *.d 文件，你会注意到它们包含引用项目 target 目录的绝对路径。如果移动，cargo 将无法利用它们作为缓存的依赖项；
由于其指纹逻辑依赖于时间戳，cargo build 将从头开始构建本地依赖项（当前项目之外），即使它们没有更改（参见 cargo 仓库中的这个长问题）；