archinstall 官方文档总览：从引导安装器到 Python 库与插件体系

• 运维
• CLI

本篇技术文章以 archinstall 项目的 Sphinx 文档入口 docs/index.rst 为骨架，梳理该项目的定位、核心特性（顺序执行、日志透明、TUI 无障碍支持）与文档站的四大板块结构。读完后，你将能够：快速理解 archinstall 作为“可安装 Arch Linux 的 Python 库”的设计意图，掌握引导安装器（guided）的运行方式与--config/--creds配置机制，知道如何以库/模块/插件方式集成 archinstall，并能定位日志与文档站构建方法等工程细节。

1. 项目定位：archinstall 是一个“安装库”，而不是单纯的 CLI 工具

文档首页 docs/index.rst 对项目的定位非常明确：

archinstallis a library which can be used to install Arch Linux. The library comes packaged with different pre-configured installers, such as the default guided installer.

即 archinstall 的核心身份是一个可用于安装 Arch Linux 的 Python 库，随库打包的是一组预配置的安装脚本（installer），其中最常用的是默认的guided引导安装器。这一“库 + 预置脚本”的双层结构贯穿整个仓库：

• 库的入口与 CLI 实现在 archinstall/main.py 和 archinstall/main.py，支持python -m archinstall的模块模式；
• 预置安装脚本集中在 archinstall/scripts/ 目录，包含guided.py（引导安装）、minimal.py（最小化安装）、only_hd.py（仅硬盘安装）三个脚本，文档中提到的archinstall --script <script>列表命令就是枚举这个目录；
• 安装主流程的Installer类被文档明确定义为“访问一个安装实例的主类”，API 参考页 docs/archinstall/Installer.rst 直接通过autofunction渲染archinstall.Installer的签名，其源码位于 archinstall/lib/installer.py。

从源码结构看，archinstall/lib/下的模块划分（disk/、profile/、network/、packages/、pacman/、mirror/、bootloader/、user/等）与引导安装器的各个菜单一一对应，这与文档首页“库先行、安装器为包装”的表述一致。

2. 文档首页列出的三大核心特性

docs/index.rst 用三条要点概括了 archinstall 的设计特性，下面逐条结合仓库源码展开。

2.1 Context friendly：顺序执行 + 上下文包装器

文档原文指出：库总是按顺序执行调用，确保安装步骤不重叠、不以错误顺序执行；同时使用“上下文包装器”（context wrappers）保证清理与收尾任务（如mkinitcpio）在需要时被调用。

这一特性对应源码中的install上下文管理：主类Installer实现了__enter__/__exit__，在安装流程进入时保存状态、退出时执行清理与收尾动作（例如生成 initramfs 所需的mkinitcpio调用）。也就是说，文档宣称的“context wrappers”并非营销话术，而是Installer类以 Python 上下文管理器形式落地：以with archinstall.Installer(...)方式组织安装生命周期，保证任何一步抛出异常时收尾逻辑依然被触发。这也是将 archinstall 用作库时值得遵循的调用方式。

2.2 Full transparency：日志落在 /var/log/archinstall

文档声明日志与洞察信息位于/var/log/archinstall，在 live ISO 和已安装系统（部分）上都能找到。这一点可以在 archinstall/lib/log.py 中得到直接印证：

• Logger类的默认路径就是Path('/var/log/archinstall')，日志文件为install.log（self._path / 'install.log'）；
• 每次log()写入形如[时间戳] - 级别 - 内容的文本行，并附带 ANSI 色彩输出（当终端支持时）；
• _check_permissions在目标目录不可写时会回退到当前目录写日志并给出警告，这解释了文档中“partially on the installed system”的谨慎措辞——日志落盘位置依赖运行环境的权限。

排障时真正有用的不止install.log。根据 docs/help/report_bug.rst，/var/log/archinstall/下还有这些辅助文件：

文档特别强调：只有install.log被承诺保证不含敏感信息，其余文件（尤其是user_credentials.json）分享时必须极度谨慎；并提供archinstall share-log快速上传install.log并打印可分享 URL（仓库中有对应的测试 tests/test_share_log.py 覆盖该行为）。

2.3 Accessibility friendly：TUI + espeakup

文档首页的第三条特性是：archinstall 使用 TUI（文本用户界面）实现，因此能与espeakup等无障碍工具协同工作。仓库中 TUI 的实现位于 archinstall/tui/ 目录（components.py、menu_item.py、binding_descriptions.py等），espeakup正是 Arch 官方 ISO 中为屏幕阅读器服务的 TTS 工具，TUI 的按键式导航模型与其天然兼容。这一点属于“从源码结构看”可以确认的对应关系：交互层没有依赖图形控件，全部基于文本终端事件流。

3. 文档站四大板块（toctree）逐一解读

docs/index.rst 用四个toctree组织了整份文档，分别对应“运行 archinstall”、“获取帮助”、“把 archinstall 当库用”和“API 参考”。以下按该结构展开每个板块的实际内容。

3.1 Running Archinstall：引导安装（installing/guided）

该板块唯一条目是 docs/installing/guided.rst，是整个文档中最具实战价值的一页，要点如下：

启动方式。在最新 Arch Linux ISO 上直接运行：

archinstall

由于引导安装器是默认脚本，这等价于archinstall guided。文档同时提示：其他预置脚本可用archinstall --script <script>（不带.py）调用，archinstall --script list可列出全部脚本（对应 archinstall/scripts/ 目录）；并明确警告安装器不会在安装开始前配置 Wi-Fi，需要读者自行了解 Arch 的网络配置。

预配置回答：--config与--config-url。引导安装支持用 JSON 配置文件预填所有菜单答案，两个参数均为可选：

• --config <file.json>：本地 JSON，包含引导安装器的整体配置与菜单答案；
• --config-url <url>：远端 JSON，内容结构相同。

archinstall --config config.json archinstall --config-url https://domain.lan/config.json

文档给出了获取最新选项的稳妥方法：archinstall --dry-run以安全模式模拟运行，不会对系统做持久化操作，并把配置保存到磁盘。完整配置字段表由 CSV 文件 docs/cli_parameters/config/config_options.csv 驱动生成（在 docs/installing/guided.rst 中以csv-table引入），仓库内还附带了示例文件 examples/config-sample.json 与 tests/data/test_config.json 可作对照。一个典型配置（摘自文档示例）包含以下关键字段：

{ "bootloader": "Systemd-boot", "bootloader_config": { "bootloader": "Systemd-boot", "uki": false, "removable": false }, "disk_config": { "config_type": "manual_partitioning", "device_modifications": [ { "device": "/dev/sda", "partitions": [ { "fs_type": "fat32", "mountpoint": "/boot", "flags": ["boot"], "status": "create", "type": "primary" }, { "fs_type": "ext4", "mountpoint": "/", "status": "create", "type": "primary" } ], "wipe": false } ] }, "disk_encryption": { "encryption_type": "luks", "partitions": ["<分区obj_id>"] }, "hostname": "archlinux", "kernels": ["linux"], "locale_config": { "kb_layout": "us", "sys_enc": "UTF-8", "sys_lang": "en_US" }, "ntp": true, "offline": false, "packages": [], "script": "guided", "timezone": "UTC" }

（文档中的示例还包含mirror_config、profile_config、save_config等更多字段。）

文档特别强调两点行为约束：

1. 所有键值必须严格符合 JSON 标准，示例中带有链接的可读形式实际会破坏语法，需自行适配；
2. 若disk_config中没有任何条目，guided 安装将直接使用当前已挂载在/mnt/archinstall下的文件系统，不执行任何磁盘操作——这是把 archinstall 用于“挂载盘安装”场景的关键前提。

敏感凭据：--creds。凭据文件与常规配置分离，把密码等敏感数据从--config中剥离。最小示例是设置 root 密码：

{ "root_enc_password": "SecretSanta2022" }

--creds支持的可选项（见 docs/installing/guided.rst 的 list-table）：

文档给出的规则是：只有当设置了root_enc_password时users才是可选的；否则users被强制要求，且至少需要有 1 个拥有 sudo 权限的用户。

3.2 Getting help：已知问题、报告 Bug、社区

该板块收录三个页面，内容在各自文档中已经相当具体。

Known Issues（docs/help/known_issues.rst）列出了若干超出 archinstall 自身范围、但高频出现的问题及排查手段：

• 等待时间同步：根因通常是网络拓扑导致timedatectl show无法对默认服务器完成同步；重启systemd-timesyncd.service可能有效，更多时候需要按网络设计配置/etc/systemd/timesyncd.conf。若确认本机时间正确，可用archinstall --skip-ntp跳过时间同步；
• archlinux-keyring-wkd-sync 挂起：WKD 同步服务/定时器可能因无法连通密钥服务器而“无限期”挂起；可通过手动运行/usr/bin/archlinux-keyring-wkd-sync验证，并用systemctl show检查 timer 的ActiveEnterTimestamp与 service 的SubState。修复流程为killall gpg-agent→ 清理/etc/pacman.d/gnupg→pacman-key --init && pacman-key --populate→pacman -Sy archlinux-keyring→ 重启同步 timer。确认 ISO 最新且密钥有效时可用archinstall --skip-wkd跳过（代价是可能出现 PGP 签名 “unknown trust” 报错）；
• Nvidia 专有驱动缺包：某些内核选择/硬件组合需要额外包，常见 workaround 是安装linux-headers与nvidia-dkms；
• ARM / 32 位等架构报错：Arch Linux 官方仅支持x86_64，其他架构理论上可用但非重点；
• Keyring 过期：通常是 ISO 过旧导致archlinux-keyring过期，且网络未就绪时同步服务会失败，使 archinstall 基于旧 keyring 运行；文档建议依靠上游同步服务而非在 archinstall 内做规避。值得注意的是该问题也可能出现在刚发布几天的新 ISO 上——某些密钥可能在 keyring 烧录进 ISO 后随即过期；
• AUR 包不支持：AUR 不受支持，因此诸如 ZFS 文件系统之类的功能无法通过 AUR 包解决；但借助插件机制（见 3.3 节）可以以“不受支持的用法”引入社区 AUR 插件，官方文档给出了archinstall --plugin <url>的两个社区参考实现命令示例，并明确警告这意味着允许在安装过程中不受支持地使用 AUR。

Report Issues & Bugs（docs/help/report_bug.rst）：问题与 Bug 应在项目的 issues 渠道报告，一般性问题、增强与安全漏洞也可以一并提交；简单问题可去 Discord 帮助频道。提交求助时应附带/var/log/archinstall/install.log（live ISO 与已装入基础包的文件系统中都存在）；archinstall share-log可一键上传。

Discord（docs/help/discord.rst）：社区 Discord 服务器有贡献者常驻，#Release Party频道发布新版本通知，可用@Party Animals角色订阅；贡献者可通过!verify验证流程激活@Contributors角色。

3.3 Archinstall as a library：库安装、模块模式、插件

这是文档首页 toctree 中“Archinstall as a library”板块，由 docs/installing/python.rst、docs/examples/python.rst 和 docs/archinstall/plugins.rst 三页组成。

三种安装方式（docs/installing/python.rst）：

# 方式一：pacman（官方仓库，同时装入脚本与库） pacman -S archinstall # 只需库、不要 helper 可执行文件时用 python-archinstall 包 # 方式二：PyPI pip install archinstall # 方式三：源码安装（clone 仓库后，把目录移入项目直接 import archinstall； # 或用 PyPA build/installer 装入 Python 模块路径） git clone <仓库地址> cd archinstall python -m build . python -m installer dist/*.whl

文档同时声明：如果你使用的是官方 Arch Linux ISO，这些步骤都不需要——ISO 已内置 archinstall。仓库根目录的 pyproject.toml 定义了包名、入口点与构建后端，是上述安装方式得以成立的工程基础。

模块模式（module mode）（docs/examples/python.rst）：archinstall 支持python -m archinstall --script <name>调用，但该模式只能执行scripts文件夹下的脚本，因此文档要求把自定义安装脚本放进仓库的archinstall/scripts/目录后再构建安装。文档给出了一个可验证的最小例子——新建scripts/test_installer.py：

from archinstall.lib.disk.device_handler import device_handler from pprint import pprint pprint(device_handler.devices)

安装后运行python -m archinstall test_installer，若打印出BDevice设备对象列表（含model、path、分区信息partition_infos等字段），说明脚本位置正确、库工作正常。文档还提醒：包括该示例在内的多数调用都需要 root 权限。该示例中的device_handler确实存在于 archinstall/lib/disk/device_handler.py，磁盘/分区能力由 archinstall/lib/disk/ 目录承载。

插件机制（docs/archinstall/plugins.rst）：archinstall 支持两种插件加载方式：

1. --plugin参数：运行时通过本地或远端路径加载特定插件。优点是插件路径会被存入--config状态，重跑安装时自动加载；缺点是需要事先知道并写好路径；
2. Python 插件发现（entry points）：按archinstall.plugin分类的 entry point 自动发现，可一次加载多个插件，但插件必须预先安装到运行 archinstall 的系统上，主要面向自制 ISO 的构建者。

插件的扩展点是“查询驱动”的：宿主代码在特定调用点遍历插件、查找约定的钩子函数。文档给出的例子是——若插件定义了：

def on_pacstrap(*packages): ...

那么archinstall.Pacman().strap([...])会硬编码地遍历插件查找on_pacstrap，若存在则调用它，并用插件的返回值替换初始包列表。文档坦承这部分文档目前偏少，建议直接在源码中搜索plugin.on_前缀来确定全部受支持的钩子。仓库中插件加载逻辑位于 archinstall/lib/plugins.py，可在其中核对钩子调用与 entry point 发现的具体实现。

3.4 API Reference：Installer 类

最后一个板块只有一页 docs/archinstall/Installer.rst，内容是把archinstall.Installer作为“访问安装实例的主类”并声明：与安装系统内部相关的一切都在这个类里。页面通过 Sphinxautodoc的autofunction指令直接渲染该类的签名与 docstring，配合 docs/conf.py 中的扩展配置（sphinx.ext.autodoc、sphinx.ext.inheritance_diagram等）与自定义的process_docstring后处理（将 docstring 中 8 空格缩进替换为 4 空格以适配 reST），生成完整的类参考。

4. 文档站本身如何构建

了解文档入口之后，文档站的构建方式也值得开发者掌握（docs/README.md）：

pip install -U sphinx sphinx-rtd-theme cd docs make html # 产物在 _build/html/index.html

关键配置都在 docs/conf.py：项目名为python-archinstall，主题sphinx_rtd_theme，master_doc = 'index'（即本文剖析的 docs/index.rst），exclude_patterns排除_build等；另有一个自定义 Sphinx 扩展挂钩autodoc-process-docstring用于修正 docstring 缩进。静态资源（logo、样式）位于 docs/_static/，自定义页脚/导航模板位于 docs/_templates/layout.html。

5. 小结：沿着 index.rst 的路径图使用文档

docs/index.rst 虽然篇幅不长，却是 archinstall 文档的信息枢纽：它用三句话定义了项目“库 + 预置安装器”的身份，用三条特性（顺序执行与上下文收尾、/var/log/archinstall全透明日志、TUI 无障碍）概括了实现取向，再用四个 toctree 把读者导向四条路径——

1. 跑安装：读 docs/installing/guided.rst，掌握archinstall/--config/--config-url/--creds/--dry-run全套用法；
2. 排障求助：读 docs/help/ 三页，熟悉日志文件清单、share-log与各已知问题的标准排查流程；
3. 当库集成：读 docs/installing/python.rst 与 docs/examples/python.rst，掌握 pacman/PyPI/源码三种安装方式与模块模式；
4. 写插件/查 API：读 docs/archinstall/plugins.rst 与 docs/archinstall/Installer.rst，并以 archinstall/lib/ 源码与plugin.on_钩子调用点为最终权威参考。

对 Agent 与自动化场景而言，最值得记住的工程事实是：--dry-run可无副作用导出配置、disk_config为空时直接复用/mnt/archinstall已挂载文件系统、凭据与常规配置分离存放于--creds、以及日志目录/var/log/archinstall下各文件的敏感程度差异（仅install.log保证可公开）。

• 运维
• CLI