如何快速上手 nixos-facter:3 步生成第一份 NixOS 硬件报告(附全部命令详解)

原创2026-10-31 09:01:451,677 阅读

如何快速上手 nixos-facter:3 步生成第一份 NixOS 硬件报告(附全部命令详解)

nixos-facter 是一个面向 NixOS 的声明式硬件信息扫描工具,只需一条命令即可扫描整台机器的 CPU、内存、显卡、磁盘、USB 设备等信息,并生成一份机器可读的 JSON 硬件报告。它可以替代传统的 nixos-generate-config 引导方式,把硬件决策交给 NixOS 模块自动完成,是新手配置 NixOS 时的得力助手。

nixos-facter NixOS 硬件报告生成器

为什么需要 nixos-facter?

在 NixOS 上安装系统时,你常常需要手动描述硬件:网卡用什么驱动、显卡走哪个后端、USB 设备如何接入……这些配置既繁琐又容易出错。

nixos-facter 的思路很直接:

  1. 先在目标机器上扫描硬件,输出一份详细的 JSON 报告;
  2. 把报告交给 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 语言编写,核心目录结构如下:

如果你打算参与开发,可以阅读 docs/content/contributing/code.md 了解 Go 开发环境(devshell)与代码检查流程。

总结:3 步回顾

  1. 装好 Nix —— 目标机器上安装 Nix 包管理器;
  2. 一条命令生成报告 —— sudo nix run nixpkgs#nixos-facter -- -o facter.json;
  3. 接入配置 —— 在 NixOS 配置中设置 hardware.facter.reportPath = ./facter.json; 并重建系统。

至此,你的 NixOS 硬件配置就从"手动摸索"升级为"扫描报告 + 模块自动决策"的声明式工作流。掌握 --swap、--ephemeral、--hardware 等参数后,你还可以按需定制报告内容,让它更贴合你的部署场景。🎉

登录后查看全文
nixos-facter