disko 声明式磁盘分区：把分区表写成 Nix 表达式

① 设备名漂移：/dev/sda 与 /dev/nvme0n1 在不同机型上指的不是同一块盘
② 顺序耦合：必须严格按"分区→加密→建文件系统→建子卷→挂载"执行
③ 无幂等：重复执行 mkfs 会清空数据，无法"再跑一次看看"

disk
 └── content: gpt
      ├── partitions.ESP   → content: filesystem(vfat) → mountpoint /boot
      └── partitions.root  → content: luks
                               └── content: btrfs
                                    ├── subvolumes./root → mountpoint /
                                    └── subvolumes./nix  → mountpoint /nix

# disko-config.nix —— 单盘 GPT + LUKS + Btrfs 子卷
{
  disko.devices.disk.main = {
    type = "disk";
    # 关键：用 by-id 而不是 /dev/sda，避免设备名漂移
    device = "/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_0000";
    content = {
      type = "gpt";
      partitions = {
        ESP = {
          size = "1G";
          type = "EF00";                       # EFI System Partition
          content = {
            type = "filesystem";
            format = "vfat";
            mountpoint = "/boot";
            mountOptions = [ "umask=0077" ];
          };
        };
        root = {
          size = "100%";
          content = {
            type = "luks";
            name = "cryptroot";
            settings.allowDiscards = true;      # SSD TRIM 穿透
            passwordFile = "/tmp/luks.key";     # 安装期临时密钥
            content = {
              type = "btrfs";
              extraArgs = [ "-f" ];
              subvolumes = {
                "/root" = { mountpoint = "/";     mountOptions = [ "compress=zstd:3" "noatime" ]; };
                "/nix"  = { mountpoint = "/nix";  mountOptions = [ "compress=zstd:3" "noatime" ]; };
                "/home" = { mountpoint = "/home"; mountOptions = [ "compress=zstd:3" "noatime" ]; };
                "/swap" = { mountpoint = "/.swap"; swap.swapfile.size = "16G"; };
              };
            };
          };
        };
      };
    };
  };
}

- ESP 单独 1G：足够容纳多个内核与引导项，避免 /boot 满导致升级失败
- 根分区 100%：单盘场景下不留空洞，扩容留给 LVM 或多盘
- 子卷分离 /nix 与 /home：/nix 可单独快照与回滚，不影响用户数据
- swapfile 放独立子卷：便于单独设置 nodatacow，也避免快照把 swap 内容带进去
- allowDiscards：SSD 上必须开，否则长期使用后写入放大明显
- 子卷的键与 mountpoint 写成同一个字符串，最不容易写反

# 两块盘做 PV，卷组上切 root 与 home
disko.devices = {
  disk.a = { type = "disk"; device = "/dev/disk/by-id/disk-a"; content = { type = "gpt";
    partitions.data = { size = "100%"; content = { type = "lvm_pv"; vg = "pool"; }; }; }; };
  disk.b = { type = "disk"; device = "/dev/disk/by-id/disk-b"; content = { type = "gpt";
    partitions.data = { size = "100%"; content = { type = "lvm_pv"; vg = "pool"; }; }; }; };
  lvm_vg.pool = { type = "lvm_vg";
    lvs.root = { size = "100G";     content = { type = "filesystem"; format = "ext4"; mountpoint = "/"; }; };
    lvs.home = { size = "100%FREE"; content = { type = "filesystem"; format = "ext4"; mountpoint = "/home"; }; };
  };
};

# 全新安装：销毁 + 格式化 + 挂载（最常用，也最危险）
sudo disko --mode destroy,format,mount ./disko-config.nix

# 只挂载已有磁盘：不碰数据，用于 chroot 修复
sudo disko --mode mount ./disko-config.nix

# 只看会做什么，不真做：任何模式都应先跑一次
sudo disko --mode destroy,format,mount --dry-run ./disko-config.nix

--dry-run 会打印将要执行的命令序列：
  sgdisk --zap-all /dev/nvme0n1
  sgdisk -n 1:... -t 1:EF00 ...
  cryptsetup luksFormat --type luks2 ...
  mkfs.btrfs -f /dev/mapper/cryptroot
  btrfs subvolume create ...
逐条核对设备路径与分区类型码，这一步能挡掉绝大多数误操作。

- destroy 不可逆：确认 device 指向 by-id 而不是可能变化的符号链接
- 生产机上永远不要跑 destroy，除非确定这块盘可以被清空
- 有数据的盘在 format/mount 前，先 lsblk -f 看清现状
- 把 disko 配置与 NixOS 配置放在同一个 flake 里，评审时一起看

# flake.nix
{
  inputs.disko.url = "github:nix-community/disko";
  outputs = { self, nixpkgs, disko, ... }: {
    nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        disko.nixosModules.disko      # ← 关键：提供 disko 选项并派生 fileSystems
        ./disko-config.nix            # 上面那份配置
        ./configuration.nix
      ];
    };
  };
}

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

# 反例：密钥文件被写进 store，任何能读 /nix/store 的人都能拿到
passwordFile = ./luks.key;

# 正解一：安装期用临时路径，装完立即删除
passwordFile = "/tmp/luks.key";

# 正解二：从远程安装端推送密钥（nixos-anywhere 的 --disk-encryption-keys）

# 安装期先用临时密钥，装好后追加一个正式密钥槽，再移除临时槽
sudo cryptsetup luksAddKey /dev/disk/by-id/nvme-... /root/luks.key
sudo cryptsetup luksRemoveKey /dev/disk/by-id/nvme-... /tmp/luks.key
sudo cryptsetup luksDump /dev/disk/by-id/nvme-... | grep -A2 Keyslots

boot.initrd.luks.devices.cryptroot = {
  device = "/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_0000-part2";
  allowDiscards = true;   # 与 disko 中的 settings.allowDiscards 保持一致
  preLVM = true;
};

若机器需要自动重启（无人在场输入口令）：
  方案一：密钥文件放在 initrd 可读的独立未加密分区（安全性下降，但可用）
  方案二：用 TPM2 绑定（systemd-cryptenroll --tpm2-device=auto）自动解锁
  方案三：网络解锁（clevis / initrd 中的 dropbear）
disko 负责"怎么建"，解锁策略属于 initrd 配置，两者必须保持设备路径一致。

disko.devices = {
  disk.a = { type = "disk"; device = "/dev/disk/by-id/disk-a"; content = { type = "gpt";
    partitions.zfs = { size = "100%"; content = { type = "zfs"; pool = "tank"; }; }; }; };
  zfs.tank = {
    type = "zfs";
    pool = "tank";
    root = { type = "zfs_fs"; options.mountpoint = "none"; };
    datasets = {
      "tank/root" = { type = "zfs_fs"; options.mountpoint = "/"; };
      "tank/nix"  = { type = "zfs_fs"; options.mountpoint = "/nix"; };
      "tank/home" = { type = "zfs_fs"; options.mountpoint = "/home"; };
    };
  };
};

boot.supportedFilesystems = [ "zfs" ];
boot.zfs.forceImportRoot = false;      # 用 hostId 而不是强制导入
networking.hostId = "0a1b2c3d";        # ZFS 要求稳定的 hostId，务必显式设置

# checks 里验证 disko 配置是否可用
{ pkgs, inputs, ... }:
pkgs.testers.runNixOSTest {
  name = "disko-single-disk";
  nodes.machine = { lib, ... }: {
    virtualisation.emptyDiskImages = [ 4096 ];     # 4G 空白盘
    imports = [ inputs.disko.nixosModules.disko ./disko-config.nix ];
    disko.devices.disk.main.device = lib.mkForce "/dev/vdb";   # 虚拟机无 by-id
    boot.loader.grub.enable = false;
  };
  testScript = ''
    machine.start()
    machine.wait_for_unit("multi-user.target")
    machine.succeed("findmnt -n -o FSTYPE / | grep -q btrfs")
    machine.succeed("findmnt -n -o OPTIONS /nix | grep -q 'subvol=/nix'")
    machine.succeed("swapon --show | grep -q swapfile")
  '';
}

价值：
  - 分区方案改错（子卷名拼错、挂载点冲突）在 CI 就能暴露，不必等真机装完
  - 加密容器能在虚拟机里真实创建与打开，验证密钥路径是否可用
  - 与 nixosTest 生态一致，可纳入 flake 的 checks
取舍：
  - 虚拟盘容量给足（≥4G），否则 Btrfs 元数据与 swapfile 会失败
  - LUKS 在测试中用固定口令，避免依赖交互
  - 断言落在"文件系统类型/挂载选项/swap 是否生效"这类可观测事实上

# 错误：不同机器上 /dev/sda 可能是系统盘也可能是数据盘
device = "/dev/sda";
# 正确：用 by-id（或 by-path）
ls -l /dev/disk/by-id/ | grep nvme

症状：装完后 /nix 是空的，nix 命令找不到 store
原因：subvolumes 的键是"子卷名"、mountpoint 是"挂载点"，两者写反
处理：把键与 mountpoint 写成同一个字符串，从根上避免

症状：nixos-rebuild 时报 No space left on device（/boot）
原因：ESP 只给了 100M，装不下多个内核 + initrd
处理：给到 512M~1G；已装机器可清理旧内核或改用 systemd-boot

症状：error: The option 'fileSystems."/"' is used but not defined
原因：disko.nixosModules.disko 未引入，派生逻辑没生效
处理：加进 modules 列表，同时删掉手写的 fileSystems

症状：重启后卡在 Waiting for device /dev/disk/by-id/...-part2
原因：disko 配置里的分区顺序变了（如 ESP 与 root 调换），part2 不再指向加密分区
处理：先 blkid 确认真实分区号，再同步修改 boot.initrd.luks.devices

症状：启动时报 pool tank cannot be imported: hostid mismatch
处理：显式设置 networking.hostId；首次导入可临时用 forceImportRoot = true 引导一次