Skip to content
lilei0918Public

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

nixos-DMS — NixOS 配置参考手册(README)

本仓库是 Lei 的 NixOS 配置(flake 化),目标主机 Lenovo Legion R7000P 2021。本文档既是仓库 README,也是面向 AI 助手(opencode 等)与本人备查的完整参考手册:覆盖硬件、目录结构、各模块详解、维护流程与排障。

技术栈:NixOS(nixos-unstable)+ niri(滚动式 Wayland compositor)+ Noctalia(v5,bar/launcher/控制中心/通知;替代原 DMS) + greetd/tuigreet + Home Manager + sops-nix(age 加密)。主机配置名 legion,主机名 nixos。

改动配置的流程不变: cd nixos-DMS alejandra . nix flake check git add -A && git commit -m "before switch" nh os switch .#legion

目标:让 AI 助手(opencode 等)理解这套 NixOS 配置的完整结构、硬件背景和日常维护流程,以便提供精准的操作建议。 本文档为静态知识库:只维护长期不变的事实(硬件拓扑、模块结构、维护流程)。系统版本、generation、内核、服务状态等动态值一律不写入文档,需要时按「二、当前系统状态」的获取命令实时查询。涉及硬件事实的测量日期在对应表格处标注。


一、硬件与系统概览

  • 机型:Lenovo Legion R7000P 2021(AMD 平台)
  • CPU:AMD Ryzen 5 5600H(12 线程,基础频率 3.3GHz,最高 4.28 GHz)
  • GPU:
    • 集成显卡:AMD Radeon Vega Series(当前驱动 amdgpu)
    • 独立显卡:NVIDIA RTX 3050 Ti Mobile(vars/default.nix 的 enableNvidia = true,启用 nvidia.nix 的 PRIME offload + RTD3 省电方案;置 false 则由 nvidia-block.nix 屏蔽、仅用核显省电)
  • 内存:32GB
  • 存储(⚠️ 内核设备名 nvme0n1/nvme1n1 会随 BIOS 枚举顺序变化,本仓库一律用 磁盘 by-id + 分区 UUID + 文件系统标签,不写死设备名;下表按物理盘型号分节):
    • SK Hynix HFS512GDE9X084N(512GB,GPT) —— Windows 11 系统盘 + Windows ESP + NixOS ESP(NixOS GRUB 引导所在)+ Immich 媒体库
    • ZHITAI TiPlus7100 1TB(MBR) —— NixOS 主盘(Btrfs 根分区)+ NTFS 数据盘 DATATB + 20G LUKS 加密盘(密码库/个人文件,含 Vaultwarden 备份归档)

存储与分区详表(2026-11-07 实测)

实测命令(只读):lsblk -o NAME,SIZE,TYPE,FSTYPE,PTTYPE,LABEL,UUID,PARTUUID、ls -l /dev/disk/by-id /dev/disk/by-uuid 权威标识 = 磁盘 by-id + 分区 UUID/PARTUUID + 文件系统标签。nvme0n1/nvme1n1 这类内核设备名不写死(本机已发生过互换)。 表内 p1…p7 是该盘自身的分区编号,只在同一块盘内有效。

盘 1:by-id/nvme-SKHynix_HFS512GDE9X084N_CJA5N775913905S66(512GB,GPT)

分区 大小 文件系统 标签 用途 UUID(FS) PARTUUID
p1 100 MiB vfat — Windows EFI 分区 785A-7651 2997a151-0dad-410f-9f57-50fef583b05d
p2 16 MiB — — Microsoft Reserved (MSR) — 46a4cccd-a73b-4105-a662-a018a613c2d9
p3 148.4 GiB ntfs Win11 Windows 11 系统盘 (C:) 68D4EDC8D4ED9918 e68b0315-6182-4c7f-b465-ae6b74480f0e
p4 0.93 GiB ntfs — Windows 恢复分区 (WinRE) E05682B656828D4A 9a8d033b-45f4-475f-a761-288732bfd65d
p5 0.56 GiB ntfs — Windows 恢复分区 (WinRE) 6016A3AC16A381A0 29f912b6-a781-4cba-8913-41767db0879e
p6 2.00 GiB vfat — NixOS ESP(GRUB 主引导,挂载 /boot/efi) AC09-EF5B cc17ada6-9af8-4df3-b926-33770fe489cb
p7 324.94 GiB btrfs IMMICH Immich 媒体库(挂载 /srv/immich) 5c0e846a-5822-4059-bb93-f0256dd2a81c 29447188-9240-4817-aaab-61756562a665
  • p7 是原 Arch 根分区(UUID 9dccd22a-…,2026-09 删除)释放的空间,2026-10 重建为 Immich 托管库;挂载用 by-label/IMMICH
  • Windows 侧占用 p1 / p3 / p4 / p5,p2 为 MSR

盘 2:by-id/nvme-ZHITAI_TiPlus7100_1TB_ZTA71T0AB24182L6AD(1TB,MBR)

分区 大小 文件系统 标签 用途 UUID(FS) PARTUUID
p1 783.87 GiB ntfs DATATB 数据盘(挂载 /run/media/lilei/DATATB) FAC6848EC6844D37 ebf47cf2-01
p2 150.00 GiB btrfs NIXOS NixOS 根分区(挂载 /、/home、/nix、/var/log 等子卷) 6c9764ff-c293-4be8-801c-982bdb6ed30a ebf47cf2-02
p3 20.00 GiB LUKS2 — 加密数据盘(密码库/个人文件,挂载 /mnt/vault) 86c742fc-8de5-4c59-9a30-196484a35695 ebf47cf2-03
  • 分区表是 MBR(dos),不是 GPT;hosts/legion/disko-fs.nix 用 disko 的 legacy table + format = "msdos" 如实描述(MBR 的 4 个主分区槽位已用 3 个)

  • 物理顺序是 p1 → p3 → p2(p2 在盘尾 150 GiB,p3 在中间 20 GiB);编号以本表为准

  • p2 的 Btrfs 子卷:@→/、@home→/home、@nix→/nix、@log→/var/log(见 hardware-configuration.nix)

  • p3 即 LUKS 加密盘(解锁后 ext4,挂载 /mnt/vault),对应 vault.nix 里的 LUKS UUID 86c742fc-…(cryptsetup open UUID=…,不依赖分区路径)

  • DATATB 自动挂载:已在 hosts/legion/configuration.nix 的 fileSystems."/run/media/lilei/DATATB" 中配置(by-label/DATATB,ntfs3 + x-systemd.automount,nofail,uid=1000/gid=100/umask=022)

  • 多系统引导(2026-11-07 实测):Windows ESP(盘 1 p1,785A-7651)与 NixOS ESP(盘 1 p6,AC09-EF5B,挂 /boot/efi)是两个独立 ESP。主引导为 AC09-EF5B 上的 NixOS GRUB,开机直接进 GRUB 菜单(最新 NixOS 默认 + Windows 11,5 秒倒计时),generations 也在同一菜单内选择;Windows 原生 EFI 留在 785A-7651 不动。引导细节与 NVRAM 说明见「四.6 system/boot.nix」与「九」。

  • 主机名:nixos(system/network.nix 中设置;flake 配置名才是 legion)

  • NixOS 用户:仅 lilei(普通用户,加入 wheel、networkmanager、video、input 组)。

  • 配置仓库:git@github.com:lilei0918/nixos-DMS.git(本地路径 /home/lilei/nixos-DMS),已备份。


二、当前系统状态(以命令实测为准)

本节只给获取命令与不变的架构事实,不保存会过期的版本号 / generation / 服务状态 / 运行时长。 需要某时刻的实测值时执行对应命令即可,输出即为当时状态。

固定架构(不随升级变化的部分):

  • 显示管理器:greetd + tuigreet(Wayland,--cmd niri-session)
  • 窗口管理器:niri(nixpkgs 自带 pkgs.niri,手写 KDL,见「六、Niri 配置」)
  • 终端:主用 alacritty(super+return);次选 ghostty(super+shift+return)
  • Shell:终端常用 fish;默认登录 shell 为 zsh,可自由切换
  • 会话:纯 Wayland(X 应用走 xwayland-satellite)

动态值 → 获取命令:

要查什么 命令
NixOS 版本 nixos-version
内核版本 uname -r
nixpkgs unstable commit nix flake metadata(或直接看 flake.lock)
当前 / 历史 generation sudo nixos-rebuild list-generations
系统安装天数 echo $(( ($(date +%s) - $(stat -c %W /)) / 86400 ))
各服务状态 systemctl is-active greetd vaultwarden.service
磁盘 / 分区(UUID 权威) lsblk -f、sudo blkid
快速总览 fastfetch

三、目录结构与职责

nixos-DMS/
├── flake.nix                # 总入口:inputs / outputs(含 eval 测试、pre-commit 钩子、devShell)
├── flake.lock               # 锁定所有 inputs 版本
├── README.md                # 本文档(完整参考手册:仓库简介 + 全部配置详解)
├── MEMO.md                  # 命令速查备忘录(日常备查)
├── AGENTS.md                # AI agent 行为规则(安全边界、机密处理、工具默认值)
├── agents/
│   ├── README.md            # 说明本目录(规则/权限配套)
│   └── permissions.md       # 权限策略(敏感文件 deny、命令 allow/ask)
├── vars/
│   └── default.nix          # 集中变量(username/userfullname/useremail/homeDirectory/repoDir/flakeName/theme),经 myvars 注入所有模块
├── tests/                   # flake 求值测试(expr.nix vs expected.nix,`nix flake check` 自动跑)
├── secrets/
│   └── secrets.yaml         # 加密的机密文件(sops:deepseek_api_key / vaultwarden_admin_token / password_hash / vaultwarden_tls_*)
├── hosts/
│   └── legion/              # 主机专属配置(flake 配置名 legion)
│       ├── configuration.nix   # NixOS 系统配置入口(导入所有模块;DATATB 自动挂载)
│       ├── hardware-configuration.nix  # 硬件自动生成(勿手动修改)
│       ├── disko-fs.nix        # disko 分区描述(未导入,参考/重装用;只动 ZHITAI 盘的 NIXOS 分区 p2)
│       ├── home.nix            # Home Manager 入口(niri KDL 配置、fcitx5 覆盖等)
│       └── packages.nix        # 用户级软件包列表
├── scripts/                # 运维辅助脚本
│   ├── backup-credentials.sh # 信任根/凭据备份(sops age key / ssh / opencode / mihomo / pi)
│   ├── git-hooks/          # 自愈式 git pre-commit 钩子(nix develop 自动安装)
│   └── README.md           # 脚本用法与故障排查
├── system/                  # 系统级配置(影响所有用户)
│   ├── nix.nix              # Nix 自身设置(flakes、镜像源、GC 7d、NUR overlay)
│   ├── cleanup.nix          # journal 日志上限 200M(services.journald.settings.Journal)
│   ├── tmpfs.nix            # 易失文件系统:/tmp(4G)+ ~/.cache(6G)tmpfs
│   ├── boot.nix             # 启动引导(GRUB 主引导,双 ESP 双系统菜单)
│   ├── hardware.nix         # 硬件:GPU 图形、蓝牙、fstrim、btrfs scrub
│   ├── network.nix          # 网络(NetworkManager、NTP)——防火墙配置已下放到 proxy/*.nix
│   ├── services.nix         # 系统服务(PipeWire/tuned 等;桌面壳 Noctalia 走 HM 模块)
│   ├── secrets.nix          # sops 机密声明
│   ├── fonts.nix            # 字体(思源黑体/宋体、Inter、JetBrainsMono NF + fontconfig 映射)
│   ├── input.nix            # 输入法(Fcitx5/Rime)
│   ├── xdg.nix              # XDG 桌面门户(gtk 后端)
│   ├── greetd.nix           # 登录管理器(greetd + tuigreet)
│   ├── nix-ld.nix           # nix-ld 动态链接器(非 Nix 二进制运行所需系统库 + jpeg-8 旧 ABI)
│   ├── packages.nix         # 系统级软件包列表
│   ├── proxy/               # 代理(clash-verge 主用,mihomo 备用)
│   │   ├── clash-verge.nix      # 【启用】Clash Verge Rev(programs.clash-verge,serviceMode + tunMode + autoStart)
│   │   └── mihomo.nix           # 【备用】mihomo(TUN 模式,切回方法见文件头注释)
│   ├── nvidia/              # NVIDIA 显卡模块(myvars.enableNvidia 二选一)
│   │   ├── nvidia.nix           # 【当前启用,enableNvidia = true】PRIME offload + RTD3 空闲断电
│   │   └── nvidia-block.nix     # 【备选】屏蔽 NVIDIA 独显(省电,纯核显)
│   ├── vault/               # 加密数据盘 + Vaultwarden 密码管理器
│       ├── vault.nix            # LUKS 加密盘(vault-open / vault-close,手动解锁)
│       ├── vaultwarden.nix      # 密码管理器(Podman + Quadlet 容器,SQLite,TLS 走 sops)
│       ├── vaultwarden-backup.nix  # 每日在线备份(本地 7 天 + DATATB 镜像 + 加密盘归档)
│       └── certs/               # Vaultwarden 本地 CA 公钥(vaultwarden-ca.crt,私钥走 sops)
│   ├── immich.nix           # Immich 照片库(独立 btrfs 分区 /srv/immich,仅本机/局域网)
│   ├── immich-backup.nix    # Immich 每日备份(**仅数据库**,异盘镜像;不镜像媒体原图)
│   ├── immich-deduper.nix   # Immich 重复/相似照片清理(按需 systemctl start,不常驻)
│   ├── immich-power-tools.nix # Immich 批量整理 Web UI(按需 systemctl start,不常驻)
│   └── tailscale.nix        # Tailscale 尾网(远程访问,serve 出 HTTPS)
├── home/                    # 用户级配置(仅 lilei)
│   ├── niri/                # Niri 窗口管理器配置(手写 KDL,见「六」)
│   │   ├── kdl.nix          # HM 模块:链接 conf/ 到 ~/.config/niri/
│   │   ├── conf/config.kdl  # 主配置(input/输出/layout/环境变量,include 分片)
│   │   ├── conf/keybindings.kdl  # 快捷键
│   │   ├── conf/windowrules.kdl  # 窗口规则
│   │   └── conf/spawn-at-startup.kdl  # 自启动
│   ├── terminal/            # 终端相关
│   │   ├── alacritty.nix    # 主终端(Monokai Pro 配色、fish)
│   │   ├── ghostty.nix      # 次选终端(Monokai Pro 主题)
│   │   ├── fish.nix         # fish shell(别名、插件)
│   │   ├── zsh.nix          # zsh(oh-my-zsh、别名)
│   │   ├── starship.nix     # prompt
│   │   └── tmux.nix
│   └── programs/            # 用户软件包及配置
│       ├── AI/              # AI 工具(zed / vscode / opencode / codex / pi)
│       ├── btop.nix
│       ├── chrome.nix       # Google Chrome(Wayland + VA-API 硬解)
│       ├── dconf.nix        # GNOME dconf 主题设置
│       ├── elyoffice.nix    # ElyOffice 办公套件(flake input,AppImage 包装)
│       ├── fastfetch.nix    # 系统信息(FastCat Simple 主题,无 logo)
│       ├── firefox.nix      # Firefox(NUR 扩展、搜索配置;⚠️ 当前未导入 home.nix,保留备用)
│       ├── git.nix          # git + delta
│       ├── rime.nix         # Rime 输入法(rime-ice 方案 + fcitx 环境变量)
│       ├── theme.nix        # GTK/Qt 主题(WhiteSur)
│       ├── thunar.nix       # 文件管理器(xfconf 依赖)
│       └── walker.nix       # 应用启动器(+ elephant 剪贴板依赖)
└── assets/                  # 静态资源(icons/logo.png 已随 fastfetch 换主题删除)

生成/忽略文件(不在 git 内):niri-colors.generated.kdl(dms 动态主题生成)、.pre-commit-config.yaml(git-hooks.nix 生成)、result/、.direnv/。.typos.toml 是 typos 拼写检查配置(已提交)。 本仓库几乎每个子目录都带一份轻量 README.md(文件索引 + 要点 + 指回本文档对应章节),AI agent 可直接就地读取。


四、核心配置文件详解

1. flake.nix

作用:定义所有输入源,输出 NixOS 配置、测试、checks 和 devShell。

关键内容:

  • inputs 包含:
    • nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"
    • home-manager(follows nixpkgs)
    • nur(NUR 仓库)
    • sops-nix(follows nixpkgs)
    • pre-commit-hooks(github:cachix/git-hooks.nix,follows nixpkgs,提供 alejandra + typos 钩子)
    • nixos-grub-themes(github:jeslie0/nixos-grub-themes,follows nixpkgs,提供 GRUB 主题包,boot.nix 用其 nixos)
  • noctalia(github:noctalia-dev/noctalia,不 follows nixpkgs:上游 Cachix 按自身 nixpkgs 构建,follows 会使缓存全失效;桌面壳走其 HM 模块)
  • 输入源说明:
    • ⚠️ niri 已不使用 niri-flake(2026-08-30 改):改用 nixpkgs 自带 pkgs.niri(跟随 nixpkgs unstable,26.04,支持 include 语法),配置改为手写 KDL(home/niri/conf/*.kdl)。曾因 niri-flake 的 nixpkgs pin(624af66,libdisplay-info 0.2.0)而锁定 stable 25.08,现已废弃该方案。
  • outputs:
    • nixosConfigurations.legion:nixosSystem(system = x86_64-linux),specialArgs = { inherit self inputs myvars; }(myvars 来自 ./vars),模块:
      • ./hosts/legion/configuration.nix
      • home-manager.nixosModules.default
      • sops-nix.nixosModules.sops
    • checks.x86_64-linux:evalTestsCheck(包装 eval 测试)+ preCommitCheck(alejandra --check + typos),供 nix flake check 使用
    • devShells.x86_64-linux.default:nix develop 进入开发环境(含 alejandra/typos,自动装 git pre-commit 钩子)
    • formatter.x86_64-linux:alejandra

2. hosts/legion/configuration.nix

作用:主机入口,导入所有系统级模块并配置用户。

关键内容:

  • imports 列表(按分组):
    • 硬件:./hardware-configuration.nix
    • system 模块:../../system/nix.nix、cleanup.nix、boot.nix、hardware.nix、network.nix、services.nix
    • desktop:fonts.nix、input.nix、xdg.nix
    • programs:../../system/nvidia/(由 myvars.enableNvidia 在 nvidia.nix / nvidia-block.nix 间二选一,当前 true 启用 nvidia.nix)、../../system/proxy/clash-verge.nix(主用)、packages.nix、nix-ld.nix
    • vault:../../system/vault/vaultwarden.nix、vaultwarden-backup.nix、vault.nix
    • greeter:greetd.nix
    • secrets:secrets.nix
  • 用户 lilei(经 myvars.username):isNormalUser = true,shell = pkgs.zsh,extraGroups = [ "wheel" "networkmanager" "video" "input" ]。密码 hash 不落仓库:hashedPasswordFile = config.sops.secrets.password_hash.path。
  • DATATB 自动挂载:fileSystems."/run/media/lilei/DATATB" = ntfs3(/dev/disk/by-label/DATATB,uid=1000 gid=100 umask=022 nofail x-systemd.automount)。
  • environment.localBinInPath = true:把 ~/.local/bin 加进 PATH(自定义脚本:futu 等)。
  • Home Manager:useGlobalPkgs = true、useUserPackages = true、extraSpecialArgs = { inherit inputs myvars; }、users.${myvars.username} = import ./home.nix、备份扩展名 backup。
  • programs.dconf.enable = true;time.timeZone = "Asia/Shanghai"、console.keyMap = "us";programs.zsh.enable = true;system.stateVersion = "25.05"。
  • system.activationScripts.logRebuildTime 写入 /var/log/nixos-rebuild-log.json(记录重建日期和 generation 号)。

3. hosts/legion/hardware-configuration.nix

作用:硬件自动生成(nixos-generate-config,勿手动修改)。

关键内容:

  • 导入 modulesPath + "/installer/scan/not-detected.nix"
  • boot.initrd.availableKernelModules:nvme, xhci_pci, ahci, usbhid, usb_storage, sd_mod
  • 文件系统挂载(Btrfs 子卷,UUID 6c9764ff-c293-4be8-801c-982bdb6ed30a):
    • / → 子卷 @,compress=zstd,noatime,discard=async
    • /home → 子卷 @home、/nix → 子卷 @nix、/var/log → 子卷 @log
    • /boot/efi → VFAT,UUID AC09-EF5B(SK Hynix 盘 p6,NixOS 独立 ESP;权威值以本文件为准),fmask=0022,dmask=0022
  • /tmp(4G)与 ~/.cache(6G)为 tmpfs,声明在 system/tmpfs.nix(本文件只保留硬件事实);~/.cache 为易失数据,每次开机按需重建
  • swapDevices = [](无交换)
  • networking.useDHCP = lib.mkDefault true
  • nixpkgs.hostPlatform = "x86_64-linux"
  • hardware.cpu.amd.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware

4. system/nix.nix

作用:Nix 自身配置。

内容:

  • nixpkgs.overlays:加载 NUR(import inputs.nur { nurpkgs = prev; pkgs = prev; })→ 提供 pkgs.nur
  • 启用 flakes 和 nix-command:experimental-features = [ "nix-command" "flakes" ]
  • auto-optimise-store = true
  • substituters:Tuna(priority 1)、USTC(priority 2)、cache.nixos.org(priority 20)
  • trusted-public-keys:cache.nixos.org 的 key
  • nix.gc:自动,dates = "daily",options = "--delete-older-than 7d"(内置 nix-gc.timer 带 Persistent=true,关机错过会在开机补跑)
  • nixpkgs.config.allowUnfree = true

5. system/cleanup.nix(新增)

作用:系统日志上限(journal)。

内容:

  • services.journald.settings.Journal:SystemMaxUse = "200M"、SystemKeepFree = "1G"(journal 不会涨满 /var/log)
  • 用户缓存 ~/.cache 已是 tmpfs(见 system/tmpfs.nix),重启即空,无需再用 tmpfiles 年龄规则清理

6. system/boot.nix

作用:主引导配置(2026-09-05 起为 GRUB)。

背景:Windows ESP(785A-7651)与 NixOS ESP(AC09-EF5B)是两个独立 ESP,systemd-boot 只会扫描自身所在 ESP,看不到 Windows 那个 → 改用 GRUB 主引导。

内容:

  • boot.loader.timeout = 5:菜单 5 秒倒计时,超时进入最新 NixOS generation(默认项)
  • boot.loader.grub:enable = true、efiSupport = true、device = "nodev"(EFI 安装到 /boot/efi)
  • boot.loader.grub.theme:NixOS 官方 logo 风格主题(inputs.nixos-grub-themes.packages.${pkgs.system}.nixos,flake input nixos-grub-themes)
  • boot.loader.grub.extraEntries:手写 Windows 11 menuentry —— search --file /EFI/Microsoft/Boot/bootmgfw.efi --set=root + chainloader,GRUB 每次开机跨磁盘找 p1 的引导文件(不依赖 os-prober,Windows 更新后无需手动同步)
  • extraEntriesBeforeNixOS = false:Windows 排在 NixOS 之后,保持默认项为 NixOS
  • boot.loader.efi.efiSysMountPoint = "/boot/efi"
  • boot.loader.efi.canTouchEfiVariables = true:NixOS 自管 NVRAM 引导项(rebuild 自动注册/自愈)
  • boot.kernelPackages = pkgs.linuxPackages_latest
  • boot.kernelParams = [ "amd_pstate=passive" "nowatchdog" ]

7. system/hardware.nix

内容:

  • hardware.graphics.enable = true,extraPackages = [ libva libvdpau vulkan-loader vulkan-tools vulkan-validation-layers ]
  • hardware.bluetooth:enable = true,powerOnBoot = true
  • hardware.enableRedistributableFirmware = true
  • services.udev.packages = [ pkgs.rwedid ]
  • services.fstrim.enable = true
  • services.btrfs.autoScrub.enable = true

8. system/network.nix

内容:

  • networking.hostName = "nixos"(⚠️ 与 flake 名 legion 不同)
  • networking.networkmanager.enable = true,wifi.backend = "wpa_supplicant",wifi.powersave = false
  • services.timesyncd.enable = true,networking.timeServers = [ "ntp.aliyun.com" "ntp.tencent.com" ]
  • ⚠️ 防火墙已从本文件下放:clash-verge.nix 经 tunMode 把 checkReversePath 默认设为 "loose"(network.nix 已是 loose);mihomo.nix 设 trustedInterfaces = [ "Meta" ] + 放行端口。不要在 network.nix 重复配置。

9. system/services.nix

作用:系统服务配置(最核心的服务文件)。

包含内容:

  • 桌面壳(Noctalia,完整方案):flake input noctalia(唯一不 follows nixpkgs 的 input,为了命中 noctalia.cachix.org 预编译缓存)→ hosts/legion/home.nix 导入 inputs.noctalia.homeModules.default,用 programs.noctalia 声明式配置(theme/wallpaper/launch_apps_as_systemd_services),并 systemd.enable = true(自启 + 崩溃重启 + rebuild 重启)。不要再在 niri 里 spawn-at-startup "noctalia",会起两份抢 IPC socket。⚠️ 两层配置:~/.config/noctalia/config.toml(Nix 生成,只读)< ~/.local/state/noctalia/settings.toml(运行时状态,优先级更高);改了 Nix 设置没生效时,停服务并移走后者即可回落
  • ⚠️ 未启用 services.xserver(纯 Wayland;X 应用走 xwayland-satellite,AMD 图形由 hardware.graphics 提供)
  • services.dbus.enable = true,packages 包含 bluez
  • 电源调度:services.tuned(enable = true、settings.dynamic_tuning、ppdSupport,PPD 默认档 power-saver);services.power-profiles-daemon.enable = false(与 tuned 冲突,必须关)
  • Legion 静音兜底:quiet-fan-boot / quiet-fan-resume / initrd quiet-fan-initrd 三处把 EC platform_profile 写回 low-power(电源键蓝灯),quiet-fan-boot 另强制 PPD 档回 power-saver(Noctalia bar 显示正确)。tuned 会持久化被切过的 PPD 档,重启被这些服务强制回静音
  • services.gvfs.enable = true,services.tumbler.enable = true
  • services.pipewire:alsa(含 support32Bit)/pulse/jack/wireplumber 全部开启
  • security.rtkit.enable = true
  • security.pam.services.greetd.enableGnomeKeyring = true,services.gnome.gnome-keyring.enable = true
  • services.upower.enable = true,services.pulseaudio.enable = false,services.blueman.enable = true

10. system/secrets.nix

内容:

  • sops.defaultSopsFile = ../secrets/secrets.yaml
  • sops.age.keyFile = "/etc/sops/age/keys.txt"
  • sops.secrets:
    • deepseek_api_key = {}、vaultwarden_admin_token = {}
    • password_hash:neededForUsers = true(activation 阶段先于用户创建解密,供 hashedPasswordFile 使用)
    • vaultwarden_tls_ca_key / vaultwarden_tls_ca_crt / vaultwarden_tls_server_key / vaultwarden_tls_server_crt:path 指向 /var/lib/vaultwarden/tls/*(boot 时 sops-nix 解密写入)

11. system/fonts.nix

作用:字体全套声明式配置(2026-08 大改:思源黑体/宋体取代 Noto CJK 主力)。

内容:

  • fonts.enableDefaultPackages = false(默认字体包关闭,由 packages 完全接管)
  • fonts.packages:inter、source-serif、source-han-serif(思源宋体)、source-han-sans(思源黑体)、source-han-mono(思源等宽)、nerd-fonts.jetbrains-mono、noto-fonts-color-emoji、noto-fonts
  • fonts.fontconfig.defaultFonts:
    • sansSerif:["Inter" "Source Han Sans SC" "Source Han Sans TC" "Noto Sans"]
    • serif:["Source Han Serif SC" "Source Han Serif TC" "Source Serif 4"]
    • monospace:["JetBrainsMono Nerd Font" "Source Han Mono SC" "Source Han Mono TC"]
    • emoji:["Noto Color Emoji"]
  • 渲染参数(macOS 观感):antialias = true、hinting.style = "slight"、subpixel.rgba = "rgb"、lcdfilter = "default"
  • localConf(写入 /etc/fonts/local.conf):关 autohint/embeddedbitmap、ui-*/-apple-system/SF Pro* → Inter、SF Mono → JetBrainsMono Nerd Font、Noto CJK* → Source Han 分地区子家族映射

12. system/input.nix

作用:输入法配置(系统级 Fcitx5)。

  • i18n.inputMethod.type = "fcitx5",waylandFrontend = true
  • addons:fcitx5-rime、fcitx5-gtk、fcitx5-material-color、qt6Packages.fcitx5-chinese-addons、qt6Packages.fcitx5-configtool

13. system/xdg.nix

作用:XDG 桌面门户。

  • xdg.portal.enable = true,仅 extraPortals = [ xdg-desktop-portal-gtk ]
  • config.niri.default = [ "gtk" ]

14. system/greetd.nix

作用:登录管理器(greetd + tuigreet,Wayland 会话)。

  • services.greetd.settings.default_session.command = "${pkgs.tuigreet}/bin/tuigreet --remember --asterisks --container-padding 2 --no-xsession-wrapper --cmd niri-session"
  • user = "greeter"
  • systemd.settings.Manager.DefaultTimeoutStopSec = "10s"(防止关机卡住)
  • greetd serviceConfig:Type = "idle"、tty 相关设置

15. system/nix-ld.nix(新增)

作用:nix-ld 兼容动态链接器,让非 Nix 二进制(AppImage 解压、.deb 解压的程序,如富途 futu、longbridge 等)通过 nix-ld 加载器找到系统库。

关键内容:

  • programs.nix-ld.enable = true
  • libraries:一整套 Electron/CEF(gtk3、glib、pango、cairo、harfbuzz、atk、gdk-pixbuf、fontconfig、freetype...)、媒体栈(libbsd、libgcrypt、librsvg、nss、cups、libdrm、mesa...)、X11/Qt(libx11~libxtst、xcbutil*、libsm、libice、dbus...)、通用基础(stdenv.cc.cc.lib、zlib、curl、openssl、icu、libGL)
  • ⚠️ 自定义 jpeg-8(libjpeg.so.8 旧 ABI):nixpkgs 的 libjpeg(turbo) 只提供 .62,libmpv 等旧库需要 .8,用 fetchurl 从 ijg.org 编译 jpegsrc.v8d 提供
  • 缺库报错时往 libraries 里按需补充

16. system/proxy/clash-verge.nix(主用)

作用:Clash Verge Rev(nixpkgs 官方模块 programs.clash-verge),GUI 客户端 + TUN/系统代理。

关键内容:

  • programs.clash-verge.enable = true
  • serviceMode = true:clash-verge-service 由 systemd 开机常驻(TUN 所需的特权核心)
  • tunMode = true:生成 security.wrappers.clash-verge,授予 cap_net_bind_service / cap_net_raw / cap_net_admin(TUN + DNS 所需),并把 firewall.checkReversePath 默认设为 "loose"
  • autoStart = true:生成 XDG autostart 条目,桌面登录自动启动 GUI
  • ⚠️ 单实例:GUI 必须在 设置 → 开启「服务模式」+「Tun 模式」以复用 service 核心;若未开「服务模式」,GUI 会另起一个核心(出现"两个 clash")

日常使用:

  1. super+d / 应用菜单打开 clash-verge
  2. 「订阅 → 新建 → 粘贴订阅 URL → 更新」,选中一个 profile
  3. 打开「系统代理」或 Tun 模式即可全局代理

切换回 mihomo:见 mihomo.nix 顶部注释(注释 clash-verge import、取消 mihomo import)。

17. system/proxy/mihomo.nix(备用)

作用:mihomo(Clash Meta,TUN 模式),备用方案。

  • services.mihomo.enable = true,configFile = "${myvars.homeDirectory}/.config/mihomo/config.yaml"(用户目录下,不在仓库内)
  • tunMode = true,webui = pkgs.metacubexd
  • systemd.services.mihomo.path = [ pkgs.mihomo ](恢复系统默认高权限沙箱以完美支持 TUN)
  • networking.firewall:checkReversePath = "loose"、trustedInterfaces = [ "Meta" ]、放行 TCP 9090/7890/7891
  • 已自包含防火墙规则,启用时需同步在 configuration.nix 移除 clash-verge import(反之亦然)

订阅链接管理(若启用):

  • 订阅链接在 ~/.config/mihomo/config.yaml 的 proxy-providers.mysub.url(含 token,属敏感信息,不进 git)
  • systemd.services.mihomo.path = [ pkgs.mihomo ] 恢复默认高权限沙箱(TUN 需要),mihomo 直接读用户目录的 config.yaml
  • 每月更换订阅:编辑该文件 url → systemctl restart mihomo → curl http://127.0.0.1:9090/providers/proxies 验证
  • 只刷新订阅(不改配置):curl -X PUT "http://127.0.0.1:9090/providers/proxies/mysub"

18. system/packages.nix

作用:系统级软件包(所有用户可用)。

完整列表:

  • 基础工具:wget, curl, lazygit, nh, jq, socat, tree, ripgrep, fd, bat, eza, yazi (git 由 home/programs/git.nix 安装,避免双装)
  • 终端:fzf, zoxide (alacritty/tmux/starship/direnv 由 home 模块安装,避免双装)
  • 压缩解压:zip, unzip, p7zip, rar, dtrx
  • Nix 开发工具:nil, alejandra, statix, deadnix, nix-tree, nix-output-monitor, sops, age
  • 编译工具:gcc, gnumake
  • Wayland / Niri:xwayland, xwayland-satellite, wl-clipboard(⚠️ 截图已改用 niri 内置,grim/slurp/wl-clip-persist 已移除)
  • 硬件检测:pciutils, ddcutil
  • 文件系统:btrfs-progs, ntfs3g
  • 网络兼容:wsdd
  • Android:android-tools(adb)
  • AppImage:appimage-run(部分 AppImage 如 longbridge 依赖系统库,沙箱里没有,需 nix-ld 直跑,见 system/nix-ld.nix)
  • Secret:libsecret
  • 系统控制:playerctl, brightnessctl, libnotify
  • 编辑器:vim, gnome-text-editor

19. system/nvidia/nvidia-block.nix(enableNvidia = false 时启用,屏蔽独显)

作用:屏蔽 NVIDIA 独显以省电(仅用 AMD iGPU)。

  • boot.extraModprobeConfig:blacklist nouveau
  • services.udev.extraRules:移除 NVIDIA USB/音频/VGA 设备(power control)
  • boot.blacklistedKernelModules = [ "nouveau" "nvidia" "nvidia_drm" "nvidia_modeset" ]

20. system/nvidia/nvidia.nix(当前启用:enableNvidia = true)

作用:启用 NVIDIA RTX 3050 Ti Mobile 独显(PRIME offload 省电方案,闲置自动断电)。

  • hardware.graphics.enable = true
  • 内核模块 nvidia_modeset/nvidia_drm/nvidia,blacklist nouveau
  • services.xserver = { enable = true; videoDrivers = [ "nvidia" ] }(XWayland 也走此驱动)
  • hardware.nvidia:modesetting、powerManagement.enable = true(suspend 保存 VRAM,防唤醒花屏)、powerManagement.finegrained = true(RTD3 空闲进入 D3cold 断电)、open = true(开源内核模块,595 驱动已稳定)、nvidiaSettings = true、package = linuxPackages_latest.nvidiaPackages.stable
  • hardware.nvidia.prime.offload.enable = true(按需渲染),amdgpuBusId = "PCI:6:0:0",nvidiaBusId = "PCI:1:0:0"
  • ⚠️ 启用方法:vars/default.nix 的 enableNvidia 为 true 即启用本模块(当前值);改为 false 则由 nvidia-block.nix 接管,两者由该开关自动二选一,无需改 imports

21. vars/default.nix(新增)

作用:集中管理用户/仓库变量,经 specialArgs 以 myvars 注入所有模块。

内容:

  • username = "lilei"、userfullname = "lilei"、useremail = "lilei0918@gmail.com"
  • homeDirectory = "/home/lilei"
  • repoDir = "/home/lilei/nixos-DMS"
  • flakeName = "legion"
  • enableNvidia = true:独显开关(true 启用 NVIDIA offload + RTD3,当前值;false 屏蔽独显走核显省电)
  • theme:GTK/Qt/光标主题统一取值(gtk/icon/cursor/cursorSize),见 theme.nix、dconf.nix、niri settings.nix

任何需要硬编码用户名/路径的地方,优先用 myvars.xxx 而不是写死字符串(fish/zsh 别名、mihomo configFile、thunar、firefox profile 等已改用)。

22. tests/(新增)

作用:flake 求值测试,nix flake check 自动运行(经 checks.evalTestsCheck 强制求值,失败即抛错)。

结构:每个测试子目录 tests/<name>/ 下有 expr.nix + expected.nix,tests/default.nix 自动发现并断言二者相等。

现有测试:home-directory(home.homeDirectory == /home/lilei)、state-version、timezone(Asia/Shanghai)、user-is-normal、proxy-mutex(clash-verge 开 / mihomo 关)、firefox-disabled、hm-state-version。

新增测试:在 tests/ 建目录,expr.nix 引用 outputs.nixosConfigurations.legion.config...,expected.nix 给出期望值。

23. hosts/legion/home.nix

作用:Home Manager 入口文件。

关键内容:

  • home.username = myvars.username,home.homeDirectory = myvars.homeDirectory,home.stateVersion = "25.05"
  • imports 列表包含:
    • ../../home/niri/kdl.nix(niri 手写 KDL 配置链接)
    • ../../home/programs/rime.nix、AI/vscode.nix、chrome.nix、dev.nix、elyoffice.nix、walker.nix、thunar.nix、theme.nix、dconf.nix、fastfetch.nix、git.nix、btop.nix、AI/zed.nix、AI/opencode.nix、AI/pi.nix (firefox.nix 保留在仓库但当前未导入,需要时取消注释)
    • ../../home/terminal/alacritty.nix、fish.nix、starship.nix、tmux.nix、ghostty.nix、zsh.nix
  • niri:⚠️ 已放弃 niri-flake(2026-08-30 改)。niri 用 nixpkgs 自带 programs.niri(system/niri.nix,pkgs.niri 26.04,支持 include);配置为手写 KDL(home/niri/conf/*.kdl,经 home/niri/kdl.nix 链接到 ~/.config/niri/)。主 config.kdl 用 include 引入 theme.kdl(配色为原 DMS 主题的静态快照)+ Noctalia 集成设置。
  • home.packages = lib.mkBefore allPackages(allPackages 来自 ./packages.nix)
  • Fcitx5/Rime 用户配置:
    • home.file."~/.local/share/fcitx5/rime/default.custom.yaml"(声明在 home/programs/rime.nix,非 home.nix):schema rime_ice,page_size: 9
    • xdg.configFile."fcitx5/profile":默认输入法 rime
    • fcitx 环境变量(GTK_IM_MODULE / QT_IM_MODULE / QT_IM_MODULES / XMODIFIERS / SDL_IM_MODULE)统一在 home/programs/rime.nix(sessionVariables)声明,niri 会话不再重复声明(见 home/niri/conf/config.kdl 注释)
  • home.sessionVariables:EDITOR=vim
  • programs.direnv:启用,nix-direnv.enable = true
  • programs.home-manager.enable = true

24. hosts/legion/packages.nix

作用:用户级软件包列表(仅 lilei 可用)。

完整列表:

  • 办公/阅读:libreoffice, foliate, loupe, zathura, zettlr, papers, readest, marktext(thunderbird 已注释,未启用)
  • 金融:tradingview(已注释,未启用)
  • 通讯:qq, telegram-desktop
  • 桌面配置:nwg-look, apple-cursor, waypaper, dconf-editor, matugen, qt6Packages.qt6ct
  • 文件管理:file-roller, xz, localsend, duf
  • 音频/视频:pavucontrol, mpv, gpu-screen-recorder, blanket
  • 音乐:spicetify-cli(已注释,未启用)
  • 笔记:siyuan
  • 图片:imagemagick(已注释,未启用)

26. system/vault/vault.nix(加密数据盘)

作用:管理 20G LUKS 加密盘(ZHITAI 盘 p3,LUKS UUID 86c742fc-8de5-4c59-9a30-196484a35695),作为密码库 + 个人敏感文件存储。手动按需解锁,开机不自动挂载。

关键内容:

  • systemd.tmpfiles.rules 常驻创建挂载点 /mnt/vault(加密卷关闭时也保留,便于 mountpoint 判断)
  • vault-open(writeShellApplication,root):cryptsetup status 未开 → cryptsetup open "UUID=86c742fc-8de5-4c59-9a30-196484a35695" vault → mount /dev/mapper/vault /mnt/vault,幂等(已开/已挂载则跳过)
  • vault-close:先 umount 再 cryptsetup close vault
  • runtimeInputs = cryptsetup + util-linux;用 LUKS UUID 而非设备路径,防设备号漂移

使用:

  • 开:sudo vault-open;关:sudo vault-close
  • 解锁后 /mnt/vault 是普通 ext4 目录,Thunar 可像普通盘一样复制粘贴管理
  • 盘内目录结构:vaultwarden/backups/(备份归档)、passwords/、recovery/、crypto/、ssh/、documents/,详见盘中 /mnt/vault/README.md

27. system/vault/vaultwarden.nix

作用:自托管密码管理器(Vaultwarden = Bitwarden 服务端),通过 Podman 容器 + Quadlet 管理,SQLite 存储。

关键内容:

  • virtualisation.podman.enable = true(Quadlet generator 随 podman 打包,/etc/containers/systemd/*.container 自动转 systemd 服务);dockerCompat = false,defaultNetwork.settings.dns_enabled = false
  • systemd.timers.podman-auto-update.wantedBy = ["timers.target"]:启用 podman 自带的自动更新 timer(配合容器 AutoUpdate=registry)
  • 容器 docker.io/vaultwarden/server:latest,AutoUpdate=registry
  • 数据持久化:/var/lib/vaultwarden(宿主机)↔ /data(容器),SQLite 数据库即 db.sqlite3
  • 仅本机访问:PublishPort=127.0.0.1:8080:80
  • 强制 HTTPS:⚠️ Bitwarden 新版 web vault 拒绝所有 http:// 请求(含 localhost)。本地 CA + localhost 证书(SAN 含 DNS:localhost,IP:127.0.0.1)由 sops 加密存储(secrets.yaml 的 vaultwarden_tls_*),boot 时 sops-nix 解密写入 /var/lib/vaultwarden/tls(0700 root);Quadlet 用 After=sops-nix.service 确保容器在解密后启动,TLS 证书以 bind mount 逐文件挂载(sops 的 path 是符号链接,容器命名空间里没有 /run/secrets,需挂真实文件)。CA 公钥提交在仓库 system/vault/certs/vaultwarden-ca.crt,经 security.pki.certificateFiles 写入系统信任。证书稳定,rebuild 不轮换
  • 访问地址:https://localhost:8080(不是 http)
  • 管理后台:https://localhost:8080/admin,密码为 sops 加密的 vaultwarden_admin_token(经 sops.templates."vaultwarden-env" 注入 ADMIN_TOKEN)
  • Environment:DOMAIN=https://localhost:8080、ROCKET_PORT=80、ROCKET_TLS=...、SIGNUPS_ALLOWED=false(注册已关闭)、WEBSOCKET_ENABLED=true
  • 容器 TimeoutStopSec=60(SQLite WAL checkpoint 需要优雅关闭,全局 10s 可能不够)
  • 系统包补充:podman、podman-compose

使用注意事项:

  • 若要开放注册:临时把 SIGNUPS_ALLOWED 改为 true → rebuild/重启容器 → 注册完改回 false
  • 浏览器端:Chrome 用扩展或直接访问 web 界面(Firefox 当前未启用;启用后 firefox.nix 已配好 bitwarden 扩展)
  • 证书由 sops 管理,rebuild 不更换;要换证书:更新 secrets.yaml 的 vaultwarden_tls_*(并同步仓库 certs/vaultwarden-ca.crt 的公钥)→ rebuild → 重启容器
  • security.enterprise_roots.enabled = true 已加入 firefox.nix(当前未导入,启用 Firefox 后生效),让 Firefox 使用系统根证书

28. system/vault/vaultwarden-backup.nix

作用:Vaultwarden 数据库每日在线备份(三层)。⚠️ Vaultwarden 新版已移除内置备份(BACKUP_* 变量无效),故用 sqlite3 .backup 在线备份(WAL 安全)。原异盘同步目标(Arch btrfs 分区,UUID 9dccd22a-…)于 2026-09 随 Arch 删除;同一槽位后于 2026-10 重建为 Immich 库(UUID 5c0e846a-…),镜像改落本机数据盘 DATATB。

三层备份:

  1. 本地:sqlite3 .backup → /var/lib/vaultwarden/backups/backup-*.db(保留 7 天;生成后跑 PRAGMA integrity_check,校验失败的文件直接删除并让本次备份失败,避免留坏档)
  2. DATATB 镜像:rsync --delete → /run/media/lilei/DATATB/vaultwarden-backup/(ntfs3 自动挂载数据盘,与本地同滚动 7 天)
  3. 加密盘(按需,长期归档):检测 [ -b /dev/mapper/vault ] && mountpoint -q /mnt/vault,已解锁则 rsync(只增不删)到 /mnt/vault/vaultwarden/backups/;未解锁自动跳过并留日志

使用:

  • 手动触发一次:sudo systemctl start vaultwarden-backup
  • ⚠️ 本地 / DATATB / 加密盘分属 ZHITAI 盘上不同分区、同一块物理盘,只有分区与文件系统级冗余,无整盘容灾;长期归档请定期外导(U 盘等离线介质)再保一份(习惯同 scripts/backup-credentials.sh)

29. system/immich.nix(照片库)

作用:自托管照片/视频管理(Immich),用 nixpkgs 原生模块 services.immich(自带 PostgreSQL + Redis + 机器学习,无需容器)。当前启用局域网访问(host = "" 监听所有接口 + openFirewall = true 放行 2283);远程访问以后再经 Tailscale 追加。

关键内容:

  • services.immich:enable = true、host = ""、port = 2283、openFirewall = true、mediaLocation = "/srv/immich"、accelerationDevices = ["/dev/dri/renderD128"](AMD Vega 核显硬件转码)
  • 数据分布:数据库/缓存/缩略图元数据在 /var/lib/immich(根 btrfs);托管库(手机上传/Immich 管理的文件)在 /srv/immich
  • 托管库必须在 Linux 文件系统(btrfs/ext4),不能用 NTFS(属主/权限/大小写不兼容);NTFS 上的既有照片无需搬移,可作「外部库」原地只读索引(见下)
  • 独立分区:SK Hynix 盘 p7(原 Arch 根分区释放的空间,324.94 GiB)用 cfdisk 新建 btrfs(标签 IMMICH,UUID 5c0e846a-…),挂载用 by-label/IMMICH(设备名会漂移)。一次性创建命令见 system/immich.nix 文件头注释。不建此分区也可先跑(用默认 /var/lib/immich)。
  • 默认注册开放,首次访问 http://<NixOS 局域网 IP>:2283 注册管理员后可在网页端关闭注册
  • ⚠️ 照片库在 SK Hynix 盘(Windows 盘) 上,与系统盘(ZHITAI)物理分离,天然异盘;仍建议定期外导备份

30. system/tailscale.nix(远程访问,预留,当前未导入)

作用:Tailscale 尾网,实现办公室远程访问家庭 NixOS 服务。家里宽带多为 CGNAT 无公网 IPv4,Tailscale 打洞/中继,无需端口映射。当前只做局域网,需要远程时再在 configuration.nix 取消该 import 注释。

关键内容:

  • services.tailscale.enable = true、networking.firewall.trustedInterfaces = ["tailscale0"]
  • 一次性初始化(交互式登录,状态写入 /var/lib/tailscale,重启保留):
    sudo tailscale up
    # Tailscale 管理后台开启 MagicDNS + HTTPS Certificates
    sudo tailscale serve --bg --https=443 http://localhost:2283
  • 访问:https://<主机名>.<tailnet>.ts.net(Tailscale 颁发有效证书,手机 Immich App 可直接用)
  • 无人值守登录:在 secrets 加 tailscale_auth_key,设 services.tailscale.authKeyFile(未配置则用交互式登录)
  • ⚠️ 必须配合 clash-verge 的 Tailscale 直连规则(见「十二」注意事项),否则 TUN 会劫持尾网流量/DNS
  • 注:host = "" 时,远程经 tailscale serve 代理到 localhost:2283 仍可用

31. system/immich-backup.nix(Immich 每日备份)

范围:只备份数据库(相册 / 人物 / 时间线等元数据)。媒体原图不镜像(2026-11 起,省空间)—— 照片/视频只有 /srv/immich 一份,单盘损坏即丢失;需要异盘副本时把模块里媒体 rsync 的注释打开。

作用:新版 Immich 无内置备份,用 systemd oneshot + 每日 timer 备份数据库,异盘落两份抗单盘损坏。

关键内容:

  • 数据库:runuser -u postgres -- pg_dumpall --clean --if-exists | gzip → /srv/immich/backups/db/immich-db-<时间>.sql.gz(落在 SK Hynix 盘,与 DB 所在的 ZHITAI 根分区异盘),保留 14 天
  • 媒体:❌ 不再镜像(原 DATATB/immich-backup/media/ 已弃用,可删);upload/ 只有本机一份
  • 数据库 dump 另存一份到 DATATB/immich-backup/db/(异盘,约 2.9 GiB / 12 份滚动)
  • 触发:sudo systemctl start immich-backup;timer 每日 04:30(Persistent 补跑)
  • ⚠️ 备份前 RequiresMountsFor=/srv/immich,未挂载则跳过(防写到根盘空目录)
  • ⚠️ 升级 Immich 前先备份(DB 迁移单向);恢复须用相同/更新版本
  • ⚠️ 两份备份同机不同盘,整机故障仍需定期外导(U 盘)

32. system/immich-deduper.nix(重复照片清理,按需启动)

作用:用上游 immich-deduper(ResNet152 视觉相似度)找重复照片并清理;不常驻,需要时手动启停。删除只把 asset.status 改成 trashed,照片进 Immich 回收站可恢复。

关键内容:

  • 不随系统启动:systemd.services.immich-deduper.wantedBy = [],只有 sudo systemctl start immich-deduper 才运行;stop 后容器与网络一起清理,数据目录保留
  • rootful podman:/srv/immich 是 0700 immich:immich,rootless 读不到缩略图
  • 免密码连库:容器用 --user <immich uid>:<gid> 运行,PostgreSQL 的 local all all peer 直接认作 role immich;不需要给角色设密码、也不暴露 5432
  • 媒体路径同路径挂载(/srv/immich:/srv/immich:ro):podman 无 /.dockerenv,Deduper 判 IS_DOCKER=false,不会重映射成 /immich
  • 只监听本机:-p 127.0.0.1:8086:8086,不进防火墙
  • 镜像固定 razgrizhsu/immich-deduper:0.3.5(CPU;AMD 核显不支持,上游只有 NVIDIA CUDA 变体)+ qdrant/qdrant:v1.17.1
  • 数据:/var/lib/immich-deduper/{data,qdrant}(data 属主 immich、组 users,lilei 可读日志)
  • 首次启动会拉约 2 GB 镜像,并下载 ResNet152 权重约 250 MB;TimeoutStartSec = 0 避免拉取超时
  • ⚠️ 40k 资产的向量化在 CPU 上可能数小时;可以先缩小范围(NameFilter/Path Filter)

33. system/immich-power-tools.nix(批量整理 Web UI,按需启动)

作用:上游 immich-power-tools(非官方客户端)提供批量人物/相册整理、缺失位置、潜在相册、统计、Smart Search、批量日期偏移。不常驻,需要时启停。

关键内容:

  • 不随系统启动:wantedBy = [];sudo systemctl start immich-power-tools 才运行,stop 后容器清理,数据保留
  • 数据两条通道:读库走 PostgreSQL unix socket(容器以 immich uid 运行 → peer 认证,不设密码/不开 5432);写操作走 Immich HTTP API(http://127.0.0.1:2283)
  • DB 参数用显式 DB_HOST=/run/postgresql + DB_USERNAME=immich:绕过上游「DB_PASSWORD 不能为空」的校验(占位值在 peer 认证下被忽略)
  • 只监听 127.0.0.1:8001(HOSTNAME=127.0.0.1 + PORT=8001),不暴露局域网
  • 镜像固定 ghcr.io/immich-power-tools/immich-power-tools:0.25.0(Immich ≥3.0 需 ≥0.22.0)
  • 密钥不落仓库:/var/lib/immich-power-tools/power-tools.env(root 0600,首次启动自动生成模板 + 随机 JWT_SECRET);IMMICH_API_KEY 需在 Immich 里创建(全权限)后填入
  • 数据:/var/lib/immich-power-tools/{data,cache}(data/app.db 是它自己的 SQLite;cache 给 Next.js 图片缓存)
  • 可选:AI_API_KEY/AI_BASE_URL/AI_MODEL 写入同一 env 文件即可启用 Smart Search 的自然语言解析

六、Niri 配置详解(home/niri/)

⚠️ 架构(2026-08-30 改):放弃 niri-flake 属性集,改用手写 KDL(参照 ryan4yin/nix-config 风格)。 niri 版本来自 nixpkgs pkgs.niri(system/niri.nix,26.04,支持 include)。 home/niri/kdl.nix(HM 模块)把 conf/*.kdl 链接到 ~/.config/niri/。

conf/config.kdl(主配置)

  • 顶部 include 分片:./keybindings.kdl、./windowrules.kdl、./spawn-at-startup.kdl、./theme.kdl
  • 主题/集成:include "./theme.kdl" —— 冻结的配色(原 DMS 主题)+ Noctalia 的 layer-rule / debug 设置
  • 工作区:workspace "browser" / "note" / "code"(open-on-workspace 需先声明)
  • prefer-no-csd(禁用客户端装饰)
  • 布局:背景透明(Noctalia 壁纸层放进 backdrop)、focus-ring/border width 2、颜色 theme.kdl 固定、预设列宽 25/50/75/100%、默认 75%、gaps 4、struts 8/8/1/1
  • 输入:键盘 us + numlock;触控板(tap、natural-scroll、two-finger、button-areas、middle-emulation、accel-profile adaptive);focus-follows-mouse、workspace-auto-back-and-forth
  • 输出:eDP-2 1920×1080 @ 165.004Hz scale 1.0;DP-2 2560×1600 @ 60.001Hz scale 1.25(外接屏物理位于内屏正上方)
  • 光标:size 24、hide-when-typing、hide-after-inactive-ms = 1000
  • 环境变量:Wayland 全家桶(GDK/QT/MOZ/ELECTRON)、XDG_SESSION_TYPE / XDG_CURRENT_DESKTOP

conf/keybindings.kdl(快捷键)

按键 动作
super+q 关闭窗口
super+f / super+shift+f 全屏 / 最大化列
super+t 切换浮动
super+h 居中当前列
super+c / super+v 未绑定(保留给终端内复制 / 粘贴,见下方 alacritty / ghostty)
super+tab 切换到上一个工作区
super+1..4 列宽 25/50/75/100%
super+return alacritty
super+shift+return ghostty
super+d walker(启动器,spawn-at-startup 已常驻,唤出秒开)
super+space Noctalia 启动器(noctalia msg panel-toggle launcher)
super+s Noctalia 控制中心
super+shift+comma Noctalia 设置
Alt+Tab Noctalia 窗口切换器
XF86Audio* / XF86MonBrightness* 音量 / 亮度(走 Noctalia IPC)
super+e thunar
super+b google-chrome
Print niri 内置截图(保存当前工作区到 ~/Pictures/Screenshots/)
Alt+Print 截图窗口
Ctrl+Print 截图全屏
Mod+P 截图(等同 Print)

conf/windowrules.kdl(窗口规则)

  • 通用圆角:10 / 10 / 5 / 5(左上/右上/左下/右下),clip-to-geometry true
  • Alacritty / Ghostty 固定列宽 800
  • 浏览器类(google-chrome/firefox)open-maximized,分配到 browser 工作区
  • 开发工具(Zed dev.zed.Zed / codium)占满列宽,分配到 code 工作区
  • 办公/编辑器(libreoffice/zettlr/gnome-text-editor)占满列宽
  • 浮动类:FileRoller、pavucontrol、Blanket、LocalSend、dconf-editor、waypaper、nwg-look、qt6ct、Loupe、zathura、Foliate、telegram
  • QQ(app-id QQ)浮动 + 固定列宽 800(独立规则 6.1)
  • 终端类(Alacritty/Ghostty)与 mpv 均浮动、不分配工作区
  • 弹窗类居中浮动(Open File/Save File)
  • 画中画(Firefox PiP)右下角浮动 480×270
  • SiYuan(app-id org.b3log.siyuan)→ note 工作区 + 独占一列 100%
  • thunar(app-id [Tt]hunar)浮动 + 1200×800;重命名对话框(标题含 Rename/重命名)420×180 小浮动(规则 11.1 覆盖)

conf/spawn-at-startup.kdl(自启动)

  • polkit-gnome-authentication-agent-1(权限代理)
  • fcitx5 -d(输入法)
  • blueman-applet(蓝牙托盘)
  • walker --gapplication-service(walker 常驻服务:GTK4 冷启动 2-3s,service 常驻后 super+d 唤出仅 ~0.1s)
  • sleep 10 && exec qq(延迟启动 QQ)
  • ⚠️ XWayland:niri 25.08 起内置集成(自动 spawn xwayland-satellite),无需手动

七、用户程序配置速查(home/programs/ 与 home/terminal/)

文件 内容要点
AI/zed.nix Zed 编辑器(nixpkgs zed-editor,二进制 zeditor)+ nil(Nix LSP)+ nixfmt:主题 Gruvbox Dark、图标扩展 icons-modern-material(Material 风格);TS/JS 用 typescript-language-server + 外部 prettier;三栏布局(左 Project / 中 Editor / 右 Agent)+ userKeymaps;ACP 链接 opencode(opencode acp,⚠️ 不是 serve)。API key/登录走 Zed keychain(不进 Nix)
AI/opencode.nix OpenCode AI agent(nixpkgs opencode):只装工具,凭据用 opencode auth login(切换 provider 无需改 Nix)
AI/pi.nix Pi coding agent(nixpkgs pi-coding-agent):只装工具,认证用 /login(自动写入 ~/.pi/agent/auth.json),自定义 provider 才需 ~/.pi/agent/models.json
alacritty.nix JetBrainsMono Nerd Font 12、Monokai Pro 配色、shell=fish、Super+C/V 复制粘贴、WINIT_UNIX_BACKEND=wayland
ghostty.nix monokai-pro 主题(自定义 palette)、JetBrainsMono 12、无装饰、GTK tabs bottom、Super+C/V 复制粘贴(ignore 掉默认 ctrl+shift+c/v)
fish.nix Nix 别名用绝对路径(rebuild/nix-test/boot/rollback/cleanup/check/update/fmt,任意目录可用)、g* git 别名、ls=eza 等、starship/direnv/zoxide/fzf、fzf-fish 插件、目录快捷 alias
zsh.nix oh-my-zsh(git/sudo/colored-man-pages/extract)、syntaxHighlighting、历史 10 万、同名 Nix 别名(rebuild/test/boot/rollback/cleanup/check/update/fmt,绝对路径)、cd=z
starship.nix 极简 format(user/host/dir/git/cmd_duration/❯)
tmux.nix mouse、history 10 万、vi 模式键、escape-time 0
chrome.nix nixpkgs wrapper 不读 chrome-flags.conf,包本体 + Wayland/GPU 启动参数经 commandLineArgs 注入(含 --enable-wayland-ime --wayland-text-input-version=3)+ 环境变量:LIBVA_DRIVER_NAME=radeonsi、VAAPI 相关(原在 hosts/legion/packages.nix)
firefox.nix NUR 扩展(bitwarden/darkreader/sponsorblock)、隐私设置、搜索引擎(searxng/nix-packages/nixos-wiki/ddg,默认 ddg)、security.enterprise_roots.enabled=true(信任系统根证书,配合 Vaultwarden 本地 CA);⚠️ 当前未导入 home.nix,保留备用
git.nix user 信息走 myvars(lilei/lilei0918@gmail.com)、lfs、delta(Catppuccin Mocha、side-by-side)、别名 st/co/br/lg
elyoffice.nix ElyOffice 0.1.11 七件套(doc/table/show/pdf/mail/tree/mark),包来自 flake input elyoffice(github:ELY-Open-Source/ElyOffice,nixpkgs.follows = "nixpkgs");上游用 appimageTools.wrapType2 包成 FHS+bwrap,store 增量约 2.75 GiB(doc/show/table 各约 700 MiB);升级随每周 update(nix flake update)自动跟随上游 main;⚠️ 上游仍用已弃用的 extractType2(求值有 warning),nixpkgs 移除该函数后需跟进
theme.nix GTK3 WhiteSur-Dark + WhiteSur 图标 + macOS-White 光标(含 home.pointerCursor);GTK4 用系统默认(gtk4.theme = null);Qt 走 gtk3;sessionVariables:GTK_APPLICATION_PREFER_DARK_THEME=1、XCURSOR_THEME/SIZE、QT_QPA_PLATFORMTHEME=gtk3(已删掉破坏 GTK4 的 GTK_THEME)
dconf.nix gnome 桌面 WhiteSur 主题、Nerd Font 10 等宽字体
thunar.nix thunar + xfconf(必需)+ volman/archive/media-tags 插件、默认文件管理器(xdg.mimeApps)。默认显示隐藏文件、按名称升序且文件夹在前(misc-folders-first)、force = true(xfconf 改写文件破坏符号链接)。生效后需重启 Thunar(killall Thunar)
walker.nix walker + elephant(剪贴板依赖,systemd user service,graphical-session.target 后启动);walker 本体由 niri spawn-at-startup 以 --gapplication-service 常驻,super+d 秒开
AI/vscode.nix VSCodium:nix-ide、gitlens、material-icon、markdown-all-in-one、yaml、code-spell-checker(Nix LSP 统一用 nixd)。主题 Gruvbox Dark Medium。⚙️ Nix 格式化走 nixd:nix.serverSettings.nixd.formatting.command = ["alejandra"]。redhat.telemetry.enabled=false
btop.nix presets、TTY 配色、desktop entry(ghostty -e btop)
fastfetch.nix FastCat Small-Themes/Simple 主题(无 logo、图标+RGB 配色、⌲ 分隔,来源见文件头)
rime.nix rime-ice(锁定 commit 8a3d9470,声明式 home.file 管理)+ librime/librime-lua;fcitx 环境变量(GTK/QT/XMODIFIERS/SDL_IM_MODULE)统一在此管理。⚠️ rebuild/重启后若雾凇未出现,手动运行 fcitx5-remote -r 触发部署(详见文件头注释)

八、软件添加规范

1. 系统级软件(所有用户可用)

  • 在 system/packages.nix 的 environment.systemPackages 中添加。
  • 或者创建 system/<name>.nix(或相关主题目录,如 system/nvidia/、system/vault/、system/proxy/)并在 configuration.nix 的 imports 中引用。
  • 重建:sudo nixos-rebuild switch --flake .#legion(或 nh os switch .#legion,nh 会自动提权,不要加 sudo)

2. 用户级软件(仅 lilei)

  • 在 home/programs/ 下创建 <name>.nix,内容通常为 { pkgs, ... }: { home.packages = [ pkgs.<name> ]; } 或使用特定模块(如 programs.git.enable = true)。
  • 然后在 hosts/legion/home.nix 的 imports 中添加 ../../home/programs/<name>.nix。
  • 也可直接在 home.nix 的 home.packages 中添加,但推荐模块化。
  • ⚠️ 注意:新模块如果引用 flake input(如 inputs.xxx),必须先在 flake.nix 中添加对应 input,否则构建失败。
  • 用户/路径等重复出现的值,优先用 vars/default.nix 的 myvars 而非写死字符串。

3. 添加新服务

  • 在 system/services.nix 中添加相应的 services.<name>.enable = true 及配置。
  • 如需环境变量,使用 sops 模板(如 sops.templates."<name>-env")并设置 environmentFiles。

4. 添加新机密

  • 在 system/secrets.nix 的 secrets 属性集中声明新密钥(如 new_key = {};)。
  • 运行 sops secrets/secrets.yaml 添加对应条目(明文输入,保存后自动加密)。
  • 在需要的地方使用 config.sops.placeholder."new_key" 或 config.sops.secrets."new_key".path。

5. 添加新测试

  • 在 tests/<name>/ 建 expr.nix + expected.nix(expr 取配置实际值,expected 给期望值),tests/default.nix 自动发现,nix flake check 自动校验。

九、系统更新与回滚

日常更新流程

  1. 保存当前状态:git add . && git commit -m "before update"
  2. 更新 flake 锁:nix flake update(或只更新某个 input:nix flake lock --update-input <name>)
  3. 测试构建(不切换):sudo nixos-rebuild test --flake .#legion(或 nh os test .#legion)
  4. 校验:nix flake check(跑 eval 测试 + pre-commit 的 alejandra/typos 检查)
  5. 若测试通过,正式切换:sudo nixos-rebuild switch --flake .#legion(或 nh os switch .#legion)
  6. 提交锁文件:git add flake.lock && git commit -m "update inputs"

回滚

  • 回滚到上一个 generation:sudo nixos-rebuild switch --rollback
  • 或在启动时从 GRUB 菜单选择旧 generation。

垃圾清理

  • 删除所有旧 generation:sudo nix-collect-garbage -d
  • 查看占用:nix store gc --dry-run
  • fish/zsh 别名:cleanup(保留 14 天);系统 GC 自动每日清理 7 天前 generation

特别注意(多系统引导)

主引导是 p6 上的 NixOS GRUB,Windows(p1 独立 ESP)经 GRUB 菜单进入。NVRAM 引导项编号(0004/0007…)由固件动态分配,禁止在配置或脚本里硬编码,一切以 efibootmgr -v 实测为准。

  • 正常状态(2026-09-05 实测)BootOrder ≈ 0007 NixOS-boot-efi(GRUB)→ 0004 Windows Boot Manager → 硬驱/USB/网络回退项。
  • 调整顺序用 efibootmgr(本机未常驻安装,临时调用):sudo nix run nixpkgs#efibootmgr -- -o <grub编号>,<windows编号>,…。
  • 切换历史:从 systemd-boot 迁到 GRUB 时,曾删除指向旧 systemd-boot 的 Linux Boot Manager/Fallback Linux Boot Manager NVRAM 项并清理 p6 上的 EFI/systemd、EFI/nixos、loader/ 目录;EFI/BOOT/BOOTX64.EFI 现为 GRUB 副本(固件回退路径,NVRAM 丢失也能起)。
  • 若固件把 NixOS 项挪后或删掉:canTouchEfiVariables = true 会在下次 rebuild 自愈,必要时用 efibootmgr 把 NixOS-boot-efi 排回最前。

十、常用命令速查

日常备查的完整备忘录见 MEMO.md(按主题分 Nix / 加密盘 / Vaultwarden / sops / 代理 / 备份重装 / 排障)。

操作 命令
重建系统 sudo nixos-rebuild switch --flake .#legion、nh os switch .#legion 或 rebuild(fish/zsh 别名,绝对路径,任意目录可用)
仅测试 sudo nixos-rebuild test --flake .#legion、nh os test .#legion、nix-test(fish / zsh 同名)
以新 generation 启动 nh os boot .#legion 或 boot
回滚 sudo nixos-rebuild switch --rollback 或 rollback
校验配置 nix flake check(eval 测试 + pre-commit)
进入开发环境 nix develop(自动装 git pre-commit 钩子)
查看 generations sudo nixos-rebuild list-generations
查看当前系统包 nix-store -q --references /run/current-system/sw
查看用户包 home-manager packages
搜索包 nix search nixpkgs <pkg>
更新所有 inputs nix flake update 或 update(别名,绝对路径)
更新单个 input nix flake lock --update-input <name>
查看 flake 元数据 nix flake metadata
清理垃圾 sudo nix-collect-garbage -d 或 cleanup(保留 14 天)
格式化配置 alejandra . 或 fmt
编辑机密 sops secrets/secrets.yaml
截图 Print / Alt+Print / Ctrl+Print(niri 内置,保存到 ~/Pictures/Screenshots/)
Git 推送 git push
查看系统状态 fastfetch
查看当前内核版本 uname -r
查看 NixOS 版本 nixos-version
打开加密盘(解锁+挂载) sudo vault-open
关闭加密盘(卸载+锁) sudo vault-close
手动触发 Vaultwarden 备份 sudo systemctl start vaultwarden-backup
手动触发 Immich 数据库备份 sudo systemctl start immich-backup
清理 Immich 重复照片(按需,不常驻) sudo systemctl start immich-deduper → http://127.0.0.1:8086;用完 sudo systemctl stop immich-deduper
Immich 批量整理(按需,不常驻) sudo systemctl start immich-power-tools → http://127.0.0.1:8001;用完 sudo systemctl stop immich-power-tools
局域网访问 Immich http://<NixOS 局域网 IP>:2283(host="" + 放行 2283)
Immich 本机访问 http://localhost:2283
Tailscale 登录(首次,远程用) sudo tailscale up
Immich 经尾网出 HTTPS sudo tailscale serve --bg --https=443 http://localhost:2283
查看尾网状态 tailscale status
备份信任根/凭据 sudo bash scripts/backup-credentials.sh(到加密盘,默认保留 5 份)
查看加密盘状态 cryptsetup status vault、sudo cryptsetup luksUUID /dev/disk/by-uuid/86c742fc-8de5-4c59-9a30-196484a35695
运行非 Nix 二进制 直接运行解压后的 AppImage/.deb(nix-ld 提供系统库),或 appimage-run xxx.AppImage

十一、备忘

重装流程(恢复新机器)

  1. 迁移前:在旧机上解锁加密盘后备份信任根/凭据:sudo bash scripts/backup-credentials.sh(备份 sops age key ×2、~/.ssh/、opencode/pi/mihomo 凭据,完整源清单见 scripts/README.md)
  2. 分区(二选一):
    • disko 一键分区(推荐):在 NixOS 官方 ISO 中执行,只重建 ZHITAI 盘的 NixOS 分区(p2,btrfs 根分区),保留 DATATB 数据盘与加密盘:
      git clone https://github.com/lilei0918/nixos-DMS.git && cd nixos-DMS
      
      # 保留 DATATB + 加密盘:只格式化+挂载 btrfs 根分区(分区表已存在)
      nix run github:nix-community/disko -- --mode format,mount hosts/legion/disko-fs.nix
      # 全新空盘(重建整块 ZHITAI 盘分区表,DATATB/加密盘不保留):改用
      # nix run github:nix-community/disko -- --mode create,format,mount hosts/legion/disko-fs.nix
      # ⚠️ 不要用 --mode destroy(会销毁整块盘)
      
      # 挂载 NixOS EFI(SK Hynix 盘 p6,UUID AC09-EF5B;全新硬件需自行创建 EFI 分区并调整)
      mkdir -p /mnt/boot/efi
      mount /dev/disk/by-uuid/AC09-EF5B /mnt/boot/efi
    • 手动分区:参照 hosts/legion/hardware-configuration.nix(Btrfs 子卷 @/@home/@nix/@log、/tmp tmpfs、EFI)
  3. 放置 age 私钥(在安装前写入目标系统,供激活阶段解密密码 hash):
    mkdir -p /mnt/etc/sops/age
    cp /mnt/vault/credentials-backup/latest/etc-sops-age-keys.txt /mnt/etc/sops/age/keys.txt
    chmod 600 /mnt/etc/sops/age/keys.txt
  4. 安装(首次构建较慢;全新硬件需先 nixos-generate-config --root /mnt 并同步 hardware-configuration.nix):
    nixos-install --root /mnt --flake .#legion --no-root-password
    reboot
  5. 登录后 clone 仓库到 /home/lilei/nixos-DMS,放置 ~/.config/sops/age/keys.txt,恢复 ~/.ssh/ 与 opencode auth.json
  6. sudo nixos-rebuild switch --flake .#legion(或 rebuild)——密码 hash、Vaultwarden TLS 证书全部由 sops 自动解密生成,无需手动配置

未启用模块(保留但不导入)

  • system/nvidia/nvidia-block.nix:屏蔽独显配置(仅用核显省电),vars/default.nix 的 enableNvidia = false 时自动切换导入(与 nvidia.nix 二选一)。当前 enableNvidia = true,故本模块未启用。
  • system/proxy/mihomo.nix:mihomo 备用方案,启用时注释 clash-verge.nix 的 import(二选一,不可同时开启)。
  • home/programs/firefox.nix:Firefox 配置(home.nix 中 import 被注释),需要时取消注释启用。
  • system/tailscale.nix:远程访问(Tailscale),当前只做局域网,configuration.nix 中 import 被注释;需要时取消注释并 sudo tailscale up。
  • hosts/legion/packages.nix 中 thunderbird / tradingview / spicetify-cli / imagemagick(注释中)。

设计说明

  • 主机名 nixos ≠ flake 配置名 legion:所有 rebuild 命令用 .#legion;hostname 显示 nixos 属正常。
  • niri 工作区:settings.nix 用数字前缀 key(1-browser/2-note/3-code)+ name 声明三个命名工作区(rules.nix 的 open-on-workspace 需要它们),其余工作区按需动态创建。
  • mihomo 配置文件 ~/.config/mihomo/config.yaml 在用户目录(非仓库内),由 backup-credentials.sh 一并备份。
  • 自定义脚本放 ~/.local/bin(environment.localBinInPath = true 已加入 PATH),如 futu。

十二、关键注意事项

  1. 多系统引导:主引导为 NixOS GRUB(system/boot.nix),与 Windows 11(p1 独立 ESP)组成双系统菜单,NixOS generations 也在 GRUB 内选择;bootmgfw.efi 由 GRUB 每次开机动态搜索,Windows 更新后无需手动同步。
  2. Btrfs 子卷:系统使用 Btrfs 子卷布局(@, @home, @nix, @log),快照和回滚可基于此进行(当前未配置自动快照,但有 btrfs autoScrub)。
  3. 无交换分区:内存充足(32GB),因此未配置 swap。
  4. 显卡驱动:NVIDIA RTX 3050 Ti Mobile 独显已启用(vars/default.nix 的 enableNvidia = true,nvidia.nix:PRIME offload + RTD3,独显空闲自动断电),核显 amdgpu 负责输出;置 enableNvidia = false 则由 nvidia-block.nix 屏蔽独显、仅用核显省电。系统为纯 Wayland,未启用 services.xserver(X 应用走 xwayland-satellite),启用独显时会自动开启。
  5. 密码哈希:存于 secrets/secrets.yaml 的 password_hash(sops 加密,不落仓库明文)。修改:用 openssl passwd -6(或 mkpasswd -m sha-512)生成新 hash → sops secrets/secrets.yaml 更新该值 → rebuild。
  6. sops 私钥(信任根):/etc/sops/age/keys.txt(对应公钥 age14hwqm9aumaek4k6gn2zn8269ztzemgyvt8kqu4aq4lpxqtpl8uys5q42qn)必须备份,丢了它 secrets/secrets.yaml 永远解不开。已备份到 win11 数据盘和 qqmail。用户级解密还依赖 ~/.config/sops/age/keys.txt(跑 sops secrets/secrets.yaml 用),同样要备份。推荐直接用备份脚本(含上述两把 key + ~/.ssh/ + opencode auth.json):
    sudo vault-open                      # 若加密盘未解锁
    sudo bash scripts/backup-credentials.sh   # 备份到 /mnt/vault/credentials-backup
    手动备份命令(现在执行):
    sudo cp /etc/sops/age/keys.txt /mnt/vault/sops-age-keys.txt   # 或 U 盘等离线介质
    重装恢复命令(重装 NixOS 后、rebuild 前):
    sudo mkdir -p /etc/sops/age
    sudo cp /path/to/sops-age-keys.txt /etc/sops/age/keys.txt
    sudo chown root:root /etc/sops/age/keys.txt
    sudo chmod 600 /etc/sops/age/keys.txt
    恢复后路径必须是 /etc/sops/age/keys.txt(sops.age.keyFile 指向它),之后 rebuild 即全自动:密码 hash、Vaultwarden TLS 证书全部由 sops 解密生成,无需其它手动步骤。
  7. 镜像源:已配置 Tuna/USTC 镜像,更新速度较快。
  8. NixOS 版本:实际使用 nixpkgs unstable(具体版本 / commit 以 flake.lock 为准,nixos-version / nix flake metadata 可查),但 system.stateVersion 保留为 25.05 以确保兼容性。
  9. 用户组:lilei 加入 wheel / networkmanager / video / input 组。
  10. 机密文件:secrets/secrets.yaml 已加密,可以提交到 GitHub,但 age 私钥绝不可提交(已在 .gitignore 中忽略)。
  11. Rime 部署:rebuild/重启后若雾凇输入法未出现,手动运行 fcitx5-remote -r 触发部署(rime 目录由 home.file 声明式管理,部署懒触发)。详见 home/programs/rime.nix 头部注释。
  12. Vaultwarden 仅本机:服务只监听 127.0.0.1:8080,firewall 无需放行;访问必须用 https://localhost:8080(Bitwarden 客户端拒绝 http)。
  13. 注册已关闭:SIGNUPS_ALLOWED=false,需要开放注册时临时改回 true 并重建/重启容器,用完再关。
  14. Vaultwarden 数据备份:SQLite 数据在 /var/lib/vaultwarden/db.sqlite3,含全部密码(加密存储),备份该文件即备份整个保险库。
  15. Vaultwarden 证书:本地 CA + 证书位于 /var/lib/vaultwarden/tls/(0700 root),由 sops 解密生成(secrets.yaml 的 vaultwarden_tls_*),rebuild 不轮换;CA 公钥 system/vault/certs/vaultwarden-ca.crt 经 security.pki.certificateFiles 写入系统信任,浏览器零警告无需手动导入。换证书流程见「vaultwarden.nix」一节。
  16. 加密盘手动解锁:LUKS 加密盘(ZHITAI 盘 p3,UUID 86c742fc-8de5-4c59-9a30-196484a35695)开机不自动挂载,用 sudo vault-open / sudo vault-close 管理。解锁密码 = 全部数据的钥匙,丢失即永久丢失、无法找回,务必离线备份(纸质 / U 盘,参照 sops age key 的备份习惯)。
  17. 加密盘用 Thunar 管理:解锁挂载后 /mnt/vault 是普通 ext4 目录,可直接复制粘贴。不要用 udisks / GNOME Disks 解锁(会挂到动态路径 /run/media/...,破坏备份脚本对 /mnt/vault 的假设)。
  18. 加密盘备份策略:备份脚本的加密盘归档只在 vault 解锁时写入 /mnt/vault/vaultwarden/backups/(只增不删),未解锁自动跳过并留日志;镜像副本另有 DATATB /run/media/lilei/DATATB/vaultwarden-backup/(随本地 7 天滚动)。本地 / DATATB / 加密盘同属一块物理盘(ZHITAI),建议定期外导(U 盘等离线介质)再保一份。
  19. 字体(思源):系统字体主力为 Source Han 思源黑体/宋体/等宽 + Inter + JetBrainsMono NF;fonts.enableDefaultPackages = false,fontconfig 的 localConf 做了 ui-*/SF Pro/Noto CJK → 思源的映射,改动注意保持 fontconfig 完整 XML。
  20. nixpkgs:除 noctalia 外,所有 input 均 follows 统一 nixpkgs(nix flake update 可整体升级);noctalia 刻意独立(换取 Cachix 预编译缓存)。⚠️ niri 使用 nixpkgs 自带 pkgs.niri(见「六」)。
  21. nix-ld:非 Nix 二进制(富途 futu、longbridge 等)依赖系统库,靠 system/nix-ld.nix 提供;缺库按报错往 libraries 补。自定义 jpeg-8(libjpeg.so.8 旧 ABI)是手动编译的,勿删。
  22. 清理策略:journal 上限 200M(services.journald.settings.Journal);/tmp(4G)与 ~/.cache(6G)为 tmpfs(system/tmpfs.nix),重启即空;系统 GC 每日自动删 7 天前 generation。
  23. 截图:已用 niri 内置截图(Print/Alt+Print/Ctrl+Print),保存到 ~/Pictures/Screenshots/;grim/slurp/wl-clip-persist 已移除,旧文档中的 grim 命令不再适用。
  24. 提交前检查:nix flake check 会跑 eval 测试(tests/)和 pre-commit(alejandra --check + typos)。git commit 前确保 .nix 文件已 alejandra . 格式化,避免 typos 误报可改 .typos.toml。
  25. Immich:services.immich 为 nixpkgs 原生模块,当前局域网访问(host = "" + 放行 2283),首次访问 http://<NixOS 局域网 IP>:2283 注册。托管库(手机上传/Immich 管理的文件)放独立 btrfs 分区 /srv/immich(SK Hynix 盘 p7,标签 IMMICH,UUID 5c0e846a-…);NTFS 上的既有照片不必搬移,可在 Immich 后台「外部库」填 NTFS 挂载路径原地只读索引(当前 DATATB 挂载 umask=022 全局可读,immich 用户可读)。数据库/缓存/缩略图元数据在 /var/lib/immich。升级 Immich 前建议先备份。
  26. Tailscale + clash-verge 共存(重要):clash-verge 的 TUN 会劫持尾网流量与 DNS,已通过全局扩展配置放行,无需改订阅:
    • profiles/Merge.yaml:prepend-rules 加 100.64.0.0/10 与 *.tailscale.com/*.tailscale.io/*.ts.net 直连,并设 tun.route-exclude-address、dns.fake-ip-filter、nameserver-policy(+.ts.net → 100.100.100.100)。
    • profiles/Script.js:同规则(脚本对配置对象二次兜底)。
    • 这两文件在 ~/.local/share/io.github.clash-verge-rev.clash-verge-rev/profiles/(不在本仓库),订阅更新不会覆盖;改动后在 GUI 重载配置或重启 clash-verge 生效。
    • ⚠️ 若在 GUI 里改过「Tun/DNS 设置」,运行时 clash-verge.yaml 会重新生成;上面的 route-exclude / fake-ip-filter 语义仍由 Merge/Script 保证,如失效请在 GUI 对应项核对。
  27. Immich 备份(仅数据库):system/immich-backup.nix 每日 04:30 跑:DB pg_dumpall --clean → /srv/immich/backups/db/(保留 14 天,约 242 MiB/份,SK Hynix 盘)+ 镜像到 DATATB/immich-backup/db/(ZHITAI 盘,异盘)。媒体原图不镜像(DATATB/immich-backup/media/ 已弃用)——需要照片异盘副本时,把模块里媒体 rsync 循环的注释打开再 rebuild。升级 Immich 前先手动跑一次;恢复须用相同/更新版本。手动触发:sudo systemctl start immich-backup。

十三、常见问题排查

  • 开机直接进 Windows / 没有 GRUB 菜单:固件 BootOrder 把 Windows 排到了最前。sudo nix run nixpkgs#efibootmgr -v 查看项编号,用 sudo nix run nixpkgs#efibootmgr -- -o <NixOS-boot-efi编号>,<Windows编号>,… 把 GRUB 排回最前(canTouchEfiVariables = true 会在下次 rebuild 自愈 NVRAM 项)。
  • NixOS 重建后无法引导新 generation:确认 rebuild 成功且 /boot/efi/EFI/NixOS-boot-efi/grubx64.efi 存在;GRUB 配置写入 /boot/grub/grub.cfg(引用 /nix/store 内核路径)。GRUB 菜单里选旧 generation 可回滚,或 sudo nixos-rebuild switch --rollback。
  • 软件包未安装:确认添加到了正确的层级(系统 vs 用户),并检查是否在正确的 packages.nix 中。
  • Git 冲突:若从另一台机器修改并推送,拉取后需手动解决冲突,然后重建。
  • 构建失败(磁盘空间不足):运行 sudo nix-collect-garbage -d 清理旧 generation。
  • 启用模块报 input 不存在:该模块引用了 flake.nix 中未定义的 input,先添加 input 再启用。
  • Vaultwarden 打不开/报证书错:确认地址是 https://localhost:8080(非 http);Chrome 需完全关闭重开加载新 CA;检查容器 sudo systemctl restart vaultwarden.service。
  • Vaultwarden 登录提示 Invalid master password:先确认已注册账号(数据库 /var/lib/vaultwarden/db.sqlite3 的 users 表),再核对邮箱/密码;浏览器扩展的服务器地址填 https://localhost:8080。
  • vault-open / vault-close command not found:脚本在 legion 配置(system/vault/vault.nix)中,尚未部署或部署的是旧 generation。临时用 sudo nix-shell -p cryptsetup --run '...' 命令,或 nixos-rebuild switch --flake .#legion 后重试。
  • vault-close 报 target is busy:有程序正占用 /mnt/vault(通常是 Thunar/终端 cwd 在该目录),关掉窗口或 cd 离开后重试。可先 lsof +D /mnt/vault 查看占用进程。
  • 加密盘解锁提示 wrong passphrase / 无法打开:确认密码无误,且设备确实是对应分区(sudo cryptsetup luksUUID /dev/disk/by-uuid/86c742fc-8de5-4c59-9a30-196484a35695 应仍是 86c742fc-…)。密码是唯一钥匙,无法找回。
  • 非 Nix 二进制缺 .so 库:把缺失的库包(如 libxcb-*、qt6)加进 system/nix-ld.nix 的 libraries 后 rebuild。libjpeg.so.8 由自定义 jpeg-8 提供。

十四、给 AI 助手的特别说明

  • 此文档为静态知识库,AI 助手(opencode 等)应以当前信息为基础回答用户问题。
  • 当用户询问系统状态时,可参考"当前系统状态(快照)"部分,但动态值(如 uptime、generation 数)可能已变化,建议用户执行相应命令获取实时值。
  • 所有操作建议需考虑多系统环境和硬件限制。
  • 若用户要求添加/删除软件,应指明修改哪个文件,并提醒重建。
  • 若涉及机密,应提醒用户使用 sops 编辑 secrets/secrets.yaml,而不是直接写入明文。
  • 回答问题时,尽量引用具体的文件路径和配置示例。
  • 用户/路径等常量优先引用 vars/default.nix 的 myvars。
  • 行为规则见根目录 AGENTS.md;权限策略见 agents/permissions.md(含敏感文件 deny 清单)。
  • 各子目录的轻量 README.md 是文件索引与要点,先就地读取,需要细节再回看本文档对应章节。
  • 修改配置后应同步更新本文档(目录树、模块说明、已知问题)及各子目录 README.md。

文档版本:5.2 最后更新:2026-09-05 维护者:lilei(AI 助手协助整理,基于仓库实际文件通读核实)

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages