Back to Details

nixos-managing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NixOS Management

NixOS管理

Quick Decision: What do you need?

快速决策：你需要做什么？

TaskGo to
Rebuild / activate / rollback systemvm-management.md
Install NixOS on new machineinstallation.md
Build ISO / disk image / VM imageimage-building.md
Configure modules, flakes, packages, servicesconfiguration.md
Ephemeral root / wipe on boot / impermanenceimpermanence.md
LUKS encryption / remote unlock (SSH, Tailscale)luks.md
Health checks / Telegram (or webhook) alerts for filesystem, disk, SMART, servicesmonitoring.md
Something isn't working / weird behavioranti-patterns.md
任务查看文档
重建/激活/回滚系统vm-management.md
在新机器上安装NixOSinstallation.md
构建ISO/磁盘镜像/VM镜像image-building.md
配置模块、flakes、软件包、服务configuration.md
临时根目录/开机重置/无持久化存储impermanence.md
LUKS加密/远程解锁（SSH、Tailscale）luks.md
文件系统、磁盘、SMART、服务的健康检查/Telegram（或Webhook）告警monitoring.md
功能异常/奇怪行为排查anti-patterns.md

Execution Context — Ask First

执行上下文 — 先确认环境

Before suggesting any commands, establish where they will run.
NixOS management involves multiple machines. Commands that work on the NixOS host will fail on macOS or non-NixOS Linux. Always determine the setup before suggesting commands.
If unsure — ask: "Where are you editing configs, and where does nixos-rebuild run?"
在推荐任何命令之前，先确定命令的运行环境。
NixOS管理涉及多台机器。在NixOS主机上可用的命令，在macOS或非NixOS Linux上可能会执行失败。在推荐命令前，务必先确认用户的环境配置。
若不确定，请询问：“你在哪个机器上编辑配置文件，
nixos-rebuild
又在哪个机器上运行？”

All common setups

常见环境场景

Setup A — NixOS local (everything on one machine)
NixOS machine: edit → nixos-rebuild switch (local)
  • All commands run locally
  • nixos-option
    , 
    man configuration.nix
    , 
    nixos-rebuild
    — all local
Setup B — NixOS workstation → NixOS remote server
NixOS workstation (edit) → nixos-rebuild --target-host → NixOS server
  • nixos-rebuild
    runs on workstation, deploys to server
  • Option verification: workstation (has nixpkgs) or server via SSH
  • nixos-option
    on server reflects what's actually active there
Setup C — macOS → NixOS remote (Linux rebuilds locally)
macOS (edit .nix files) → push/rsync → NixOS Linux host → nixos-rebuild switch (local)
  • nixos-rebuild
    runs on the Linux host (SSH in, or via remote trigger)
  • Option verification: SSH into Linux host — macOS has no 
    nixos-option
  • search.nixos.org/options
    always works from macOS
Setup D — macOS → NixOS remote (macOS drives rebuild)
macOS (edit) → nixos-rebuild --target-host root@linux-host --flake .#host
  • nixos-rebuild
    runs on macOS but activates on Linux
  • Requires Nix installed on macOS (
    nix
    CLI, not NixOS)
  • Option verification: 
    nix eval
    works on macOS if Nix is installed; otherwise use 
    search.nixos.org
Setup E — Linux (non-NixOS) → NixOS remote
Ubuntu/Debian/Arch (edit + run nixos-rebuild) → NixOS remote server
  • Same as Setup D — Nix must be installed on the source machine
  • nixos-option
    not available unless NixOS; use 
    nix eval
    or 
    search.nixos.org
Setup F — CI/CD → NixOS remote
CI agent (GitHub Actions / GitLab CI) → deploy to NixOS server
  • CI agent needs Nix installed (use 
    cachix/install-nix-action
    or similar)
  • No interactive verification — all options must be pre-validated
  • Use 
    nix flake check
    in CI to catch errors before deploy
场景A — 本地NixOS（所有操作在同一台机器）
NixOS机器：编辑配置 → 本地执行nixos-rebuild switch
  • 所有命令均在本地运行
  • nixos-option
    、
    man configuration.nix
    、
    nixos-rebuild
    — 全部支持本地执行
场景B — NixOS工作站 → NixOS远程服务器
NixOS工作站（编辑配置） → 执行nixos-rebuild --target-host → NixOS服务器
  • nixos-rebuild
    在工作站运行，部署到服务器
  • 配置项验证：可在工作站（需安装nixpkgs）或通过SSH在服务器上完成
  • 服务器上的
    nixos-option
    反映当前生效的配置
场景C — macOS → NixOS远程服务器（Linux本地执行重建）
macOS（编辑.nix文件） → 推送/rsync → NixOS Linux主机 → 本地执行nixos-rebuild switch
  • nixos-rebuild
    在Linux主机上运行（需SSH登录或远程触发）
  • 配置项验证：必须SSH登录到Linux主机 — macOS没有
    nixos-option
    命令
  • 可在macOS上使用
    search.nixos.org/options
    查询配置项
场景D — macOS → NixOS远程服务器（macOS驱动重建）
macOS（编辑配置） → 执行nixos-rebuild --target-host root@linux-host --flake .#host
  • nixos-rebuild
    在macOS运行，但在Linux主机激活配置
  • 要求macOS上安装Nix（
    nix
    命令行工具，而非NixOS系统）
  • 配置项验证：若macOS安装了Nix，可使用
    nix eval
    ；否则使用
    search.nixos.org
场景E — 非NixOS Linux → NixOS远程服务器
Ubuntu/Debian/Arch（编辑配置+运行nixos-rebuild） → NixOS远程服务器
  • 与场景D一致 — 源机器必须安装Nix
  • 除非是NixOS系统，否则无法使用
    nixos-option
    ；可使用
    nix eval
    或
    search.nixos.org
场景F — CI/CD → NixOS远程服务器
CI代理（GitHub Actions / GitLab CI） → 部署到NixOS服务器
  • CI代理需要安装Nix（可使用
    cachix/install-nix-action
    或类似工具）
  • 无交互式验证 — 所有配置项必须预先验证
  • 在CI中使用
    nix flake check
    在部署前捕获错误

Verification availability by machine type

不同机器类型的验证工具可用性

Machine
nixos-option
nix eval nixpkgs#...
man configuration.nix
search.nixos.org
NixOS host✅✅✅✅
macOS with Nix❌✅❌✅
Linux (non-NixOS) with Nix❌✅❌✅
macOS without Nix❌❌❌✅
CI agent with Nix❌✅❌✅
机器类型
nixos-option
nix eval nixpkgs#...
man configuration.nix
search.nixos.org
NixOS主机✅✅✅✅
安装Nix的macOS❌✅❌✅
安装Nix的非NixOS Linux❌✅❌✅
未安装Nix的macOS❌❌❌✅
安装Nix的CI代理❌✅❌✅

MCP Server: 
mcp-nixos
(optional accelerator)

MCP服务器：
mcp-nixos
（可选加速工具）

If the 
mcp-nixos
MCP server (utensils/mcp-nixos) is configured in the environment, prefer it for lookups over SSH/web round-trips — but ask the user first before using it for a given task: "I can use the mcp-nixos MCP server to look this up directly — want me to use it?"
What it's good at:
  • Exact NixOS package names, versions, metadata (130K+ packages)
  • NixOS options (23K+) — verify option paths before suggesting config
  • Home Manager options (5K+)
  • nix-darwin macOS settings (1K+)
  • Nixvim Neovim configuration (5K+)
  • FlakeHub registry discovery (600+ flakes)
  • Noogle Nix function lookup (2K+)
  • NixOS Wiki / nix.dev documentation
  • Binary cache status checks
  • Local flake input exploration
  • Package version history with nixpkgs commit hashes (reproducible pins)
Use it instead of: guessing option names, scraping 
search.nixos.org
, or SSHing into a host just to run 
nixos-option
. Works on macOS without Nix installed.
Tools exposed: 
nix
(unified query), 
nix_versions
(version history).
When NOT to ask: the user has already said they want (or don't want) to use it this session — honor that preference.
Before installing — security review required. Any MCP server runs with your shell privileges. Before adding 
mcp-nixos
(or any MCP) to the configuration:
  1. Download the source (
    git clone https://github.com/utensils/mcp-nixos
    or inspect the PyPI tarball via 
    uvx --from mcp-nixos --print
    / 
    pip download mcp-nixos --no-deps
    ).
  2. Review it for anything harmful: unexpected network endpoints, filesystem writes outside its own cache, shell/exec calls, credential reads (
    ~/.ssh
    , 
    ~/.aws
    , env vars), obfuscated code, suspicious post-install hooks in 
    pyproject.toml
    / 
    setup.py
    .
  3. Pin to a known-good version/commit rather than a floating tag.
  4. Only after review — add it to the MCP config.
Tell the user what you reviewed and what you found before they approve the install.
若环境中配置了
mcp-nixos
MCP服务器（utensils/mcp-nixos），优先使用它进行查询，以替代SSH/网页往返操作 — 但在为特定任务使用前，请先询问用户：“我可以使用mcp-nixos MCP服务器直接查询相关内容 — 是否需要启用该工具？”
适用场景：
  • 精确查询NixOS软件包的名称、版本、元数据（超过13万个软件包）
  • NixOS配置项（超过23000个） — 在推荐配置前验证配置项路径
  • Home Manager配置项（超过5000个）
  • nix-darwin macOS设置（超过1000个）
  • Nixvim Neovim配置（超过5000个）
  • FlakeHub注册表发现（超过600个flakes）
  • Noogle Nix函数查询（超过2000个）
  • NixOS Wiki / nix.dev文档
  • 二进制缓存状态检查
  • 本地flake输入探索
  • 基于nixpkgs提交哈希的软件包版本历史（可复现的版本锁定）
替代方案： 无需猜测配置项名称、爬取
search.nixos.org
，或仅为运行
nixos-option
而SSH登录主机。即使macOS未安装Nix也可使用。
提供的工具： 
nix
（统一查询）、
nix_versions
（版本历史）。
无需询问的情况： 用户已明确表示本次会话是否要使用该工具 — 尊重用户的选择。
安装前注意 — 需进行安全审查。 任何MCP服务器都会以你的Shell权限运行。在将
mcp-nixos
（或任何MCP工具）添加到配置前：
  1. 下载源代码（
    git clone https://github.com/utensils/mcp-nixos
    ，或通过
    uvx --from mcp-nixos --print
    / 
    pip download mcp-nixos --no-deps
    检查PyPI压缩包）。
  2. 检查是否存在有害内容：意外的网络端点、超出自身缓存目录的文件系统写入、Shell/执行调用、读取凭据（
    ~/.ssh
    、
    ~/.aws
    、环境变量）、混淆代码、
    pyproject.toml
    / 
    setup.py
    中可疑的安装后钩子。
  3. 锁定到已知安全的版本/提交记录，而非浮动标签。
  4. 审查通过后 — 再将其添加到MCP配置中。
告知用户你审查的内容和结果，再等待用户批准安装。

Option Verification — Always Verify Before Suggesting

配置项验证 — 推荐前务必验证

Never suggest a NixOS option from memory alone. Option names change between NixOS versions, and incorrect options fail silently or produce confusing errors.
Fastest path (if available): the 
mcp-nixos
MCP server — see section above. Ask the user before using it.
Run on the NixOS host (not macOS, not CI unless it runs NixOS):
bash
undefined
切勿仅凭记忆推荐NixOS配置项。 不同NixOS版本的配置项名称可能会变化，错误的配置项会静默失败或产生令人困惑的错误。
最快验证方式（若可用）： 使用
mcp-nixos
MCP服务器 — 见上文。使用前需询问用户。
在NixOS主机上运行（不要在macOS、CI环境中运行，除非CI环境是NixOS）：
bash
undefined

Search available options interactively

交互式搜索可用配置项

nixos-option services.openssh.settings
nixos-option services.openssh.settings

Evaluate option existence in current nixpkgs

评估当前nixpkgs中是否存在该配置项

nix eval nixpkgs#nixosOptionsDoc --apply 'x: builtins.attrNames x' 2>/dev/null | grep -o '"[^"]PasswordAuth[^"]"'
nix eval nixpkgs#nixosOptionsDoc --apply 'x: builtins.attrNames x' 2>/dev/null | grep -o '"[^"]PasswordAuth[^"]"'

Quickest: man page on the NixOS machine

最快捷方式：在NixOS机器上查看手册页

man configuration.nix | grep -A3 "PasswordAuthentication"

**Or use the web** (version-specific, always available):
- `https://search.nixos.org/options` — search by option name, filterable by channel
- Check the channel matching your `nixpkgs.url` (e.g. `nixos-25.05`)

**Workflow when unsure about an option:**
1. Check `search.nixos.org/options` for the option name and correct path
2. Note the NixOS version it applies to
3. Only then include it in configuration
man configuration.nix | grep -A3 "PasswordAuthentication"

**或使用网页工具**（按版本区分，始终可用）：
- `https://search.nixos.org/options` — 按配置项名称搜索，可按频道筛选
- 选择与你的`nixpkgs.url`匹配的频道（例如`nixos-25.05`）

**不确定配置项时的工作流程：**
1. 在`search.nixos.org/options`上查询配置项名称和正确路径
2. 记录该配置项适用的NixOS版本
3. 确认无误后再将其添加到配置中

Core Mental Model

核心思维模型

NixOS is declarative and atomic. Every change produces a new generation. You can always roll back.
Key workflow:
  1. Edit 
    .nix
    files
  2. git add
    (in flakes — untracked files are invisible to Nix)
  3. nixos-rebuild test
    (activate without committing to bootloader)
  4. nixos-rebuild switch
    (set as default boot)
NixOS是声明式且原子化的系统。每一次变更都会生成一个新的系统代次。你始终可以回滚到之前的状态。
关键工作流程：
  1. 编辑
    .nix
    文件
  2. git add
    （在flakes模式下 — 未跟踪的文件对Nix不可见）
  3. nixos-rebuild test
    （激活配置但不修改引导加载项 — 安全的第一步）
  4. nixos-rebuild switch
    （设置为默认引导项）

Flakes vs Channels

Flakes vs Channels

Use flakes for reproducibility. Channels are impure (machine-dependent lookup paths).
Enable flakes once:
nix
nix.settings.experimental-features = [ "nix-command" "flakes" ];
优先使用flakes以确保可复现性。Channels是非纯净的（依赖机器特定的查找路径）。
只需启用一次flakes：
nix
nix.settings.experimental-features = [ "nix-command" "flakes" ];

Common 
nixos-rebuild
Commands

常用
nixos-rebuild
命令

CommandWhen to use
nixos-rebuild switch
Apply + set as default boot
nixos-rebuild test
Apply now, skip bootloader — safe first step
nixos-rebuild boot
Set as next boot without activating now
nixos-rebuild dry-activate
Preview changes without applying
nixos-rebuild build
Build only, creates 
./result
nixos-rebuild build-vm
Build QEMU VM for local testing
Always test before switch — especially on remote servers:
bash
nixos-rebuild test --flake .#hostname --target-host root@server
nixos-rebuild switch --flake .#hostname --target-host root@server
命令使用场景
nixos-rebuild switch
应用配置并设置为默认引导项
nixos-rebuild test
立即应用配置，不修改引导加载项 — 安全的测试步骤
nixos-rebuild boot
设置为下次引导项，但不立即激活
nixos-rebuild dry-activate
预览变更但不实际应用
nixos-rebuild build
仅构建系统，生成
./result
目录
nixos-rebuild build-vm
构建QEMU虚拟机用于本地测试
在执行switch前务必先测试 — 尤其是远程服务器：
bash
nixos-rebuild test --flake .#hostname --target-host root@server
nixos-rebuild switch --flake .#hostname --target-host root@server

Remote Deployment Tools

远程部署工具

ToolBest for
nixos-rebuild --target-host
1-3 machines, simplest
deploy-rs
Small fleet, auto-rollback on failure
colmena
Large fleet, parallel, cross-host config
nixos-anywhere
Initial install on non-NixOS machine
工具最佳适用场景
nixos-rebuild --target-host
1-3台机器，最简单的方式
deploy-rs
小型机器集群，失败时自动回滚
colmena
大型机器集群，支持并行部署、跨主机配置
nixos-anywhere
在非NixOS机器上初始安装NixOS

Secret Management

密钥管理

ToolWhen to use
agenixSimple setup, SSH key workflow, small secret count
sops-nixCloud KMS needed, templating, multiple formats
Secrets live at 
/run/agenix/
or 
/run/secrets/
— never in Nix store.
工具使用场景
agenix配置简单，基于SSH密钥工作流，密钥数量较少的场景
sops-nix需要云KMS、模板化支持、多格式密钥的场景
密钥存储在
/run/agenix/
或
/run/secrets/
目录 — 切勿存储在Nix存储库中。

Most Frequently Changed Elements

最常修改的配置元素

  • environment.systemPackages
    — installed packages
  • users.users.<name>
    — user accounts and SSH keys
  • networking.*
    — hostname, IPs, firewall ports
  • services.*
    — enable/configure systemd services
  • boot.loader.*
    — bootloader and kernel settings
  • nix.settings.*
    — substituters, trusted users, features
See configuration.md for patterns.
  • environment.systemPackages
    — 已安装的软件包
  • users.users.<name>
    — 用户账户和SSH密钥
  • networking.*
    — 主机名、IP地址、防火墙端口
  • services.*
    — 启用/配置systemd服务
  • boot.loader.*
    — 引导加载项和内核设置
  • nix.settings.*
    — 替代源、可信用户、实验性功能
更多配置模式请查看configuration.md。