企业官网建设流程全解析

NixOS 模块化服务（Modular Services）实战指南：以模块为单位声明可组合、可移植的服务

【免费下载链接】nixpkgsNix Packages collection & NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs

模块化服务（Modular Services）是 NixOS 25.11 引入的服务定义新范式：它把传统上"写在模块里的一组选项"提升为"本身就是模块的服务"，从而让服务具备天然的可组合性、可复用性与跨进程管理器（systemd、launchd、s6 等）的可移植性。本文将以 NixOS 手册中的 Modular Services 章节 为主线，结合 Nixpkgs 仓库中lib/services/、nixos/modules/system/service/的源码实现以及 ghostunnel 等真实模块化服务实例，系统讲解其设计原理、选项体系、编写规范与测试方法。读完本文，你将掌握如何接入system.services.<name>声明服务、如何写出可移植的_class = "service"模块、如何在 systemd 下定制单元行为，以及如何为模块化服务编写 VM 测试并通过passthru.services将其随包分发。

传统服务的困境：选项写在模块里，而不是模块本身

在模块化服务出现之前，NixOS 服务的定义方式是：在 NixOS 模块（例如services.nginx、services.postgresql）内部声明一组选项，把进程启动、配置生成、系统集成逻辑统统固化在这组选项里。

这种做法的根本问题是非模块化（non-modular）。服务不是独立、可自由搬移的单元，而是与特定配置管理框架（NixOS）的选项命名空间深度耦合。由此引发一系列问题：

• 可组合性差：很难把某个服务作为构件嵌入到更大的服务或组合体中，服务的"实例"无法用模块系统原生机制去 import 和叠加。
• 复用困难：同一份服务逻辑很难在另一个配置管理框架（如 Home Manager、nix-darwin）中复用，因为它假定自己是运行在 NixOS 的系统命名空间下。
• 不可移植：服务的定义隐含依赖了 systemd 的选项树，而其他进程管理器（launchd 等）无法消费这些定义。

模块化服务的核心思路，就是把这些逻辑重新组织成"模块"本身——一个服务就是一个模块，可以被imports组合、被赋予用户指定的名字、被拆成子服务树。

配置管理框架与服务管理组件

要理解模块化服务的定位，需要先厘清两个层次的概念。

**配置管理框架（configuration management framework）**是evalModules的一个应用场景：把class与specialArgs输入参数设为特定值，从而得到一套带有约束和特殊参数的模块求值体系。NixOS 是一个配置管理框架，Home Manager、nix-darwin 也是。对应源码位于 lib/modules.nix。

**服务管理组件（service management component）**是配置管理框架中负责把 Nix 表达式与底层服务（进程）管理器连接起来的那一组模块选项：

• 对 NixOS 而言，是包装 systemd 的模块（nixos/modules/system/service/systemd/system.nix）；
• 对 nix-darwin 而言，是包装 launchd 的模块；
• 未来也可以是对 s6、runit 等进程管理器的包装。

模块化服务（modular service）正是"插在"这个组件上的模块：它为核心选项集（包括运行哪个程序）定义值。由于它本身是模块，因此可以经由imports与其他模块组合、扩展其功能。

NixOS 的接入点：system.services.<name>

NixOS 为模块化服务提供了两个可插入的位置：

• system.services.<name>——系统级服务；
• 用户级服务的选项（TBD）——尚未落地，仍在设计中。

关键在于：这些选项的类型是attrsOf与submodule的组合。服务名就是attrsOf对应的属性名——你在system.services下写什么属性名，服务就叫什么名字。

该submodule被预加载了两个模块（参见 system.nix 中的portable-lib.configure调用）：

1. 一个通用（可移植）模块——即lib/services/service.nix定义的便携服务基座，它不依赖任何具体进程管理器；
2. 一个 systemd 特定模块——即nixos/modules/system/service/systemd/service.nix，其选项的值或默认值从通用模块的选项值推导而来（例如把process.argv转译为systemd.mainExecStart、把process.reloadSignal转译为ExecReload）。

因此，system.services.<name>的默认值并不是一个完整服务。它要求用户提供值，而通常的做法是导入一个模块。手册给出了最典型的用法（原样继承自 modular-services.md）：

{ system.services.my-service-instance = { imports = [ pkgs.some-application.services.some-service-module ]; foo.settings = { # ... }; }; }

从源码结构看，这一"魔术"分成两半完成（见 system.nix）：

• 前半：system.services选项被声明为types.attrsOf modularServiceConfiguration.serviceSubmodule，把便携服务基座与 systemd 特定模块混入同一个子模块类型；
• 后半：把在隔离环境中定义的 unit（makeUnits "services"/makeUnits "sockets"）、configData文件（makeNixosEtcFiles）以及断言/警告（portable-lib.getAssertions/getWarnings）回流到 NixOS 的systemd.services、systemd.sockets、environment.etc等系统级选项中。

这也是设计取舍的记录：system.services.<name>相比systemServices、services.abstract、services.modular等备选命名更自然，详见 nixos/modules/system/service/README.md 中的设计决策日志（Design decision log）。

可移植服务选项（Portable Service Options）详解

便携服务基座由 lib/services/service.nix 定义，包含以下核心选项。这些选项不依赖 systemd，任何进程管理器实现（launchd、s6）都可以消费它们。

process.argv：启动命令行

process.argv是启动服务进程的命令文件名与参数列表，类型为types.listOf pathOrStr。其中pathOrStr是types.path与types.str的强制转换类型，源码注释明确说明：路径采用插值（"${x}"）而非toString，这样路径会被复制进 store，服务运行机器上依然可以解析；而toString会留下配置求值源树的路径，运行时不存在（见 service.nix）。

process.argv = [ (lib.getExe config.package) "--nobackground" ];

注意事项（见 service.nix）：

• 这是原始命令行，不应包含任何 shell 转义；
• 如需环境变量展开，应使用 shell 脚本或pkgs.execline的importas；
• 当设置了flags时，由flags渲染出的参数会合并进argv，二者共享同一套lib.mkOrder优先级空间。

process.flags与process.flagFormat：声明式参数

process.flags让你用属性集（或列表）声明传给进程的参数：key 是参数名（如"--port"），value 是参数值。每个name = value对经由lib.cli.toCommandLine配合flagFormat渲染（见 service.nix）：

• null：参数被省略（无论flagFormat如何）；
• bool：按flagFormat.explicitBool渲染——false（默认）时true输出裸参数、false被省略；true时true/false都按formatArg显式输出；
• string / path / int：按flagFormat.sep连接到选项名，再经formatArg字符串化。

需要重复传同一参数时，用列表形式，例如[ { "--host" = "a"; } { "--host" = "b"; } ]。源码层面，渲染发生在 service.nix：process.argv由mapDefinitionValue把每个 flag 定义映射为lib.cli.toCommandLine config.process.flagFormat attr后mkMerge而成。

排序语义（重要细节）：argv与flags共享单个lib.mkOrder空间，未加排序属性的 flag 被放到优先级1250（unadornedFlagPriority），介于默认优先级 1000（裸argv定义）与lib.mkAfter（1500）之间，因此普通 flag 会跟在命令名和普通argv参数之后；lib.mkAfter的argv仍然排在 flags 之后，用来表达尾部位置参数；lib.mkOrder作用于 flag 时则原样生效，可用于把子命令插到两组 flags 之间（见 service.nix 与 service.nix）。

process.reloadSignal与process.reloadCommand：热重载

• process.reloadSignal（nullOr str，默认null，如"HUP"）：向服务管理器配置重载信号。
• process.reloadCommand（nullOr str，默认null）：底层服务管理器用于重载的命令。

二者之间存在一条推导与约束规则（见 service.nix）：当设置了reloadSignal时，reloadCommand会以mkDefault优先级推导为"${pkgs.coreutils}/bin/kill -${reloadSignal} $MAINPID"；同时通过assertions检查——只有用户显式设置了reloadCommand（优先级不高于defaultOverridePriority）且reloadSignal非空时才报错，避免两者冲突。

notificationProtocol：就绪通知协议

notificationProtocol是一个子模块（见 service.nix），声明服务与底层服务管理器之间支持的就绪通知协议：

notificationProtocol.systemd = true; # 支持 systemd-notify notificationProtocol.s6 = true; # 支持 s6-notify

在 systemd 集成层，notificationProtocol.systemd会直接影响单元的Type值（notify而非默认的simple），见下文 systemd 特定选项。

configData：免重启更新配置

configData（定义于 lib/services/config-data.nix）为服务提供配置文件，可以在不终止、不重启服务进程的情况下更新——这正是许多服务支持 SIGHUP 热重载或自动感知文件变化的用武之地。每个configData.<name>条目是一个子模块（见 lib/services/config-data-item.nix），属性包括：

示例（摘自 config-data.nix）：

configData = { "server.conf" = { text = '' port = 8080 workers = 4 ''; }; "ssl/cert.pem" = { source = ./cert.pem; }; };

在 NixOS 上，systemd 集成层通过 config-data-path.nix 递归为每个服务（含子服务）计算唯一路径，形如/etc/system-services/webserver/与/etc/system-services/webserver-api/；再经 system.nix 的makeNixosEtcFiles把configData映射为environment.etc条目。configData之所以不叫environment.etc，是为了保持服务管理器无关性——其他管理器可能以不同目录、相对路径的方式暴露配置数据（见 nixos/modules/system/service/README.md）。

services：子服务（归属关系）

便携基座还声明了services选项（attrsOf子模块，类型为submoduleWith，class = "service"），用于在一个服务内部声明子服务。子服务之间、子服务与父服务之间的关系被定义为归属关系（ownership）——它不会自动创建任何其他关系（例如 systemd slice），除非另有选项显式定义并启用（见 service.nix）。这是服务组合的关键机制，下文详述。

meta.maintainers与assertions/warnings

便携基座通过imports预加载了两个通用模块（见 service.nix）：

• lib/modules/generic/meta-maintainers.nix：提供meta.maintainers与meta.teams选项，其类型会把每个定义追溯到具体模块文件（sourceList），并要求值必须来自lib.maintainers/lib.teams；
• lib/modules/generic/assertions.nix：提供assertions与warnings选项，供服务模块表达求值期必须成立的条件与警告信息。

在 NixOS 集成层，portable-lib.getAssertions与getWarnings（定义于 lib/services/lib.nix）会递归遍历服务树，把每个服务（含子服务）里的断言/警告带上in <选项路径>:前缀后提升到系统级，与 NixOS 自身的断言体系合并。

systemd 特定服务选项详解

systemd 集成模块 nixos/modules/system/service/systemd/service.nix 定义了以下选项，它们只在 systemd 环境中存在——这恰恰是便携性的关键（下文 Portability 一节会说明）。

systemd.mainExecStart

主命令行，直接对应 systemd 的ExecStart，默认值是config.systemd.lib.escapeSystemdExecArgs config.process.argv，即把便携的process.argv转义后的结果——转义会禁用 systemd 的%说明符与$变量替换，保证process.argv按字面执行。

需要启用 systemd 的替换特性（如%n、%i、%t等 specifier，或${VAR}环境变量）时，显式设置该选项，例如（见 service.nix）：

systemd.mainExecStart = config.systemd.lib.escapeSystemdExecArgs config.process.argv + " --systemd-unit %n";

systemd.mainExecReload

主重载命令行，对应ExecReload，默认取process.reloadCommand（按原样使用，以保留$MAINPID这类引用）。当process.reloadCommand未设置时该选项为null，此时不会渲染出ExecReload行，服务可以在systemd.service.serviceConfig.ExecReload里自行定义。可参考systemd.mainExecStart的写法追加 systemd specifier 扩展它。

systemd.lib.escapeSystemdExecArgs

导出的转义函数，用于把参数列表安全地拼进Exec*行：用toJSON产生 systemd 接受的引号转义子集，并把%转成%%、$转成$$，从而禁掉 specifier 与变量展开；裸的;也会因 JSON 转义而失去分隔命令的意义（见 service.nix）。

systemd.lib.escapeSystemdExecArgs [ "/bin/echo" "Unit %n" ] # 产出： "/bin/echo" "Unit %%n"

systemd.services与systemd.sockets：单元定义逃生口

这两个选项用于声明 systemd 单元，单元名会被自动加上抽象服务名前缀。注意它们的类型是deferredModuleWith/deferredModule——选项里存放的是延迟（deferred）模块，尚未与系统配置合并，因此无法读取该选项的值；正确的用法是定义一个模块，让它读取合并进系统配置时才可用的模块参数（如config）（见 service.nix）。

同时在systemd.service选项上做了两个别名（service.nix）：

lib.mkAliasOptionModule [ "systemd" "service" ] [ "systemd" "services" "" ] lib.mkAliasOptionModule [ "systemd" "socket" ] [ "systemd" "sockets" "" ]

默认单元模板（见 service.nix）会为每个服务生成：

systemd.services."" = { wantedBy = lib.mkDefault [ "multi-user.target" ]; serviceConfig = { ExecReload = lib.mkIf (config.systemd.mainExecReload != null) config.systemd.mainExecReload; Type = lib.mkDefault (if config.notificationProtocol.systemd then "notify" else "simple"); Restart = lib.mkDefault "always"; RestartSec = lib.mkDefault "5"; ExecStart = [ config.systemd.mainExecStart ]; }; };

也就是说：声明notificationProtocol.systemd = true会让单元变成Type=notify；默认Restart=always、RestartSec=5；ExecReload只有在mainExecReload非空时才出现。这些默认行为都有 nixos/tests/system-services-compliance.nix 中的求值级断言测试（testDefaultType、testNotifyType、testReloadExecReload、testNoReloadExecReloadUnset、testServiceOwnExecReload）做保障。

子服务的 systemd 展开

systemd 集成模块同样把自己的选项递归注入子服务（services选项，class = "service"，见 service.nix）；而 system.nix 的makeUnits会递归遍历整棵服务树，把每个叶子单元以父服务名-子服务名的形式（dash拼接）导出为真正的systemd.services.<name>/systemd.sockets.<name>。

可移植性（Portability）

模块化服务可以写成可移植的：要么完全避开systemd选项树，要么以可选方式定义进程管理器特定配置。手册给出的标准写法（见 modular-services.md）：

{ config, options, lib, ... }: { _class = "service"; config = { process.argv = [ (lib.getExe config.foo.program) ]; } // lib.optionalAttrs (options ? systemd) { # ... systemd-specific definitions ... }; }

这样，该模块可以加载进不使用 systemd 的配置管理器中，systemd相关定义会被静默忽略；其他配置管理器也可以为服务声明自己的选项做定制。这个options ? systemd模式正是nixos/README-modular-services.md审查清单中的硬性要求（Systemd-specific definitions are behindoptionalAttrs (options ? systemd)）。

一个补充：模块化服务模块不应使用pkgs模块参数。基础设施刻意不向服务模块暴露pkgs，派生体与构建函数通过词法闭包提供，使依赖关系显式、避免"这个pkgs是哪个版本"的歧义。服务模块应把包依赖声明为选项（如foo.package = mkOption { type = types.package; }），由调用方提供，或用passthru.services在包内以词法闭包方式提供（详见 nixos/modules/system/service/README.md）。

组合与归属（Composition and Ownership）

与传统服务相比，模块化服务天然更可组合：它们本身是模块，并在导入时获得用户提供的名字。但组合不能止步于此——服务之间需要互相交互，这有两条路径：

1. 用户在 NixOS 配置中把服务链接起来：通过imports引入多个服务模块，在配置里互相传值；
2. 服务作为其他服务的组合体：利用便携基座的services子服务机制，一个服务可以内嵌多个子服务。

这两种方式并不互斥。实际上，良好的开发实践是：先把每个服务写成独立服务，再组合成更高级的组合体；其中每个服务（包括它们的组合）都是一个合法的模块化服务。

从实现看，组合的递归展开发生在三个层面：makeUnits/makeNixosEtcFiles递归遍历服务树（system.nix）、flattenMapServicesConfigToList递归收集断言/警告（lib/services/lib.nix）、config-data-path.nix递归计算唯一配置路径（config-data-path.nix）。每个子服务的单元、配置文件、断言都会被扁平化到系统级，且名字带有唯一的服务前缀，互不冲突。

nixos/tests/modular-service-etc/test.nix是组合的完整演示：webserver服务下挂了一个名为api的子服务，测试断言其生成的单元名为webserver.service与webserver-api.service，配置文件分别位于/etc/system-services/webserver/webroot与/etc/system-services/webserver-api/webroot。

迁移（Migration）

很多服务都可以迁移到模块化服务体系，但即便模块化服务成熟之后，也没有必要迁移全部服务。例如：许多系统级服务是桌面系统的强制组成部分，多实例化它们没有意义（手册以 TODO 注记留待补充单实例服务示例）；把这类服务的逻辑拆分到独立 Nix 文件里，仍可能对"不启用这些服务的配置求值效率"有好处，但这只是次要收益——除非模块化服务将来成为定义服务的标准方式，这种收益才变得显著。

编写与审查一个模块化服务

关于编写与审查的完整贡献者规范见 nixos/README-modular-services.md。其要点如下。

最低标准（Minimum Standard）

• 模块化服务必须附带一个NixOS VM 测试来实际运行验证；
• 模块化服务必须有meta.maintainers模块属性，列出服务维护者（不必与 NixOS 模块的维护者相同；若你不是 NixOS 模块维护者，建议加入其meta.maintainers团队以便参与评审）。

审查清单

贡献者评审模块化服务时逐项检查：

- [ ] 有 NixOS VM 测试 - [ ] 有 `meta.maintainers` 属性 - [ ] systemd 特定定义放在 `optionalAttrs (options ? systemd)` 之后以促进可移植性 - [ ] `_class = "service"` - [ ] 通过 `passthru.services` 提供的模块化服务必须用 `finalAttrs.finalPackage` 覆盖包选项默认值 - [ ] 模块化服务基础设施是否足以支撑该服务？如有未覆盖特性，去对应的 issue 中评论 - [ ] 已加入 `nixos/modules/misc/documentation/modular-services.nix`

最后一项对应 nixos/modules/misc/documentation/modular-services.nix：它用fakeSubmodule为每个已入库的模块化服务渲染文档（目前包括autopush-rs、ghostunnel、git-pages、ktls-utils、php、snid、trailbase等），纳入documentation.nixos.extraModules。

_class = "service"

_class声明确保当模块被意外导入到非模块化服务的配置（如 NixOS 配置）时，模块系统给出清晰报错。提供方式：把它作为模块的第一个属性。

# 非模块依赖（importApply） { writeScript, runtimeShell }: # 服务模块 { lib, config, ... }: { _class = "service"; options = { # ... }; config = { # ... }; }

注意与evalModules的class参数配合：NixOS 的模块类是"nixos"（见 system.nix），服务子模块类是"service"（见 lib/services/lib.nix），类型不符时会在求值期报错。整个便携基座也声明_class = "service"（service.nix）。

覆盖包默认值：finalAttrs.finalPackage

当模块化服务通过passthru.services提供时，必须用finalAttrs.finalPackage覆盖包选项的默认值。原因是：某些包本身就是由 override 定义出来的，如果不这样做，模块化服务会启动错误的包（如果还能构建的话）。若无法做到这一点、或该模块无法用单个包表示，则应考虑只按文件路径直接暴露模块化服务。

ghostunnel的包定义示范了标准做法（见 pkgs/by-name/gh/ghostunnel/package.nix）：

stdenv.mkDerivation (finalAttrs: { pname = "ghostunnel"; # ... passthru.services.default = { imports = [ (lib.modules.importApply ./service.nix { }) ]; ghostunnel.package = finalAttrs.finalPackage; }; })

实战案例：ghostunnel 模块化服务

ghostunnel是一个带双向认证的 TLS 代理。其服务模块 pkgs/by-name/gh/ghostunnel/service.nix 是模块化服务的教科书实现：

• 声明_class = "service"；
• 声明一系列ghostunnel.*选项（package、listen、target、keystore、cert、key、cacert、disableAuthentication、allowAll、allowCN、allowOU、allowDNS、allowURI、extraArguments、unsafeTarget），其中package的defaultText注明"由提供本模块的 ghostunnel 包给出"——即由passthru.services传入的finalAttrs.finalPackage填充；
• 在config中把选项渲染成process.argv命令行，并用assertions强制"至少设置一种访问控制方式"；
• 通过// lib.optionalAttrs (options ? systemd)追加 systemd 专属增强：用systemd.mainExecStart追加带${CREDENTIALS_DIRECTORY}变量替换的凭据参数（这些变量替换在默认转义路径下会被禁用，所以必须显式重写主命令行），并设置systemd.service.serviceConfig的DynamicUser、AmbientCapabilities、LoadCredential、Restart等。

在 NixOS 配置中启用该服务（见 nixos/tests/ghostunnel-modular.nix）：

system.services."ghostunnel-plain-old" = { imports = [ pkgs.ghostunnel.services.default ]; ghostunnel = { listen = "0.0.0.0:443"; cert = "/root/service-cert.pem"; key = "/root/service-key.pem"; disableAuthentication = true; target = "backend:80"; unsafeTarget = true; }; };

同一个模块在同一台机器上被实例化两次（ghostunnel-plain-old与ghostunnel-client-cert），正是"多实例化"能力的直接体现——这在传统单实例services.ghostunnel式设计中难以实现。

测试与验证

NixOS VM 测试

每个模块化服务必须有 VM 测试。最佳实践是保持测试最小且聚焦：启动 VM、启用服务、断言一次基本请求成功。ghostunnel-modular.nix的测试脚本依次验证：后端连通性、忽略证书的 TLS、带 CA 校验的 TLS、客户端证书认证成功、以及无客户端证书时连接必须失败。

nixos/tests/modular-service-etc/test.nix则验证configData的能力：

• 启动主服务webserver.service与子服务webserver-api.service；
• 断言/etc/system-services/下两个服务各自的配置目录与文件存在且内容正确；
• 记录两个服务的 MainPID，切换到specialisation.updated后，断言切换输出中不出现这两个服务、PID 不变——证明配置文件被原地更新而服务进程未被重启；
• 再断言 curl 抓取到的内容已是更新后的版本（"without restarting the service"）。

该测试的配置文件目录还展示了configData与子服务组合的完整结构（webserver+services.api子服务），其模块定义在 nixos/tests/modular-service-etc/python-http-server.nix：python-http-server.directory的默认值直接取config.configData."webroot".path，并通过enable = mkDefault (...)按需启用配置文件。

求值级合规测试

nixos/tests/system-services-compliance.nix 用pkgs.testers.modularServiceCompliance对服务树做求值级断言：默认单元Type=simple、启用notificationProtocol.systemd后Type=notify、reloadSignal = "HUP"时ExecReload为kill -HUP $MAINPID、未设置重载命令时不得渲染ExecReload（避免与服务自带的定义冲突或渲染出裸ExecReload=行）、服务自带ExecReload时保持原样。这些断言直接锚定了上文 systemd 默认单元模板的行为。

现状与展望

模块化服务是 NixOS 25.11 的新功能，状态为in development，后续很可能有显著变化。它对应的是 RFC 163 的中间产物——"先尝试基于模块的可移植服务方案"，尚非广泛认可的标准解法。手册也明确：模块化服务不是 NixOS 模块的替代品（将来或许会），而"用模块化服务实现 NixOS 模块"是预期用例，只是目前对广泛使用的模块而言不确定性尚不可接受（见 nixos/README-modular-services.md）。

即便如此，从仓库现状（system.services集成、lib/services便携基座、多套 VM/合规测试、多个已入库服务）可以推断：模块化服务正在成为 NixOS 定义"可多实例、可组合、可移植"服务的标准通道。对于编写新服务或重构既有服务的开发者，_class = "service"+process.*+optionalAttrs (options ? systemd)的组合已经是一套可复制、可验证的成熟套路；对于希望在 launchd、s6 等管理器上复用的场景，lib/services/lib.nix 中configure的文档注释（serviceManagerPkgs、baseModules、extraRootModules、extraRootSpecialArgs参数）提供了清晰的接入指引——一个非 systemd 的配置管理框架只需调用lib.services.configure拿到serviceSubmodule类型，再实现自己的服务管理器专属模块即可。

【免费下载链接】nixpkgsNix Packages collection & NixOS项目地址: https://gitcode.com/GitHub_Trending/ni/nixpkgs