企业官网建设流程全解析

• 运维
• CLI

本文基于 archinstall 官方文档 docs/cli_parameters/config/disk_config.rst 展开，系统讲解disk_config选项仅有的三种磁盘配置模式（pre_mounted_config、default_layout、manual_partitioning）的 JSON 结构与使用方式，并结合 archinstall/lib/models/device.py、archinstall/lib/disk/device_handler.py 等源码解析配置解析、校验与落盘的实际实现。读完本文，你可以为 archinstall 编写一份可直接用于自动化安装的磁盘配置：从保留已有挂载、到一键默认布局、再到自定义分区表（含 BTRFS 子卷、压缩、EFI 引导标志）。

disk_config 的三种模式

disk_config是用户配置（--conf传入的 JSON）中的顶层键，在 config_options.csv 中被定义为“安装期间使用的目标磁盘布局”。它只有三种取值，对应源码中 DiskLayoutType 枚举：

三种模式在 TUI 中通过 select_disk_config() 呈现为互斥选项；在无人值守安装（--silent）中则由 JSON 直接指定。

模式一：pre_mounted_config —— 复用已有挂载（Leave as is）

{ "config_type": "pre_mounted_config", "mountpoint": "/mnt/archinstall" }

这是三种模式中配置最简的一种：archinstall不会做任何分区操作，而是完全依赖用户已经手动挂载到mountpoint（通常为/mnt/archinstall）下的文件系统。例如，假设磁盘已经呈如下状态挂载：

/mnt/archinstall (/dev/sda2) ├── boot (/dev/sda1) └── home (/dev/sda3)

执行archinstall --conf your.json --silent后，磁盘本身原封不动，系统会被安装进上述目录结构，而各挂载点会被翻译成新系统内的挂载路径并写入 fstab。

这一模式在源码中的落地是 DiskLayoutConfiguration.parse_arg()：当config_type为pre_mounted_config时，mountpoint为必填项，随后调用 device_handler.detect_pre_mounted_mods() 完成自动发现。该方法的实现逻辑是：遍历所有块设备的所有分区及其挂载点，凡挂载点位于指定基础挂载目录之下的分区，都会生成一条PartitionModification（状态为existing），并把挂载点从/mnt/archinstall/xxx重写为相对于新根的/xxx；BTRFS 分区的子卷挂载点同理逐个重写。仓库中的 examples/auto_discovery_mounted.py 展示了等价的 Python API 用法：先detect_pre_mounted_mods()，再用返回的mods构造DiskLayoutConfiguration。

原文档同时给出一个重要限制：一些过于复杂的磁盘布局（例如 RAID 组合）可能无法被自动识别，遇到这类情况建议到项目 Issue Tracker 报告，以便后续支持。

模式二：default_layout —— Best Effort 默认布局

警告：此模式会擦除所选磁盘上的数据！

{ "disk_config": { "config_type": "default_layout", "device_modifications": [ { "device": "/dev/sda", "wipe": true, "partitions": "..." } ] } }

Best Effort 模式会尝试在选中的磁盘上生成一套“合理”的默认布局。具体布局取决于你选择的文件系统，以及该文件系统的可选设置——不同组合会得到不同的默认分区方案。

从源码结构看，TUI 中选择该模式后会进入 get_default_partition_layout()：单磁盘走suggest_single_disk_layout()，多磁盘走suggest_multi_disk_layout()，两者都接收可选的filesystem_type参数，印证了文档所说“基于所选文件系统提供不同默认布局”的行为。

文档同时说明了两点值得注意的取舍：

1. 此模式与“手动分区”生成的结构类似，只是由菜单系统自动生成；
2. 为了让后续某些可选配置（如 BTRFS 子卷、快照）可行，默认布局可能与部分 Wiki 指南略有出入。

完整的真实配置可以直接参考 examples/config-sample.json：其中disk_config使用default_layout，对/dev/sda设置了wipe: true，并包含三个分区——512 MiB 的 fat32/boot（带boot标志）、20 GiB 的 ext4/、10 GiB 的 ext4/home。该样例同时演示了配置回写（round-trip）的稳定性，测试 tests/test_configuration_output.py 中的test_user_config_roundtrip会读取配置文件、重新序列化并比对关键字段。

模式三：manual_partitioning —— 手动分区

{ "disk_config": { "config_type": "manual_partitioning", "device_modifications": [ "filesystem struct" ] } }

手动分区是三种模式中最复杂的一种，提供近乎无限的分区自由度。它基于 pyparted 的类型桩与 archinstall 自身的控制逻辑（负责创建子卷、设置压缩等）。

顶层结构与每个条目的参数

manual_partitioning提供的device_modifications是一组字典定义，每个条目描述一块设备及其分区变更。官方参数表（manual_options.csv）如下：

此外，disk_config本身还支持若干可选附加键，可从源码中的 _DiskLayoutConfigurationSerialization 结构确认：lvm_config（LVM 卷组）、disk_encryption（LUKS 加密）、btrfs_options（快照配置）。其中加密配置通过分区条目的obj_id（一个 UUID）引用具体分区，机制详见 docs/cli_parameters/config/disk_encryption.rst——partitions列表中的 UID 就是 disk_config 条目里的obj_id。

尺寸单位与对齐规则

文档指出：尺寸默认以sector（扇区）为单位，但也支持其他单位。从 Unit 枚举 可确认全部受支持的单位：十进制单位B/kB/MB/GB/TB/PB/EB/ZB/YB、二进制单位KiB/MiB/GiB/TiB/PiB/EiB/ZiB/YiB，以及特殊的sectors（扇区数，需配合sector_size字段换算）。每个尺寸在 JSON 中都序列化为{value, unit, sector_size}三元组，例如：

{ "sector_size": { "unit": "B", "value": 512 }, "unit": "MiB", "value": 512 }

解析后的 Size 类 还实现了换算、对齐、比较等操作。这些能力直接体现在 DiskLayoutConfiguration.parse_arg() 对manual_partitioning的强制校验中，这也是手写配置时最容易被拒绝的地方：

1. 首分区起点：第一块待创建分区必须从 1 MiB 之后开始（is_valid_start()），否则抛出 “First partition must start at no less than 1 MiB”；
2. 禁止重叠：任一新建分区起点不能早于前一非删除分区的终点，否则抛出 “Partitions overlap”；
3. 对齐检查：所有新建分区的start与length必须已经按 1 MiB 对齐（Size.align()），否则抛出 “Partition is misaligned”；
4. GPT 尾部保留：若设备使用 GPT 分区表，最后一块分区不得越过保留区，否则会报 “Partition overlaps backup GPT header”；MBR 下则检查 “Partition too large for device”。

此外，配置中的device路径必须真实存在——parse_arg会先经device_handler.get_device()查询，查不到该设备的条目会被静默跳过（测试 test_configuration_output.py 的注释也印证了这一点：“被解析的配置会检查给定设备是否存在，否则忽略该修改”）。

示例一：FAT32 引导分区

每个分区定义的具体字段与所选文件系统强相关。以下是一个带boot标志的 FAT32 分区（文档原文示例）：

{ "btrfs": [], "flags": [ "boot" ], "fs_type": "fat32", "length": { "sector_size": null, "total_size": null, "unit": "B", "value": 99982592 }, "mount_options": [], "mountpoint": "/boot", "obj_id": "369f31a8-2781-4d6b-96e7-75680552b7c9", "start": { "sector_size": { "sector_size": null, "total_size": null, "unit": "B", "value": 512 }, "total_size": null, "unit": "sectors", "value": 34 }, "status": "create", "type": "primary" }

关于flags有一个关键行为：文档明确说明，Boot标志会让 archinstall 在系统以EFI方式启动时，自动将该分区设置为正确的 ESP 分区 GUID，即C12A7328-F81F-11D2-BA4B-00A0C93EC93B。标志名到 parted 标志的映射由 PartitionFlag 定义，支持的标志包括boot、bls_boot（xbootldr）、esp、linux-home、swap。

示例二：EXT4 根分区

{ "btrfs": [], "flags": [], "fs_type": "ext4", "length": { "sector_size": null, "total_size": null, "unit": "B", "value": 15805127360 }, "mount_options": [], "mountpoint": "/", "obj_id": "3e75d045-21a4-429d-897e-8ec19a006e8b", "start": { "sector_size": { "sector_size": null, "total_size": null, "unit": "B", "value": 512 }, "total_size": { "sector_size": null, "total_size": null, "unit": "B", "value": 16106127360 }, "unit": "MB", "value": 301 }, "status": "create", "type": "primary" }

示例三：BTRFS 子卷与压缩

BTRFS 本质上更复杂，因此选项也更“重”。下面这个示例同时包含子卷（subvolumes）与压缩（文档原文示例）：

{ "btrfs": [ { "mountpoint": "/", "name": "@" }, { "mountpoint": "/home", "name": "@home" }, { "mountpoint": "/var/log", "name": "@log" }, { "mountpoint": "/var/cache/pacman/pkg", "name": "@pkg" } ], "dev_path": null, "flags": [], "fs_type": "btrfs", "mount_options": [ "compress=zstd" ], "mountpoint": null, "obj_id": "d712357f-97cc-40f8-a095-24ff244d4539", "size": { "sector_size": { "unit": "B", "value": 512 }, "unit": "B", "value": 15568207872 }, "start": { "sector_size": { "unit": "B", "value": 512 }, "unit": "MiB", "value": 513 }, "status": "create", "type": "primary" }

BTRFS 示例中有两条约定值得注意：

1. "mountpoint": null表示分区本身不挂载，真正的挂载点写在btrfs数组里的各个子卷上。源码中 SubvolumeModification 逐条解析这些{name, mountpoint}对象；当存在名为@且挂载点为/的“默认根子卷”时，has_default_btrfs_vols() 还会自动触发对可选btrfs_options（快照配置，如 Snapper/Timeshift）的解析。
2. 压缩通过mount_options表达，compress=zstd与 BtrfsMountOption 中枚举的挂载选项一致。

对于上述两种之外的文件系统，文档建议的最稳妥做法是：直接运行archinstall交互式安装、为目标文件系统生成一份期望配置，再把相关片段拷贝进自己的永久配置。

需要提醒的是（源自源码的核对结果）：当前序列化结构 _PartitionModificationSerialization 中分区长度对应的键名是size，解析入口也按partition['size']取值（见 parse_arg 第 175 行），而文档 FAT32/EXT4 示例里仍保留了旧的length写法，且examples/config-sample.json与 BTRFS 示例均已使用size。因此手写配置时请以size为准，并与 examples/config-sample.json 中的字段结构对齐。另外文档强调：示例中的单位与位置高度依赖具体用户环境，不可照抄数值。

从配置到磁盘：manual_partitioning 的执行链路

把三种模式放到一起，配置在源码中的完整旅程大致是：

1. --conf your.json由 archinstall/lib/args.py 中的配置处理器读取，顶层键按 config_options.csv 解析；
2. disk_config交给DiskLayoutConfiguration.parse_arg()构造出DeviceModification+PartitionModification对象树，并在构造时完成前文所述的起点/重叠/对齐/GPT 校验；
3. pre_mounted_config走detect_pre_mounted_mods()做挂载点翻译；default_layout走get_default_partition_layout()自动生成；manual_partitioning则以配置为准执行 parted 操作；
4. 可选的disk_encryption、lvm_config、btrfs_options在 parse_arg 末尾 依次解析，其中加密通过obj_id关联具体分区。

小结

• pre_mounted_config：零分区操作，只做挂载点翻译，适合已有布局或 RAID 等复杂环境的“接管式”安装；
• default_layout：按所选文件系统自动生成合理布局，代价是擦除数据，适合快速部署；
• manual_partitioning：最灵活也最严格，分区必须满足 1 MiB 起点、无重叠、1 MiB 对齐、GPT 保留区等校验，BTRFS 场景下挂载点下沉到子卷；
• 编写配置时优先参考 examples/config-sample.json 与 examples/auto_discovery_mounted.py，并以 archinstall/lib/models/device.py 中的序列化结构为字段权威依据。

• 运维
• CLI