构建沙箱与可复现性：Nix 如何隔离构建过程

① 文件系统隐式输入：脚本读了未声明的 /etc/passwd、/usr/lib、家目录下的缓存
② 环境隐式输入：继承了宿主机的 LANG、TZ、HOME、PATH，行为随之漂移
③ 网络隐式输入：构建时下载依赖、拉取最新版本、访问私有 registry
这三类输入都不会出现在 .drv 里，因此哈希算不出来，缓存也命中不了。

症状 A：A 机器构建成功、B 机器失败（B 没装某个系统库）
症状 B：同一 commit 两次构建产物哈希不同（下载到了不同版本）
症状 C：本地能构建、CI 失败（CI 没有 ~/.cache 里的东西）
症状 D：二进制缓存命中率异常低（每次构建的输入其实都不同）

文件系统：只有 /nix/store 里声明过的路径（只读）+ 一个私有可写工作目录
环境变量：由 derivation 属性显式生成，宿主环境一律不带入
网络：默认不存在（除非是声明了输出哈希的固定输出派生）
身份：用专用的非特权构建用户，而不是当前用户

# /etc/nix/nix.conf；NixOS 上写 nix.settings.sandbox = true;
# sandbox = true | relaxed | false

Linux：沙箱依赖命名空间（user/mount/pid/ipc/net），能力完整
macOS：没有等价的内核原语，只能做有限限制，无法提供完整 chroot 隔离
结论：同一份 derivation 在 Linux 上更容易做到封闭，这也是 Linux 作为官方构建平台的原因

nix show-config | grep -E '^sandbox'
nix --version

① 创建新的命名空间：mount / pid / ipc / uts / net（以及 user，视配置）
② 挂载私有根文件系统：
     /nix/store      → 以只读方式绑定（整个 store 可见）
     /tmp、/build    → tmpfs，构建的工作目录 NIX_BUILD_TOP
     /dev            → 最小设备集（null、zero、random、urandom、tty 等）
     /proc           → 供脚本读取进程信息
     /etc            → 仅放入必要的静态文件（如 passwd、group、hosts）
③ 切换到专用的构建用户（build-users-group 中的 uid）
④ 清空环境变量，注入 derivation 派生的变量（$NIX_BUILD_TOP、$TMPDIR、$out）
⑤ 执行 builder（通常是 bash）

沙箱把整个 /nix/store 以只读方式暴露，而不是只暴露声明的依赖。
后果：
  - 构建脚本可以"恰好读到"某个未声明但已在 store 里的路径
  - 这次构建会成功，但该引用会被扫描进 .drv 的引用集，成为运行时依赖
  - 若依赖没有被正确声明，换一台没有该路径的机器就会失败
因此：沙箱防的是"宿主文件系统"，不能替代"依赖声明正确性"。

# NixOS 上指定构建用户组，构建以组内随机 uid 执行
nix.settings.build-users-group = "nixbld";

id nixbld1 2>/dev/null || getent group nixbld

宿主环境变量：一律不带入（PATH、HOME、LANG、TZ、SSH_AUTH_SOCK 全部消失）
derivation 属性：每个字符串属性变成一个同名环境变量
                  例如 buildInputs、nativeBuildInputs 会被拼成 PATH
固定注入：NIX_BUILD_TOP、TMPDIR、TMP、TEMP、TEMPDIR、PWD、HOME=/homeless-shelter
          NIX_STORE、NIX_BUILD_CORES、NIX_LOG_FD、out / outputHash 等

pkgs.stdenv.mkDerivation {
  pname = "demo";
  version = "1.0";
  MY_FLAG = "enabled";          # → 构建脚本里 $MY_FLAG 可用
  buildPhase = ''
    echo "flag=$MY_FLAG"        # 输出 flag=enabled
    echo "home=$HOME"           # 输出 home=/homeless-shelter
    echo "lang=$LANG"           # 输出 lang=（空，宿主 LANG 被丢弃）
  '';
}

# 明确列出允许穿透的环境变量（常用于固定输出下载的代理）
pkgs.fetchurl {
  url = "https://example.com/archive.tar.gz";
  hash = "sha256-...";
  impureEnvVars = [ "http_proxy" "https_proxy" "no_proxy" ];
}

# 更好的做法：不放行，而是把值作为属性显式传入构建

__structuredAttrs = true 会把属性以 JSON 形式传给构建脚本，
而不是展开成环境变量，避免超长环境变量与转义问题。

普通 derivation：没有网络出口，任何 curl / wget / git fetch 都会失败
失败信息通常形如：
  curl: (6) Could not resolve host: example.com
  fatal: unable to access 'https://...': Could not resolve host
这是设计意图，不是缺陷：构建期联网意味着产物依赖外部世界的当前状态。

# 声明了 outputHash 的派生（固定输出）允许联网，因为产物会被哈希校验
src = pkgs.fetchFromGitHub {
  owner = "NixOS";
  repo = "nixpkgs";
  rev = "24.11";
  hash = "sha256-AAAA...";      # 校验点：内容不符即失败
};

反模式：buildPhase 里直接 npm install / cargo fetch / pip download
改造步骤：
  ① 用固定输出派生把依赖预取到 store（如 npmDepsHash、cargoHash 对应的 fetch 派生）
  ② 构建阶段使用离线模式（npm ci --offline、cargo build --offline）
  ③ 校验：把网络彻底断掉后构建仍能成功
检查是否偷偷联网：
  nix build .#mypkg -L 2>&1 | grep -iE 'could not resolve|network is unreachable'

nix build .#mypkg --print-out-paths                          # 沙箱下构建
nix build .#mypkg --option sandbox false --print-out-paths   # 仅用于对比

判读：两者输出路径相同 → 没有读到宿主环境（纯净）
      输出路径不同 → 脚本依赖了未声明的东西，需要定位

# 强制重新构建并比较结果（可复现性的直接检验）
nix build .#mypkg --check -L

nix-store --query --references ./result      # 该产物的直接引用（运行时依赖）
nix why-depends ./result /nix/store/<某路径> # 为什么产物依赖某个路径
nix log .#mypkg | grep -E '/etc/|/usr/|/home/|/var/'   # 构建日志里的宿主路径痕迹

# 纯求值模式：禁止 builtins.currentSystem、getEnv 等不纯内建
nix eval --option pure-eval true .#packages.x86_64-linux.mypkg.drvPath

# 某些构建确实需要访问特定宿主路径（如虚拟机测试需要 /dev/kvm）
{
  requiredSystemFeatures = [ "kvm" ];
}
# 系统侧：nix.settings.extra-sandbox-paths = [ "/dev/kvm" ];

{ __noChroot = true; }   # 让该派生不做 chroot 隔离（历史遗留，尽量避免）
{ __impure  = true; }    # 显式声明"这个构建不保证可复现"

__impure 的代价：
  - 产物路径不可复现，二进制缓存无法有效复用
  - 依赖它的派生也无法稳定缓存
适用：确实无法封闭的构建（如需要访问本地设备的测试），且要隔离在依赖图边缘

遇到沙箱失败时的正确顺序：
  ① 先问：失败是否因为缺少声明？→ 补 buildInputs / nativeBuildInputs
  ② 再问：是否真的需要宿主路径？→ extra-sandbox-paths 精确添加
  ③ 最后才考虑：sandbox = relaxed 或 false（并记录原因与影响范围）

症状：error: while setting up the build environment: setting up a private
      mount namespace: Operation not permitted
原因：内核禁用了非特权用户命名空间，或所在容器限制了 clone/unshare
处理（按优先级）：
  ① 开启内核支持：sysctl kernel.unprivileged_userns_clone=1
  ② 容器里放开：docker run --privileged，或 --security-opt seccomp=unconfined
  ③ 确实无法放开时，退到 sandbox = relaxed

症状：error: the build users group 'nixbld' has no members
原因：容器镜像里没有创建 nixbld 用户
处理：在镜像里创建组与用户；或直接使用官方 nixos/nix 镜像

症状：脚本报 /etc/resolv.conf 或 /etc/passwd 缺失
正解：不要添加宿主 /etc，而是把需要的内容作为构建输入传进去
反例：extra-sandbox-paths = [ "/etc" ]  ← 直接把宿主环境泄漏进构建

症状：固定输出派生在企业代理后无法下载
处理：用 impureEnvVars 放行 http_proxy/https_proxy/no_proxy，
      而不是关沙箱（固定输出本身允许联网，缺的只是代理环境变量）

症状：macOS 上"关沙箱"与"开沙箱"构建结果一致，误以为沙箱无效
说明：macOS 的隔离能力有限，沙箱主要限制部分操作而非提供完整 chroot
处理：把可复现性验证放到 Linux 构建机上做，macOS 只做开发

docker run --rm -it --security-opt seccomp=unconfined \
  -v "$PWD:/src" -w /src nixos/nix:latest nix build .#mypkg

env:
  NIX_CONFIG: |
    sandbox = true
    experimental-features = nix-command flakes
    trusted-users = root runner

要点：
  - 保持 sandbox = true；若必须降级，在流水线里显式写注释说明原因
  - trusted-users 决定谁能使用额外的沙箱路径与 impure 特性，不要给普通用户
  - 与构建缓存配合：只有封闭构建才可能被安全共享，参见二进制缓存篇

沙箱保证"构建只依赖声明的东西"，这是可追溯的前提：
  - 产物 → derivation → 输入哈希 这条链才有意义
  - 若构建能读宿主文件或联网，链条断裂，产物来源无法证明
因此沙箱不是"安全加固的加分项"，而是供应链可验证性的基础设施。
需要设备（如 nixosTest 的 /dev/kvm）时：
  - 系统侧 extra-sandbox-paths = [ "/dev/kvm" ]
  - 派生侧 requiredSystemFeatures = [ "kvm" ]
  这样既保留沙箱，又精确放行了唯一需要的设备。