可复现的依赖管理:coop 隔离虚拟机的 Nix 安装与跨平台交叉编译完全指南

原创2026-10-26 15:41:141,665 阅读

可复现的依赖管理:coop 隔离虚拟机的 Nix 安装与跨平台交叉编译完全指南

coop 是一个用 Rust 编写的 CLI 工具,为 Claude Code、Codex 和 Grok Build 提供一次性、可销毁的隔离虚拟机环境。本文讲解如何用 Nix 可复现地安装 coop(nix build + nix profile add),并深入剖析 flake 依赖锁定机制与 musl 跨平台交叉编译的完整流程——无论是普通用户还是贡献者,读完都能做到"在任何机器上,构建出完全相同的二进制"。

为什么 coop 需要可复现的依赖管理

coop 的仓库是一个 Cargo workspace,包含两个二进制:

二进制 职责
coop 主 CLI,管理 Firecracker(Linux)/ Lima(macOS)虚拟机
coop-proxy 宿主机侧的凭证注入反向代理

其中 coop-proxy 依赖 aws-lc-sys 这个 C 库,构建时必须依赖 CMake + 原生 musl 编译器(见 coop-proxy/Cargo.toml)。这类"原生依赖"正是传统构建中最难复现的部分:不同机器上 cmake 版本、C 编译器版本稍有差异,产物就可能不同。

Nix 的方案是:把所有输入钉死。coop 的 flake 通过 flake.lock 锁定 nixpkgs 和 rust-overlay 的精确 rev + 哈希,Rust 工具链版本则由 rust-toolchain.toml 钉在 1.94.0,Cargo 侧再由 Cargo.lock + strictDeps 保证依赖树完全一致。

Nix 安装前提:版本要求与源码准备

📦 以下命令要求 Nix 2.30 或更新版本(nix profile add 是 2.30 引入的),并启用 nix-command 与 flakes 两个实验特性。用 nix --version 检查版本。

git clone https://gitcode.com/gh_mirrors/coop9/coop
cd coop

三步用 Nix 安装 coop

第一步:nix build 本地构建

在仓库目录中执行:

nix build
./result/bin/coop --version

result/bin 下同时包含 coop 和 coop-proxy 两个二进制——安装时必须让它们留在同一目录,因为代理模式会在 coop 旁边查找 coop-proxy。

第二步:nix run 免安装快速验证

不想先安装?直接运行:

nix run . -- --help

第三步:nix profile add 正式安装

nix profile add .#coop

显式的 .#coop 输出名会把 profile 条目命名为 coop,与目录名无关。如果你之前用 nix profile add . 装过,先用 nix profile list 确认旧条目名,再用旧名执行升级/移除。

macOS 与 Linux 的差异:

  • 🍎 macOS:Nix 包已内置 Lima 及宿主命令行工具(lima、coreutils、curl、git、gnutar、openssh、rsync,见 flake.nix),因此 nix run . -- setup 不需要额外安装 Homebrew。
  • 🐧 Linux:Nix 包不包含 Firecracker 主机依赖,需按 平台前置要求 自行安装 KVM、e2fsprogs 等,并保持它们在 PATH 上。

完成后执行 coop setup 构建 VM 模板镜像即可开始使用。

Nix 安装的升级与卸载方法

Nix 安装的 coop 会自我标识为 dev build,因此 coop update 和后台版本通知是禁用的——升级由 Nix 管理:

# 1. 更新本地 checkout 后
nix profile upgrade coop

# 2. 有意更新被锁定的 Nix 输入(nixpkgs / rust-overlay)
nix flake update

卸载时不要使用 sudo coop uninstall 或直接删除 store 路径——coop uninstall 在任何数据被改动之前都会拒绝操作 Nix store 中的二进制(即使带 --yes/--purge)。正确的做法是:

nix profile remove coop

这不会触碰 VM 实例、镜像和配置数据,详见 docs/getting-started.md。

nix develop:一条命令进入开发环境

贡献者无需手动装工具链。nix develop 提供的开发 shell 包含:

  • rust-toolchain.toml 中固定的 Rust 工具链(含 rustfmt、clippy)
  • CMake、Git、OpenSSH、Python 3;macOS 上还会附带 Lima 及打包 CLI 所需的宿主工具
nix develop
./scripts/install-dev-tools.sh          # 安装钉住版本的开发工具
cargo fmt -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

另外两个常用命令:nix flake check 会构建包并运行当前平台的单元测试 + 安装检查;nix fmt 负责格式化 flake 本身。完整说明见 CONTRIBUTING.md 的 Nix 章节。

flake.nix 依赖锁定原理拆解

flake.nix 的核心结构值得新手学习:

  • 输入只有两个:nixpkgs-unstable 与 rust-overlay(Rust 工具链来源),且 rust-overlay 的 nixpkgs 通过 follows 复用同一份,避免版本漂移(flake.nix)。
  • 三平台覆盖:aarch64-darwin、aarch64-linux、x86_64-linux,其中 macOS 目标专为 Apple Silicon + Lima 准备(flake.nix)。
  • 工具链同源:rust-bin.fromRustupToolchainFile 直接从 rust-toolchain.toml 读取版本,Nix 与 rustup 永不失同步。
  • 严格依赖:strictDeps = true + cargoLock.lockFile = ./Cargo.lock,Nix 构建只允许使用锁文件声明的版本。

跨平台交叉编译:三个发布目标

官方发布的三个 target

coop 的 Linux 二进制采用 musl 静态链接,单文件即可运行、无 glibc 依赖:

Target 三元组 平台
aarch64-apple-darwin macOS(Apple Silicon)
x86_64-unknown-linux-musl Linux x86_64
aarch64-unknown-linux-musl Linux arm64

三元组检测逻辑见 install.sh。注意 aws-lc-sys 的 C 后端必须用 CMake + 与目标同架构的原生 musl 编译器构建,所以官方 release 流程是在匹配架构的原生 runner 上分别构建,而不是交叉编译(RELEASING.md)。

macOS 交叉编译到 Linux 的完整流程

项目已内置两个 musl 目标的 Cargo linker 配置:x86_64-unknown-linux-musl 使用 x86_64-linux-musl-gcc,aarch64-unknown-linux-musl 使用 aarch64-linux-musl-gcc。装好对应交叉编译器后,若命名与默认不一致,需显式设置目标级变量(见 docs/backends.md 与 RELEASING.md):

export CC_x86_64_unknown_linux_musl=x86_64-linux-musl-gcc
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER=x86_64-linux-musl-gcc
export CC_aarch64_unknown_linux_musl=aarch64-linux-musl-gcc
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=aarch64-linux-musl-gcc

集成测试脚本把这个流程自动化了——交叉编译 release 构建、scp 到远端 Linux 主机、再在那边跑完整测试套件:

./tests/run-integration.sh --remote user@remote-host

用 Nix 为其他平台构建

由于 flake 为三个系统都声明了包,可以直接指定 --system 让 Nix 为目标平台构建(必要时借助 QEMU 模拟):

nix build .#coop --system x86_64-linux
nix build .#coop --system aarch64-darwin

只做编译检查(不产出二进制)

改了平台相关 #<a href="https://link.gitcode.com/i/500c85d55e3803e0d8b6a552937fc9cf" target="_blank">cfg] 分支时,可以用交叉目标做编译级验证(cargo check/clippy 加 --target),方法见 [docs/testing.md;macOS 用户还可用 tests/run-linux-unit.sh 在 Docker 容器中跑 Linux 单元测试。

关键文件清单

文件 作用
flake.nix flake 定义:包、checks、devShell、formatter
flake.lock 锁定 Nix 输入的 rev 与哈希
rust-toolchain.toml 固定 Rust 1.94.0 工具链
Cargo.toml workspace 定义(coop + coop-proxy)
install.sh 预编译二进制安装脚本(SHA-256 + Sigstore 验证)
scripts/preflight-release.sh 发版前全量检查,含三 target 本地构建
tests/run-integration.sh 集成测试,支持 --remote 跨平台
docs/getting-started.md Nix 安装官方文档
RELEASING.md 发版流程与不可变 tag 规则

💡 小结:Nix 让 coop 的"依赖管理"从口号变成机制——输入锁定、工具链同源、严格依赖三件套,让 nix build 在任何机器上都产出可预期的二进制;而 musl 静态链接 + 原生编译策略,则保证了三个平台发布目标的一致性与可验证性。

登录后查看全文
coop