nixos-anywhere 远程部署：把裸机变成 NixOS

kexec 的语义：把另一个内核加载进内存并直接启动，跳过固件与引导器
于是目标机当前的系统（Ubuntu/Debian/厂商镜像）在引导后完全消失
后续所有操作都发生在一个"内存中的 NixOS"里
结果：分区与安装过程不依赖原系统，因而完全可复现

适合：
  - 云 VPS / 托管裸机，只有 root SSH
  - 需要批量重建同样配置的一批机器
  - 需要 LUKS 加密根分区（安装期必须由安装环境处理）
不适合：
  - 目标机无法 kexec（某些虚拟化平台禁用、或架构不匹配）
  - 内存过小（安装环境跑在 tmpfs 上，通常建议 ≥1G 可用内存）
  - 目标机是 Windows 或需要保留既有系统做双启动

① 用 SSH 连上目标机（默认 root@target）
② 探测架构（x86_64-linux / aarch64-linux）与内存
③ 上传一个最小引导包（kexec 工具 + 目标内核 + initrd）

④ 目标机执行 kexec，重启进 NixOS 安装环境（运行在 RAM 中）
⑤ 安装环境里启动 sshd，等待控制端连接
⑥ 控制端把 disko 配置、flake 的 store 闭包推送过去

⑦ 在安装环境里执行 disko（destroy/format/mount）完成分区与加密
⑧ 执行 nixos-install 把系统写进目标盘
⑨ 注入密钥、host key 等额外文件
⑩ 重启进新系统

# 默认在本地构建并推送
nixos-anywhere --flake .#host --target-host root@203.0.113.10

# 指定在别的机器上构建（本地是 macOS 或算力不足时）
nixos-anywhere --flake .#host --target-host root@203.0.113.10 \
  --build-on remote --build-on-remote-host builder@10.0.0.5

# 云控制台或厂商面板里重置 root 密码 / 上传 SSH 公钥
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@203.0.113.10
ssh root@203.0.113.10 'uname -m; free -m | head -2'

# flake.nix
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
  inputs.disko.url = "github:nix-community/disko";

  outputs = { self, nixpkgs, disko, ... }: {
    nixosConfigurations.web01 = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        disko.nixosModules.disko
        ./hosts/web01/disko.nix      # 分区方案（见 disko 篇）
        ./hosts/web01/default.nix    # 系统配置
      ];
    };
  };
}

nixos-anywhere --flake .#web01 --target-host root@203.0.113.10

# 安装完成后目标机会重启，SSH host key 会变，需要清理旧记录
ssh-keygen -R 203.0.113.10
ssh root@203.0.113.10

# 只做前两个阶段，装完不重启，便于登进去检查
nixos-anywhere --flake .#web01 --target-host root@203.0.113.10 --phases kexec,disko,install --no-reboot

# 只跑 disko（目标机已在安装环境中）
nixos-anywhere --flake .#web01 --target-host root@203.0.113.10 --phases disko

kexec  → disko  → install
  kexec : 上传引导包并在目标机执行 kexec
  disko : 在安装环境里按 disko 配置分区、格式化、挂载
  install : 执行 nixos-install 并注入 extra-files，然后重启

# CI 里先构建好，再安装时直接推 store 路径，避免二次构建
nixos-anywhere --flake .#web01 --target-host root@203.0.113.10 \
  --store-paths "$(nix build .#nixosConfigurations.web01.config.system.build.toplevel --print-out-paths)"

# 生成一次性密钥，安装期用它加密根分区，装完立刻删除
head -c 64 /dev/urandom > /tmp/luks.key
nixos-anywhere --flake .#web01 --target-host root@203.0.113.10 \
  --disk-encryption-keys /tmp/luks.key
rm -f /tmp/luks.key

# --extra-files 指向一个目录，安装后按相对路径复制到目标系统根
mkdir -p extra/etc/ssh extra/root/.ssh
cp /etc/ssh/ssh_host_ed25519_key* extra/etc/ssh/
cp ~/.ssh/authorized_keys extra/root/.ssh/authorized_keys
chmod 600 extra/etc/ssh/ssh_host_ed25519_key

nixos-anywhere --flake .#web01 --target-host root@203.0.113.10 \
  --extra-files ./extra

nixos-anywhere 负责"把系统装上"，不负责长期密钥管理
长期密钥（服务凭据、TLS 私钥、API token）应走 sops-nix / agenix：
  - 加密文件进 git
  - 解密密钥在机器上就位（可用 --extra-files 注入一次）
  - 由 systemd 服务在启动时解密
见本专题的密钥管理篇。

- LUKS 密钥用临时文件，安装后立即删除，绝不写进 flake 或 store
- 不要把私钥作为 --extra-files 的一部分长期留在目标机（除 host key 与公钥外）
- CI 里用 secret 注入，不要 echo 到日志

flake.nix
hosts/
  web01/
    default.nix        # 系统配置（模块化，引用 common/）
    disko.nix          # 分区方案
    hardware.nix       # 生成的硬件配置（可选）
modules/
  common.nix           # 所有机器共享：时区、SSH、用户、防火墙

# 方式一：安装时让工具生成（在安装环境里探测）
nixos-anywhere --flake .#web01 --target-host root@IP --generate-hardware-config nixos-generate-config ./hosts/web01/hardware.nix

# 方式二：先装一次最小系统，登进去执行 nixos-generate-config 再合并
# 方式三：云主机场景下磁盘与网卡都很标准，可以手写最小配置

同一份 hosts/web01 配置：
  - nixos-anywhere 用于远程裸机
  - disko --mode destroy,format,mount 用于本地 U 盘安装
  - runNixOSTest + emptyDiskImages 用于 CI 验证
三者共用 disko.nix 与 default.nix，因此不存在"文档与实物不符"的问题。

# hosts/web01/default.nix
{ config, pkgs, ... }: {
  imports = [ ../../modules/common.nix ];
  networking.hostName = "web01";
  services.openssh = {
    enable = true;
    settings.PermitRootLogin = "prohibit-password";
  };
  users.users.root.openssh.authorizedKeys.keys = [
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@laptop"
  ];
  system.stateVersion = "24.11";
}

# 对每台机器循环执行；先并行探测，再串行安装以免互相抢带宽
for h in web01 web02 web03; do
  ip=$(getent hosts "$h" | awk '{print $1}')
  nixos-anywhere --flake ".#$h" --target-host "root@$ip" --build-on remote \
    --build-on-remote-host builder@10.0.0.5
done

安装层面的回滚 = 重装（代价高，因此安装前必须确认配置正确）
系统层面的回滚 = NixOS 代际回滚（切换 generation，代价低）
建议：新配置先在一台机器上装一遍并观察，再批量推开；
      日常变更走代际回滚路径，不要依赖重装。

# 伪代码：构建 → 校验 → 安装 → 验证
jobs:
  install:
    steps:
      - run: nix build .#nixosConfigurations.web01.config.system.build.toplevel
      - run: nixos-anywhere --flake .#web01 --target-host root@${{ secrets.TARGET }}
               --store-paths "$(nix path-info -r ./result | grep toplevel | head -1)"
               --extra-files ./ci/extra
      - run: ssh -o StrictHostKeyChecking=yes root@${{ secrets.TARGET }} 'systemctl is-system-running --wait'

① 幂等性：CI 重跑意味着重装，因此只在"确认可清空"的机器上启用
② 密钥：LUKS 密钥与 SSH 私钥从 CI secret 注入，用完即弃
③ 验证：安装后用 systemctl is-system-running、ss -tlnp、nixos-rebuild dry-activate 校验

症状：目标机执行 kexec 后 SSH 断连且不再回来
原因：平台禁止 kexec、内核与目标架构不匹配、或内存不足
处理：
  - 确认 uname -m 与 flake 的 system 一致
  - 检查可用内存（free -m），安装环境跑在 tmpfs 上，建议 ≥1G
  - 部分平台需要先加载 kexec 内核模块：modprobe kexec

症状：kexec 后长时间等待 SSH，最后超时
原因：安装环境网络未起（DHCP 拿不到地址、网卡驱动缺失）
处理：改用带网卡驱动的自定义 kexec 镜像（--kexec），或临时在目标机所在网段抓包确认

症状：disko 阶段报 device not found
原因：设备路径写成了 /dev/sda，而实际是 /dev/nvme0n1；或 NVMe RAID 模式需要额外驱动
处理：安装环境里 lsblk -f 确认实际路径，改用 by-id

症状：重启后停在等待加密设备的提示
原因：initrd 里声明的设备路径与 disko 实际创建的分区号不一致
处理：blkid 确认分区号，同步 boot.initrd.luks.devices；确认 allowDiscards 一致

症状：第二次执行时 ssh 报 REMOTE HOST IDENTIFICATION HAS CHANGED
处理：用 --extra-files 注入固定 host key（推荐）；或脚本里 ssh-keygen -R

症状：本地是 aarch64 却要装 x86_64 机器，构建极慢或失败
处理：--build-on remote --build-on-remote-host 指定同架构构建机