Den主机与用户声明完全指南:den.hosts与den.homes一次讲透

原创2026-11-08 10:47:441,925 阅读

Den主机与用户声明完全指南:den.hosts与den.homes一次讲透

Den 是一款面向 Nix 生态的 aspect-oriented(面向切面)配置框架,其中 den.hosts 与 den.homes 是两个最核心的入口:前者用来声明你的主机与用户,后者用于创建独立的 home-manager 配置。本指南带你从零理解这两个选项的含义、字段与常见写法,一次讲透主机与用户声明的全部细节。

Den主机与用户声明示意图:戴安全帽的吉祥物代表 Den 声明式配置工具

🧭 先搞懂概念:Entity 是什么

在 Den 的术语体系里,主机、用户、家庭配置都属于 Entity(实体)。声明实体是"告诉 Den 世界上存在谁",而真正配置它们的则是 Aspect(切面):

概念 声明位置 生成的 flake 输出
主机(Host) den.hosts.<system>.<name> nixosConfigurations 或 darwinConfigurations
用户(User) den.hosts.<system>.<name>.users.<user> 注入主机配置内的 home 管理 class
独立家庭(Home) den.homes.<system>.<user> homeConfigurations

💡 核心思想:Feature-first, not host-first。Den 反转了"以主机为中心堆模块"的传统模式——特性(aspect)是主角,主机只是选择自己需要哪些特性。

⚡ 快速上手:一行声明主机与用户

以仓库自带模板 templates/default/modules/hosts.nix 为例,声明"igloo 主机上的 tux 用户"只需要一行:

{
  # tux user at igloo host.
  den.hosts.x86_64-linux.igloo.users.tux = { };
}

就这么简单。系统架构 x86_64-linux、主机名 igloo 都写在 attrset 的键路径里,class(nixos / darwin)会根据 system 自动推断——darwin 结尾自动识别为 macOS。

对应的主机切面与用户切面可以分别写在任意文件中,例如:

🖥️ 主机声明:den.hosts 字段详解

den.hosts 的键格式为 <system>.<name>,每个主机条目会按其 class 自动生成到 flake.nixosConfigurations 或 flake.darwinConfigurations。类型定义见 nix/lib/entities/host.nix。

主机常用选项一览

选项 默认值 说明
name attrset 键名 配置名称
hostName name 网络主机名
system 父级键 x86_64-linux、aarch64-darwin 等
class "nixos" 或 "darwin" 操作系统 class,按 system 自动推断
aspect name 主切面,默认取 den.aspects.<name>
instantiate 按 class 决定 构建函数,如 inputs.nixpkgs.lib.nixosSystem
intoAttr 按 class 决定 flake 输出路径,如 [ "nixosConfigurations" name ]
users {} 该主机下的用户声明
* 自由属性 任意自定义属性(见下文 Freeform)

📌 提示:当使用自定义输入名(如 nixos-unstable)或需要 specialArgs 时,可以显式覆盖 instantiate。

👤 用户声明:den.hosts.*.users 怎么用

用户声明嵌套在主机之下,官方文档为 docs/src/content/docs/guides/declare-hosts.mdx:

den.hosts.x86_64-linux.laptop = {
  users.alice = { };
  users.bob.classes = [ "homeManager" "hjem" ];
};

用户条目的关键字段:

选项 默认值 说明
name attrset 键名 用户配置名
userName name 系统账户名
classes [ "user" ] 该用户参与哪些 home 管理 class
aspect 按主机限定查找 优先找 den.aspects.<name>@<host>,再找 den.aspects.<name>

两个实用要点:

  1. classes 决定用户走哪条 pipeline:默认的 user class 只做基础声明;加上 homeManager、hjem、maid 等,用户环境才会交给对应的 home 管理框架(batteries 见 modules/aspects/batteries/hjem.nix)。
  2. 同一用户名可以存在于多台主机,且切面查找会优先带主机限定的版本(alice@laptop),无需在切面里写 if host.name == ... 分支。

🏠 独立家庭:没有 root 权限时用 den.homes

对于没有系统管理权限的机器、或者纯 home-manager 场景,Den 提供了 den.homes:

{
  den.homes.x86_64-linux.alice = { };
  den.homes.aarch64-darwin.alice = { };
}

每条独立家庭都会生成 flake.homeConfigurations.<name>。其字段默认值由 nix/lib/entities/home.nix 定义:

选项 默认值 说明
userName 键名 用户账户名
system 父级键 平台 system
class "homeManager" home 管理 class
aspect den.aspects.<name> 主切面
pkgs inputs.nixpkgs.legacyPackages.<system> nixpkgs 实例
instantiate homeManagerConfiguration 构建函数
intoAttr [ "homeConfigurations" name ] flake 输出路径

🎯 进阶技巧:独立家庭还支持 user@host 命名(如 den.homes.x86_64-linux."tux@igloo"),即使该主机未在 den.hosts 中声明,Den 也会合成一个最小主机上下文,让以 host.name 匹配的路由与策略仍然生效。

⚙️ Schema 基础模块:一次配置、全局生效

den.schema.host / den.schema.user / den.schema.home 是实体类型的"元配置层",可以为所有同类型实体统一加选项(机制见 modules/options.nix):

{
  # 为所有主机开启 home-manager
  den.schema.host.home-manager.enable = true;

  # 为所有用户新增带默认值的选项
  den.schema.user = { user, lib, ... }: {
    options.groupName = lib.mkOption { default = user.userName; };
  };

  # 应用于每台主机、每个用户、每个家庭
  den.schema.conf = {
    options.copyright = lib.mkOption { default = "Copy-Left"; };
  };
}

这相当于 flake-parts 用户在 flake 层使用 options 的元数据等价物,之后切面中读取 host.groupName 即可。

🔧 Freeform 属性:在主机上挂任意数据

主机与用户类型基于 freeformType,可以挂任意自定义属性,并在切面中读取:

den.hosts.x86_64-linux.laptop = {
  users.alice = { };
  gpu = "nvidia";  # 自定义属性,切面内可通过 host.gpu 访问
};
den.aspects.laptop.includes = [
  ({ host, ... }: lib.optionalAttrs (host ? gpu) {
    nixos.hardware.nvidia.enable = true;
  })
];

这正是 Den "上下文即条件"哲学的体现:切面函数的入参形状本身就是条件,无需 mkIf 或 enable 开关。

✅ 常见问题速查

问题 解答
声明了主机但没有 flake 输出? 检查 system 键拼写,输出路径由 intoAttr 决定(默认按 class 路由)
用户没有生成 home 配置? 确认 users.<name>.classes 包含 homeManager / hjem / maid
macOS 主机报缺输入? aarch64-darwin 需要 flake 中提供 inputs.darwin(nix-darwin)
只想管用户环境不想管系统? 直接用 den.homes,无需声明主机

📚 延伸阅读

一句话总结:den.hosts 负责"声明谁在哪里",den.homes 负责"无 root 也能管环境";声明只需一行,剩下的交给 aspects 与 schema。掌握这两者,你就掌握了 Den 的主机与用户声明全貌。

登录后查看全文
den