Den主机与用户声明完全指南:den.hosts与den.homes一次讲透
Den主机与用户声明完全指南:den.hosts与den.homes一次讲透
Den 是一款面向 Nix 生态的 aspect-oriented(面向切面)配置框架,其中 den.hosts 与 den.homes 是两个最核心的入口:前者用来声明你的主机与用户,后者用于创建独立的 home-manager 配置。本指南带你从零理解这两个选项的含义、字段与常见写法,一次讲透主机与用户声明的全部细节。
🧭 先搞懂概念: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。
对应的主机切面与用户切面可以分别写在任意文件中,例如:
- 主机切面:templates/default/modules/igloo.nix 中定义
den.aspects.igloo - 用户切面:templates/default/modules/tux.nix 中定义
den.aspects.tux
🖥️ 主机声明: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> |
两个实用要点:
classes决定用户走哪条 pipeline:默认的userclass 只做基础声明;加上homeManager、hjem、maid等,用户环境才会交给对应的 home 管理框架(batteries 见 modules/aspects/batteries/hjem.nix)。- 同一用户名可以存在于多台主机,且切面查找会优先带主机限定的版本(
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,无需声明主机 |
📚 延伸阅读
- 官方文档:docs/src/content/docs/guides/declare-hosts.mdx
- 主机/用户类型实现:nix/lib/entities/host.nix
- 独立家庭类型实现:nix/lib/entities/home.nix
- 完整模板参考:templates/default/
一句话总结:den.hosts 负责"声明谁在哪里",den.homes 负责"无 root 也能管环境";声明只需一行,剩下的交给 aspects 与 schema。掌握这两者,你就掌握了 Den 的主机与用户声明全貌。
