CI+FlakeHub Cache：nix-config 实现零编译秒级配置更新的完整原理（just apply 指南）
【免费下载链接】nix-configWimpy's NixOS, nix-darwin & Home Manager Configurations ❄️项目地址: https://gitcode.com/gh_mirrors/nixco/nix-config
nix-config 是一个用单个 Nix Flake 统一管理 NixOS、nix-darwin 与 Home Manager 的系统配置仓库，它把CI 构建 + FlakeHub Cache 缓存结合在一起：每次代码推送到 main 分支，CI 会构建所有机器的完整配置并发布到 FlakeHub Cache，之后你在任何一台机器上运行just apply，就能跳过本地 Nix 求值与编译，直接拉取预构建好的配置闭包并激活，实现零编译的秒级配置更新。
一、为什么需要 CI + FlakeHub Cache？
管理十几台机器（工作站、笔记本、服务器、虚拟机）的配置时，传统流程是这样的：
- 修改配置 → 本地
nix build求值 + 编译，耗时几分钟到几十分钟； - 小机器（低配笔记本、服务器）编译更慢，还可能因磁盘空间不足失败；
- 多台机器各自编译同样的东西，算力严重浪费。
nix-config 的思路是：把"重活"全部交给 CI，本地只做"下载 + 激活"。
- GitHub Actions CI：每次 push 到
main，自动构建全部 NixOS / nix-darwin / Home Manager 配置（CI 流程定义在.github/workflows/builder.yml）。 - FlakeHub Cache：由 Determinate Systems 提供的 Nix 闭包缓存服务，CI 构建完成后把产物连同完整的输出路径（store paths）一起发布上去。
fhCLI：本地用它解析并下载预构建产物，just apply系列命令就建立在这之上。
结果就是：只要 CI 是绿的，你的机器就不需要编译任何东西。
二、CI 构建流水线：一次推送发生了什么
整个流水线可以概括为盘点 → 并行构建 → 门禁 → 发布四步（源码见.github/workflows/builder.yml）：
| 步骤 | 做什么 | 关键点 |
|---|---|---|
| 📋 Inventory 盘点 | 枚举 flake 的全部可构建输出，生成 GitHub Actions 并行矩阵 | 由 flake-inventory 脚本 完成惰性求值，约 50ms 每类，不触发任何深度求值 |
| 🔨 并行构建 | 每台 NixOS / nix-darwin 主机、每个 Home Manager 配置各占一个 runner 同时构建 | 单机 runner 磁盘只有 28–75GB，而单个 NixOS 闭包可达 15–30GB，按主机拆分是刚需 |
| 👁️ Sentinel 门禁 | 检查所有构建任务是否成功，并从 NixOS 版本号派生发布 tag | 任一任务失败则终止发布 |
| ❄️ Publish 发布 | flakehub-push以include-output-paths: true推送到 FlakeHub Cache | 有了输出路径，客户端才能fh apply |
两个值得新手记住的细节：
- 按主机并行构建：因为并行 runner 会在构建过程中持续向 FlakeHub Cache 推缓存，后面的 runner 还能搭前面 runner 的便车，整个 CI 从"串行 90 分钟以上"压缩到约 20 分钟（背景说明见 flake-inventory README）。
- PR 也构建，但只有 main 发布：Pull Request 会跑完整构建作为检查，但只有 main 分支才会推送到缓存，保证缓存里的内容始终是可信的。
三、just apply 原理：秒级更新的秘密
just apply系列命令的核心逻辑在 justfile 中，拆开看只有三步：
- 解析（resolve）：
fh resolve <flake引用>#<输出路径>先查询 FlakeHub Cache 上是否存在这份配置的预构建产物。查不到就直接报错退出，并提示是否以include-output-paths: true发布过——这一步保证了失败得快、失败得明白。 - 拉取并激活（apply）：
fh apply直接从缓存下载预构建的闭包并切换系统配置，完全不经过本地 flake 求值，也不触发任何 derivation 编译。Home Manager 走fh apply home-manager，NixOS/nix-darwin 走sudo fh apply nixos。 - 展示变化（diff）：激活前后对比系统 profile 的 store 路径，如果安装了
nvd，会自动nvd diff展示本次更新到底改了哪些包；NixOS 激活后还会顺带运行nixos-needsreboot检查是否需要重启。
用一句话概括：没有 flake 求值，没有编译，只有下载和激活—— 所以耗时取决于网络带宽，而不是 CPU。
⚠️ 一个重要的取舍：just apply应用的是最近一次从 main 发布的内容。如果你有未提交的本地改动，请改用just host/just home（本地构建后切换），不要混用。
四、常用 just 命令速查表
所有命令定义在 justfile，直接输入just可列出全部可用命令。
| 命令 | 作用 | 适用场景 |
|---|---|---|
⚡️just apply | 从 FlakeHub Cache 应用 NixOS/nix-darwin + Home Manager | 日常更新，秒级生效 |
⚡️just apply-home | 只应用 Home Manager 部分 | 只改了 dotfiles、应用配置 |
⚡️just apply-host | 只应用系统部分（NixOS/nix-darwin） | 只改了系统模块 |
🔍just resolve | 查询当前机器对应的配置是否已发布到缓存 | 排查"为什么 apply 失败" |
🐋just host/just home | 本地构建并切换（build + switch） | 有未提交的本地改动 |
🏗️just build/just switch | 分别只构建、只切换（系统 + Home） | 调试时拆开执行 |
🌍just push <主机> | 在本机构建，把闭包推送到远程主机并激活 | 管理远程服务器 |
🎟️just token-check | 检查 FlakeHub 令牌是否快过期（≤14/7/0 天会提醒） | 防止某天突然失效 |
🔐just detsys-login | 从 sops 加密文件中解密 FlakeHub 令牌并完成登录 | 换机/首次配置 |
几个新手容易踩的坑：
- 令牌过期：FlakeHub 令牌存放在 sops 加密的 secrets/secrets.yaml 中，
just detsys-login会自动解密并通过determinate-nixd登录；过期前just token-check会提前提醒你去换令牌。 - CI 未发布过：如果
fh resolve查不到配置，通常是该版本还没推送到 main，或发布任务没带include-output-paths，just apply的错误信息里也给了相应提示。 - 远程主机：远程机器的日常更新推荐
just push <主机名>—— 在你有算力的工作机上构建，再拷贝到目标机，小配置服务器完全不需要自己编译。
五、新手上手：三步体验秒级更新
第 1 步：克隆仓库并登录缓存
git clone https://gitcode.com/gh_mirrors/nixco/nix-config "$HOME/Zero/nix-config" cd "$HOME/Zero/nix-config" just detsys-login # 解密 sops 令牌并登录 FlakeHub第 2 步：确认本机的配置已发布
just resolve # 显示本机 NixOS 与 Home Manager 配置在缓存中的 store 路径第 3 步：应用更新
just apply # 一次更新系统 + 用户环境，通常几秒到几十秒内完成完成后终端会列出本次激活的差异（需要nvd），NixOS 还会提示是否需要重启。想确认这台机器最终呈现的样子？参考开头的 fastfetch 截图 —— 系统版本、内核、桌面环境、主题全部由这份配置声明式管理，而更新它的代价只是一次just apply。
六、总结：这套架构给配置管理带来的三个好处
- 🚀快：本地零编译，更新时间 = 下载时间；小机器、低配服务器不再受 CPU 限制。
- ✅稳：所有产物都来自同一份 CI 构建，13+ 台机器运行的是字节一致的闭包，杜绝"我这边能编你那边不能编"。
- 🧩可扩展：得益于 nix-config 的"广播+自门控"模块架构（每台主机引入全部模块，模块按主机元数据自行决定是否生效），新增功能只需放入一个目录；CI 的 flake-inventory 脚本 会自动发现新输出并把它纳入并行构建矩阵，几乎零维护成本。
一句话收尾：CI 负责把配置编译成现成的"系统快照"，FlakeHub Cache 负责把快照送到每台机器，just apply负责一键激活—— 这就是 nix-config 零编译秒级更新的完整闭环。
【免费下载链接】nix-configWimpy's NixOS, nix-darwin & Home Manager Configurations ❄️项目地址: https://gitcode.com/gh_mirrors/nixco/nix-config
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
