NixOS 网络问题排查：二进制缓存（Binary Cache）原理与离线/自建缓存实战
【免费下载链接】nixpkgsNix Packages collection & NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs
导读
Nix 生态的核心优势之一是**二进制缓存（binary cache）**机制：当nixos-rebuild等命令需要某个 Nix store 路径时，Nix 会优先从互联网下载预编译好的二进制产物，而不是从源码重新构建。本篇指南以 NixOS 官方手册 Network Problems 章节 为主线，结合 nixos/modules/config/nix.nix 的源码实现，深入讲解二进制缓存的原理、网络故障时的临时规避手段（--option use-binary-caches false）、如何切换/自建替代缓存，以及如何在 NixOS 配置中声明式地管理缓存源与签名校验。读完本文，你将能在缓存不可达、构建超时、离线环境等场景下快速定位并解决网络问题。
二进制缓存：Nix 的"下载优先"机制
Nix 将一切产物（包、依赖、补丁等）统一放进全局只读的 Nix store（/nix/store），并以内容寻址的 hash 作为路径标识。正是这种确定性结构，让"下载预编译产物"成为可能：
- 有缓存命中：某条 store 路径已经存在于某个二进制缓存中，且签名可信，Nix 直接下载解压，秒级完成；
- 无缓存命中：Nix 才退回到本地构建，从源码开始编译，可能耗费数分钟到数小时。
手册原文明确说明（network-problems.section.md）："每当nixos-rebuild之类的命令需要某个 Nix store 中的路径时，Nix 会尝试从互联网下载该路径，而不是从源码构建。"
默认缓存与连接超时问题
Nix 默认的二进制缓存是https://cache.nixos.org/。在 nixos/modules/config/nix.nix 的config中可以看到 NixOS 模块层写入的默认配置：
nix.settings = { trusted-public-keys = [ "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" ]; trusted-users = [ "root" ]; substituters = mkAfter [ "https://cache.nixos.org/" ]; };关键问题场景：当该缓存不可达（断网、被墙、DNS 故障、代理异常）时，Nix 操作并不会立即失败，而是会经历多次HTTP 连接超时（connection timeout）后才逐个降级。由于 Nix 需要尝试下载大量 store 路径，每次超时叠加起来，最终导致nixos-rebuild等操作异常缓慢——这正是手册该章节要解决的核心痛点。
临时禁用二进制缓存：--option use-binary-caches false
针对"缓存不可达导致长时间卡顿"的场景，手册给出了最快的临时解法——在命令中直接追加：
# nixos-rebuild switch --option use-binary-caches false执行该命令后，本次nixos-rebuild switch完全不访问任何二进制缓存，所有缺失路径一律从本地源码构建。适用场景：
- 网络故障时希望立即恢复操作（代价是本地编译变慢）；
- 排查"到底是网络问题还是构建问题"；
- 离线/内网环境临时应急。
需要说明的是，use-binary-caches属于 Nix 早期的旧式选项命名。从 Nix 2.x 起，术语统一为substitute（替换/替代源），NixOS 模块也为此提供了完善的迁移兼容层。在 nixos/modules/config/nix.nix 的legacyConfMappings中可看到完整映射关系：
legacyConfMappings = { useSandbox = "sandbox"; buildCores = "cores"; maxJobs = "max-jobs"; binaryCaches = "substituters"; trustedBinaryCaches = "trusted-substituters"; binaryCachePublicKeys = "trusted-public-keys"; autoOptimiseStore = "auto-optimise-store"; requireSignedBinaryCaches = "require-sigs"; ... };也就是说，如果你在配置或命令中仍见到binaryCaches、trustedBinaryCaches、binaryCachePublicKeys这类写法，NixOS 模块会通过mkRenamedOptionModuleWith（同文件第 139-153 行）自动迁移到substituters、trusted-substituters、trusted-public-keys。对应地，--option binary-caches的现代等价写法是--option substituters。
切换替代二进制缓存
如果你手头有可用的替代缓存（例如自建 Hydra、第三方缓存、局域网镜像、云厂商 Nix 缓存等），手册给出了临时切换方法：
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/该命令告诉本次构建：使用http://my-cache.example.org/作为二进制缓存（--option binary-caches在现代 Nix 中即--option substituters，多个地址以空格分隔）。
自建缓存的常见形态
结合 NixOS 生态，常见可用的替代缓存包括：
- 自建 Hydra（
https://hydra.nixos.org/即为 NixOS 官方 CI 的缓存，其本身也可作为替代源示例）； - nix-serve / nix-serve-ng提供的内网轻量缓存服务；
- 组织内部的 HTTP/HTTPS 镜像或对象存储（OSS/S3）缓存。
注意--option仅对单次命令生效，属于临时手段；若想让替代缓存长期生效，应使用下方声明式配置。
签名校验：为什么需要 trusted-public-keys
使用第三方缓存不是"拿来即用"这么简单。Nix 的安全性基石在于密码学签名：二进制缓存中的每个 NAR（Nix Archive）必须使用对应公钥验证通过，Nix 才会使用。
- 默认配置只信任
cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=这一个公钥（见 nix.nix）； - 使用自建/第三方缓存时，必须把该缓存的签名公钥追加到
trusted-public-keys，否则 Nix 会拒绝使用其中的二进制产物并回退到源码构建（表现为"明明配了缓存却还是编译"）。
对应选项的语义（nix.nix）：
| 选项 | 含义 | 默认/示例 |
|---|---|---|
nix.settings.substituters | 用于获取预编译二进制的缓存 URL 列表 | 默认追加https://cache.nixos.org/ |
nix.settings.trusted-substituters | 允许非 root 用户通过--option substituters额外指定的缓存 | 默认[]，示例https://hydra.nixos.org/ |
nix.settings.trusted-public-keys | 校验缓存签名所用的公钥列表 | 默认仅cache.nixos.org-1:... |
nix.settings.require-sigs | 是否强制要求并校验签名 | 默认true |
手册同样强调：trusted-substituters允许普通（非 root）用户通过命令行临时指定额外缓存；而require-sigs若被关闭（不建议），Nix 将既不要求也不检查签名——此时务必只使用可信缓存与 HTTPS，以防中间人攻击（见 nix.nix 的警告描述）。
NixOS 声明式配置：把缓存策略写进 configuration.nix
临时--option适合应急，生产环境应把缓存策略声明式地固化到系统配置中。在 NixOS 的configuration.nix里加入：
{ nix.settings = { # 追加替代缓存（默认 cache.nixos.org 仍然保留） substituters = [ "https://cache.nixos.org/" "https://my-cache.example.org/" ]; # 追加自建缓存的签名公钥（务必从缓存提供方获取） trusted-public-keys = [ "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" "my-cache.example.org-1:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=" ]; }; }执行nixos-rebuild switch后，配置会被写入/etc/nix/nix.conf（源码见 nix.nix 的environment.etc."nix/nix.conf".source = nixConf;），对所有 Nix 命令全局生效。
一些实用技巧：
- 验证当前生效配置：运行
nix-instantiate --eval --strict '<nixpkgs/nixos>' -A config.nix.settings查看展开后的实际值（该命令正是 nix.nix 的description中给出的官方建议）； - 优先级叠加：NixOS 模块用
mkAfter追加默认缓存，保证cache.nixos.org始终在列表末尾兜底（nix.nix）； - 信任用户：
trusted-users默认只有root（nix.nix），非 root 用户若要临时指定替代缓存，需要相应配置trusted-substituters或trusted-users； - 离线/内网永久禁用：若确定环境完全离线，可在
nix.settings.substituters中移除所有远程缓存地址，迫使系统始终本地构建。
与网络故障相关的周边排查要点
手册所属的 troubleshooting.chapter.md 汇集了系统级故障排查章节，网络问题常与以下情况伴随出现，可一并参考：
- DNS / 代理问题：
cache.nixos.org域名解析失败或 HTTPS 代理配置错误，症状与缓存不可达高度相似； - 沙箱 fallback：NixOS 模块默认
nix.settings.sandbox-fallback = false（nix.nix），沙箱不可用时会直接报错而非静默降级，可借此区分是网络问题还是沙箱问题； - 构建替代流程：Nix 的完整解析顺序是"本地 store 命中 → 远程 substitute 命中 → 本地构建"，网络故障只影响第二步，理解这一点有助于快速定位卡点。
小结
面对"Nix 操作因缓存不可达而长时间卡顿"的问题，本文给出三条递进式解决路径：
- 立即恢复：
nixos-rebuild switch --option use-binary-caches false（现代等价写法为--option substituters ""），临时禁用下载、强制本地构建； - 切换源：
--option binary-caches http://my-cache.example.org/指定替代缓存（注意配套公钥与签名校验）； - 长期固化：在
configuration.nix的nix.settings.substituters/trusted-public-keys中声明式配置，并可通过nix-instantiate验证展开结果。
从源码层面看，这些命令与配置的底层实现统一收敛在 nixos/modules/config/nix.nix 的legacyConfMappings、nixConf生成逻辑以及nix.settings选项定义中——旧式binary-caches命名与新的substituters命名在这里完成兼容迁移，理解这一点后，无论你在手册、配置还是命令行中看到哪种写法，都能正确对应与使用。
【免费下载链接】nixpkgsNix Packages collection & NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
