如何快速上手 nixos-facter:3 步生成第一份 NixOS 硬件报告(附全部命令详解)
如何快速上手 nixos-facter:3 步生成第一份 NixOS 硬件报告(附全部命令详解)
nixos-facter 是一个面向 NixOS 的声明式硬件信息扫描工具,只需一条命令即可扫描整台机器的 CPU、内存、显卡、磁盘、USB 设备等信息,并生成一份机器可读的 JSON 硬件报告。它可以替代传统的 nixos-generate-config 引导方式,把硬件决策交给 NixOS 模块自动完成,是新手配置 NixOS 时的得力助手。
为什么需要 nixos-facter?
在 NixOS 上安装系统时,你常常需要手动描述硬件:网卡用什么驱动、显卡走哪个后端、USB 设备如何接入……这些配置既繁琐又容易出错。
nixos-facter 的思路很直接:
- 先在目标机器上扫描硬件,输出一份详细的 JSON 报告;
- 把报告交给 NixOS 模块,模块根据报告内容自动做出决策,例如自动配置网络控制器、图形显卡、USB 设备等。
正如 README.md 中所述,这个仓库包含生成报告的二进制程序,而消费报告的 NixOS 模块已经包含在 nixpkgs 中,开箱即用。
准备工作:安装 Nix
生成报告前,目标机器上必须先安装 Nix 包管理器。如果你已经在使用 NixOS 或安装了 Nix,这一步直接跳过。
💡 提示:nixos-facter 需要以 root 权限 运行,因为扫描硬件信息需要读取受保护的系统接口。
第 1 步:生成你的第一份 NixOS 硬件报告
使用 nixpkgs 中的稳定版本,一条命令即可生成报告:
sudo nix run nixpkgs#nixos-facter -- -o facter.json
如果你想体验最新的开发版本,可以通过 flake 方式运行(完整命令见 docs/content/getting-started/generate-report.md):
sudo nix run \
--option experimental-features "nix-command flakes" \
--option extra-substituters https://numtide.cachix.org \
--option extra-trusted-public-keys numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE= \
github:nix-community/nixos-facter -- -o facter.json
命令执行完毕后,当前目录下就会出现 facter.json 文件——这就是你的硬件报告。
第 2 步:读懂报告内容
打开 facter.json,你会看到这样一份结构清晰的 JSON(节选自官方文档示例):
{
"version": 2,
"system": "x86_64-linux",
"virtualisation": "none",
"hardware": {
"bios": { ... },
"cpu": [ ... ],
"disk": [ ... ],
"graphics_card": [ ... ],
"network_controller": [ ... ],
"sound": [ ... ]
},
"smbios": {
"bios": { ... },
"board": { ... },
"chassis": { ... },
"processor": [ ... ]
}
}
各字段的含义:
| 字段 | 含义 |
|---|---|
version |
报告格式版本号,用于跟踪重大变更 |
system |
目标机器架构,如 x86_64-linux、aarch64-linux |
virtualisation |
是否运行在虚拟化/容器环境中,以及类型(kvm、qemu、none 等) |
uefi |
UEFI 固件支持信息(是否支持、32 位还是 64 位平台) |
hardware |
检测到的各类硬件:CPU、内存、磁盘、显卡、网卡、USB 控制器等 |
smbios |
系统管理 BIOS 信息:主板、机箱、内存插槽、处理器等 |
swap |
(可选)swap 分区或交换文件的详细信息 |
报告的结构定义在 pkg/facter/facter.go,想深入了解每个字段的细节可以查阅该文件。
第 3 步:把报告接入 NixOS 配置
生成报告后,只需在 NixOS 配置文件中添加一行,让模块消费它:
{
hardware.facter.reportPath = ./facter.json;
}
完成后执行 sudo nixos-rebuild switch(或 boot),NixOS 模块就会根据报告自动完成硬件配置。更多选项细节可参考 nixpkgs 的官方选项文档(在 NixOS 文档站搜索 facter 即可找到)。
全部命令与参数详解
nixos-facter 支持的全部命令行参数都定义在 cmd/root.go 中,下面逐一说明。
常用参数一览
| 参数 | 说明 | 示例 |
|---|---|---|
-o, --output <文件> |
将报告写入指定文件;省略时直接打印到终端 | -o facter.json |
--swap |
额外捕获 swap 条目 | --swap |
--ephemeral |
捕获所有临时属性(swap、文件系统等) | --ephemeral |
--version |
打印版本号后退出 | --version |
--log-level <级别> |
日志级别:error、warn、info、debug,默认 info |
--log-level debug |
--hardware <列表> |
指定要探测的硬件项(逗号分隔) | --hardware cpu,memory |
逐个详解
-o / --output:最核心的参数。指定后报告会以 0600 权限(仅 root 可读写)写入该文件,非常适合把报告纳入版本管理;不指定则输出到标准输出,方便配合 jq 等工具即时查看。相关实现见 cmd/root.go。
--swap:只额外收集 swap 信息。如果你需要为 NixOS 自动配置交换分区,加上它即可。
--ephemeral:收集全部"临时性"属性,例如 swap、文件系统挂载等。这些信息在两次启动间可能变化,默认不收集,保持报告稳定。
--hardware:默认会探测 memory、pci、net、serial、cpu、bios、monitor、scsi、usb、prom、sbus、sys、sysfs、udev、block、wlan 这些硬件类别(默认值定义见 cmd/root.go)。如果只想扫描部分硬件以加快速度,可以用该参数显式指定,如 --hardware cpu,memory。
--log-level:排查问题时推荐用 --log-level debug,可以看到扫描过程中每个探测项的调试日志。
常见问题速查
| 现象 | 原因与解决 |
|---|---|
提示 you must run this program as root |
未用 root 运行,命令前加 sudo(检查逻辑见 cmd/root.go) |
提示 udev version xxx is too old |
系统 udev 版本低于 252,升级系统后重试(检查逻辑见 cmd/root.go) |
| 报告缺少某些硬件 | 用 --hardware 显式加入对应硬件项,或检查该设备是否被系统识别 |
项目结构与延伸阅读
这个仓库采用 Go 语言编写,核心目录结构如下:
- cmd/root.go —— 命令行入口,参数解析与运行流程
- pkg/facter/ —— 扫描器与报告结构定义(
facter.go、hardware.go、smbios.go) - pkg/hwinfo/ —— 基于 hwinfo 的硬件详情解析(CPU、PCI、USB、显示器等)
- pkg/udev/、pkg/virt/、pkg/ephem/ —— udev 信息、虚拟化检测、swap 等临时信息
- docs/content/getting-started/generate-report.md —— 官方"生成报告"教程
- flake.nix —— flake 定义,声明了
x86_64-linux、aarch64-linux、riscv64-linux等构建目标 - nix/packages/nixos-facter/tests/default.nix —— 集成测试,在虚拟磁盘环境中验证报告内容
如果你打算参与开发,可以阅读 docs/content/contributing/code.md 了解 Go 开发环境(devshell)与代码检查流程。
总结:3 步回顾
- 装好 Nix —— 目标机器上安装 Nix 包管理器;
- 一条命令生成报告 ——
sudo nix run nixpkgs#nixos-facter -- -o facter.json; - 接入配置 —— 在 NixOS 配置中设置
hardware.facter.reportPath = ./facter.json;并重建系统。
至此,你的 NixOS 硬件配置就从"手动摸索"升级为"扫描报告 + 模块自动决策"的声明式工作流。掌握 --swap、--ephemeral、--hardware 等参数后,你还可以按需定制报告内容,让它更贴合你的部署场景。🎉