QOwnNotes 的 Nix 安装指南:NixOS / Linux / macOS 下的包管理、命令补全与密钥环配置
QOwnNotes 的 Nix 安装指南:NixOS / Linux / macOS 下的包管理、命令补全与密钥环配置
QOwnNotes 是一款纯文本笔记与待办事项管理器,支持 Markdown 与 Nextcloud / ownCloud 同步。本指南以 webpage/src/pl/installation/nix.md 的官方说明为主体,结合仓库内的 Nix 打包与源码实现,完整讲解如何通过 Nix 包管理器在 NixOS、其他 Linux 发行版、macOS 甚至 Windows 上安装 QOwnNotes,并深入说明其 Qt6 构建、shell 补全、命令行片段管理器 qc 以及桌面密钥环的配置与故障排查。读完本文,你将能在任意支持 Nix 的系统上以可复现的方式安装、验证并调优 QOwnNotes。
一、Nix 包与适用平台
QOwnNotes 官方提供 Nix 包,包名为 qownnotes,可通过 Nix 包管理器安装在:
- NixOS(作为系统包或用户级包)
- 其他 Linux 发行版(Arch、Debian、Fedora 等上安装 Nix 后)
- macOS(支持 x86 与 Apple Silicon,即 x86_64-darwin 与 aarch64-darwin)
- Windows(通过 Nix 的 WSL 或 MSYS 环境使用)
仓库中的 flake.nix 明确声明了构建目标系统列表:x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin,这也从源码层面印证了“macOS 原生支持 x86 与 Apple Silicon”的说明。
官方建议使用 NixOS Unstable 频道 以获得最新版本的 QOwnNotes。仓库的 flake.nix 正是基于 nixpkgs/nixos-unstable 输入构建的:
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
...
};
二、安装方式
2.1 通用安装命令
在非 NixOS 的 Linux 发行版或 macOS 上,使用 Nix 包管理器(含 flakes)安装:
nix profile install nixpkgs#qownnotes
不使用 flakes 的传统方式:
nix-env -iA nixpkgs.qownnotes
2.2 NixOS 系统级安装
在 NixOS 上,将包加入 configuration.nix 的系统包列表:
{ config, pkgs, ... }:
{
environment.systemPackages = with pkgs; [ qownnotes ];
}
然后重建系统:
sudo nixos-rebuild switch
2.3 安装后的启动命令
安装完成后,可以通过以下两个命令启动 QOwnNotes:
qownnotes
或
QOwnNotes
之所以两个命令都可用,是因为 Nix 打包时在 Linux 上创建了小写 qownnotes 的符号链接指向 QOwnNotes 可执行文件(见 default.nix 中的 postInstall 段:ln -s $out/bin/QOwnNotes $out/bin/qownnotes),而在 macOS 上则直接把二进制重命名为小写形式。包的 meta.mainProgram = "qownnotes" 同样声明了主程序名。
三、包的特性:Qt6、系统 botan3、libgit2 与 shell 补全
根据官方文档,Nix 包具有以下特性:
- 使用 Qt6 构建
- 使用系统的 botan3 加密库
- 使用 libgit2(笔记版本控制依赖)
- 提供 fish 与 bash 的 shell 补全
这些特性在 default.nix 中有完整的对应实现。构建时传入的 CMake 参数如下:
cmakeFlags = [
"-DQON_QT6_BUILD=ON"
"-DBUILD_WITH_SYSTEM_BOTAN=ON"
"-DBUILD_WITH_LIBGIT2=ON"
"-DBUILD_WITH_ASPELL=ON"
];
其中还包含可选的 useQlitehtml 参数(启用 -DUSE_QLITEHTML=ON 与静态库类型),用于在需要时启用 qlitehtml 渲染。构建依赖(buildInputs)包括 qtbase、qtdeclarative、qtsvg、qtwebsockets、botan3、libgit2、aspell;在 Linux 上额外链接 libsecret 与 qtwayland,并加入 xvfb-run(用于无头环境生成补全脚本)。
3.1 shell 补全的实现原理
文档中提到的“shell 集成”并非纸上谈兵。QOwnNotes 在 CLI 层实现了补全脚本的生成:
- src/main.cpp 注册了
--completion命令行选项,说明为 “Generate shell completion code. Supportsfish,bash.”;当传入--completion fish或--completion bash时,分别调用Utils::Cli::generateFishCompletionScript与generateBashCompletionScript后直接退出。 - src/utils/cli.cpp 实现了两类脚本的生成:fish 使用
complete -c QOwnNotes -l <option> -d "<description>"形式;bash 生成_QOwnNotes()补全函数,并通过complete -F _QOwnNotes QOwnNotes注册,对需要文件参数的选项还支持_filedir文件补全。 - Nix 打包时通过
installShellCompletion把生成的脚本安装到系统中(Linux 上借助xvfb-run在无显示环境下执行二进制生成脚本)。
也就是说,安装 Nix 包后,在 bash 或 fish 中输入 QOwnNotes - 或 qownnotes - 即可看到命令选项提示,包括 --portable、--session、--action、--completion、--decrypt-note 等。
四、命令行片段管理器 qc
QOwnNotes 官方还维护了一个命令行片段管理器 qc(QOwnNotes command-line snippet manager),它同样可以通过 Nix Store 安装。
官方推荐用以下命令临时体验:
nix-shell -p qc --run "qc exec"
该命令会进入一个临时 Nix shell,把 qc 放入环境并立即执行 qc exec。qc 是与 QOwnNotes 桌面端协作的命令行工具,适合在终端中快速调用与管理命令片段。
五、macOS 注意事项
官方文档特别强调:在 macOS 上,该 Nix 包原生支持 x86 与 Apple Silicon。这一点由 flake.nix 中列出的 x86_64-darwin 与 aarch64-darwin 系统目标,以及 default.nix 中针对 Darwin 的 makeWrapper 原生构建依赖和独立的后安装逻辑共同支撑(macOS 分支会把 QOwnNotes 可执行文件重命名为小写 qownnotes)。
在 macOS 上安装同样简单:
nix profile install nixpkgs#qownnotes
qownnotes
六、Linux 桌面密钥环(Keychain)配置与故障排查
6.1 报错信息与原因
如果 QOwnNotes 在日志中输出 Could not write secret to keychain,说明系统当前没有可用的桌面密钥环(Secret Service)实现。此时需要安装一个 Secret Service 实现,并重启桌面会话。
该行为与仓库源码完全对应:src/services/cryptoservice.cpp 中的 detectKeychainAvailability() 会通过 D-Bus 探测 org.freedesktop.secrets(GNOME/Secret Service)、org.kde.kwalletd6、org.kde.kwalletd5(KWallet)等服务是否注册或可激活,再结合 QKeychain::isAvailable() 判断密钥环是否可用。
6.2 GNOME 与基于 Secret Service 的桌面
对于 GNOME 以及其他使用 Secret Service API 的桌面环境,将以下包加入你的 Nix 环境:
gnome-keyring:Secret Service 守护进程实现libsecret:客户端库(QOwnNotes 通过 qtkeychain 的 libsecret 后端写入密钥)seahorse:图形化的密钥管理工具
在 NixOS 上可直接加入系统包:
environment.systemPackages = with pkgs; [
qownnotes
gnome-keyring
libsecret
seahorse
];
对于使用 home-manager 的用户,加入 home.packages 即可。
6.3 KDE Plasma
KDE Plasma 桌面使用 KWallet 实现密钥存储,需要添加 KWallet 相关包:
kdePackages.kwalletmanagerkdePackages.kwallet
例如:
environment.systemPackages = with pkgs; [
qownnotes
kdePackages.kwalletmanager
kdePackages.kwallet
];
6.4 回退到传统加密
如果桌面密钥环不可用,QOwnNotes 会自动回退到传统加密方式存储机密信息。源码 cryptoservice.cpp 中的 isKeychainAvailable() 在每次运行时会检测一次系统密钥环:若不存在,则跳过密钥环写入,并告警 “No system keychain is available, secrets will be stored with the legacy storage”;写入密钥环失败时(如超时或服务缺失)同样回退:Could not store secret in keychain, falling back to legacy encryption。
传统加密基于 SimpleCrypt(仓库 src/libraries/simplecrypt),并使用 cryptoKey 配置项(cryptoservice.cpp 中生成并保存)。这意味着即使没有密钥环,云连接密码、脚本机密等仍能正常存取,只是保护强度与桌面密钥环方案不同。
七、从源码构建的 Nix 变体(进阶)
仓库提供了丰富的 Nix 打包入口,适合需要自建或定制构建的开发者:
-
flake.nix 提供以下包变体:
qownnotes-qt6:默认 Qt6 构建(即官方包)qownnotes-qt6-qlitehtml:启用 qlitehtml 渲染的 Qt6 构建qownnotes-qt69:固定新版 Qt 6.9 构建qownnotes-qt5/qownnotes-cmake-qt5/qownnotes-qt5153:Qt5 构建变体(qmake 或 CMake 构建系统,见 build-systems/nix/default-qt5.nix)default:等价于nixpkgs.qt6Packages下的默认包
-
flake.nix还提供了devShells.default开发环境,包含cmakeWithGui、qmake、qttools、wrapQtAppsHook、botan3、libgit2、libsecret等构建依赖,可用于本地编译调试。 -
NixOS 虚拟机测试 tests/vm/qownnotes.nix 展示了安装后的自动化验证流程:在无头 X11 环境下启动
qownnotes --version、打开主窗口、走完首次运行向导(创建笔记目录、布局预设、Nextcloud 配置)、创建并保存新笔记,最后通过grep校验笔记文件落盘。该测试同时使用 OCR 与端口探测(如 WebSocket 服务监听 22222 端口)确认应用正常运行,可作为安装后自查的参考。
八、常见问题小结
| 现象 | 原因 | 解决办法 |
|---|---|---|
命令 qownnotes 找不到 |
包未安装或 PATH 未配置 | 使用 nix profile install nixpkgs#qownnotes 或加入 environment.systemPackages |
日志出现 Could not write secret to keychain |
缺少 Secret Service / KWallet 实现 | 按上文 6.2 / 6.3 节安装密钥环包并重启桌面会话 |
| 想要最新版本 | 使用了稳定频道 | 切换到 NixOS Unstable 频道(flake.nix 亦默认基于 unstable) |
| 想要 fish / bash 命令补全 | — | Nix 包已内置;也可手动执行 QOwnNotes --completion fish 查看生成脚本 |
通过 Nix 安装 QOwnNotes,你获得的不只是单个应用,而是一套可复现、可回滚、跨平台一致的软件环境——这正是 Nix 包管理器相比传统包管理的核心价值。