QOwnNotes 的 Nix 安装全指南:在 NixOS、Linux、macOS 与 Windows 上部署、验证与排查
QOwnNotes 的 Nix 安装全指南:在 NixOS、Linux、macOS 与 Windows 上部署、验证与排查
本篇指南以 QOwnNotes 官方 Nix 安装文档(webpage/src/es/installation/nix.md)为骨架,结合仓库内的 Nix 打包源码与测试,系统讲解如何通过 Nix 包管理器安装、启动、验证 QOwnNotes,并深入剖析该包基于 Qt6 的构建方式、bash/fish 补全集成以及 Linux 桌面钥匙串故障的排查方案。读完本文,你将能够在 NixOS 与其他发行版上一条命令装好 QOwnNotes,理解其 Nix 包的真实依赖与构建参数,并学会处理 Could not write secret to keychain 等常见问题。
一、环境支持与包的基本形态
QOwnNotes 官方通过 Nix 包管理器 分发,官方文档声明它可安装在 NixOS、其他 Linux 发行版、macOS 以及 Windows 上。包名统一为 qownnotes,在 NixOS 的 unstable 频道中提供最新版本,因此官方明确建议:
最好使用 NixOS Unstable 频道来获取最新版本的 QOwnNotes。
仓库内的打包表达式也印证了该建议的合理性——flake.nix 将主输入锁定为 nixpkgs/nixos-unstable,并把包注册为 qownnotes-qt6、qownnotes-qt6-qlitehtml、qownnotes-qt69 等多个可并行选择的派生包,默认输出 default 即 Qt6 版本。
从官方文档与 default.nix 可以确认该包具备以下特征:
| 特征 | 说明 | 源码依据 |
|---|---|---|
| GUI 框架 | 使用 Qt6 构建,CMake 参数 -DQON_QT6_BUILD=ON |
default.nix |
| 加密库 | 使用系统级 botan3 库(-DBUILD_WITH_SYSTEM_BOTAN=ON),而非仓库内嵌的旧版 Botan |
default.nix |
| Git 支持 | 链接系统 libgit2(-DBUILD_WITH_LIBGIT2=ON),用于笔记仓库的版本控制能力 |
default.nix |
| 拼写检查 | 启用系统 aspell(-DBUILD_WITH_ASPELL=ON) |
default.nix |
| Shell 集成 | 安装完成后自动生成 fish 与 bash 的补全脚本 | default.nix |
| 二进制命名 | Linux 下同时提供 QOwnNotes 与 qownnotes 两个可执行名 |
default.nix |
二、安装步骤
2.1 在 NixOS 与 Linux 上安装
在 NixOS 或任何安装了 Nix 的 Linux 系统上,选用 unstable 频道安装 qownnotes 即可。以下命令为 Nix 生态的标准安装形式(当前仓库文档明确给出包名与频道,命令本身为 Nix 通用用法):
# 使用 nix profile(Nix 2.4+ 推荐)
nix profile install nixpkgs#qownnotes
# 或使用传统 nix-env
nix-env -iA nixos.qownnotes
2.2 在 macOS 上安装
macOS 同样通过 Nix 安装该包,且官方特别说明:在 macOS 上,该包原生支持 x86 与 Apple Silicon,无需 Rosetta 转译。从源码看,打包表达式针对 Darwin 平台做了专门处理:构建依赖中追加 makeWrapper,安装阶段把可执行文件从大写 QOwnNotes 重命名为小写 qownnotes(先改名过渡文件再改名目标,以避免 "same file" 错误),见 default.nix。
nix profile install nixpkgs#qownnotes
2.3 关于 Windows
官方文档声明 QOwnNotes 也可通过 Nix 安装在 Windows 上。需要说明的是,该包的 meta.platforms 声明为 Unix 系平台(见 default.nix),因此在 Windows 上的典型做法是通过 Nix 所处的相应环境(如 WSL)来使用。
三、启动与验证
安装完成后,可以直接用命令启动应用:
qownnotes # 小写命令名
# 或
QOwnNotes # 大写命令名(Linux 上两者等价)
之所以同时存在两个名字,是因为 default.nix 在 Linux 安装阶段创建了小写符号链接:
ln -s $out/bin/${finalAttrs.appname} $out/bin/${finalAttrs.pname}
即 $out/bin/QOwnNotes -> $out/bin/qownnotes 双向可用。应用还支持命令行参数,例如查看版本与生成补全脚本:
qownnotes --version # 打印版本号
qownnotes --completion bash # 输出 Bash 补全脚本
qownnotes --completion fish # 输出 Fish 补全脚本
从源码看,--completion 选项在 src/main.cpp 中解析,接受 fish 或 bash 两种取值,并分别调用 Utils::Cli::generateFishCompletionScript 与 Utils::Cli::generateBashCompletionScript(实现见 src/utils/cli.cpp)。仓库打包时正是通过这一机制在安装阶段生成补全并安装到 shell 环境中(见下节)。
四、源码级解析:Nix 包是如何构建的
qownnotes 的 Nix 打包表达式位于仓库根目录 default.nix,其构建流程值得展开:
- 版本自动提取:表达式用正则从
src/version.h中读取#define VERSION "…"得到当前版本号(当前源码版本为26.10.3,见 src/version.h),确保打包版本与源码同步,无需手工维护。 - 构建输入:Linux 下追加
libsecret(桌面钥匙串支持)与qtwayland(Wayland 会话支持);Darwin 下追加makeWrapper。开发者若启用useQlitehtml,会额外传入-DUSE_QLITEHTML=ON -DQLITEHTML_LIBRARY_TYPE=STATIC以使用仓库自带的 qlitehtml 渲染引擎。 - 补全集成:
postInstall阶段在 Linux 上借助xvfb-run(无头 X 环境)运行QOwnNotes --completion bash/fish,分别以QOwnNotes和qownnotes两个命令名安装补全脚本;macOS 则直接运行二进制生成。 - Nix flake 入口:flake.nix 为四种系统架构(
x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin)注册了多个包变体,包括 Qt6 默认版、qlitehtml版、Qt6.9 实验版以及若干 Qt5 构建(qmake/CMake 两种构建系统,见 build-systems/nix/default-qt5.nix 与 build-systems/nix/default-cmake-qt5.nix),方便开发者本地构建与测试。
五、安装命令行片段管理器 qc
QOwnNotes 官方还提供了命令行片段管理器 qc,同样可通过 Nix 安装。官方文档给出的试用命令为:
nix-shell -p qc --run "qc exec"
这条命令会临时拉取 qc 包并在其环境中执行 qc exec,无需全局安装即可体验。qc 是 QOwnNotes 终端片段管理器的官方配套工具,适合习惯在终端中快速复用命令片段的用户。
六、从源码构建与自动化验证(进阶)
如果你希望基于当前仓库自行构建或验证 Nix 包,可以直接使用仓库内的 flake:
# 进入开发环境(包含 Qt6、botan3、libgit2、libsecret 等依赖)
nix develop
# 构建默认 Qt6 包
nix build .#default
# 构建 qlitehtml 变体
nix build .#qownnotes-qt6-qlitehtml
仓库还提供了 NixOS VM 集成测试(tests/vm/qownnotes.nix),由 flake.nix 注册为 checks.x86_64-linux.qownnotes。该测试在虚拟机中真实安装并启动 QOwnNotes,自动完成首次运行向导(依次跳过 Note folder、Layout preset、Nextcloud 设置等步骤),验证:
- 命令行
qownnotes --version能输出正确的QOwnNotes <版本号>; - 应用窗口能正常启动并显示欢迎界面;
- 通过
Ctrl+n新建笔记、Ctrl+s保存后,笔记内容确实写入~/Notes目录(测试通过grep校验文件内容); - 内置 WebSocket 服务在端口
22222正常监听。
这组测试从端到端证明了 Nix 安装产物在真实 NixOS 环境中可以正常工作。
七、故障排查:Could not write secret to keychain
在 Linux 上使用过程中,如果 QOwnNotes 日志出现以下消息:
Could not write secret to keychain: <key> <error>
官方文档给出的处理方法是:安装一个 Secret Service 实现,并重启桌面会话。根据桌面环境不同,需要安装的包也不同:
- GNOME 及其他基于 Secret Service 的桌面:在环境中加入
gnome-keyring、libsecret与seahorse等包; - KDE Plasma:添加 KWallet 支持,例如
kdePackages.kwalletmanager与kdePackages.kwallet。
在 NixOS 上,可将这些包加入 environment.systemPackages 并重启桌面会话;在其他发行版上则使用系统包管理器安装对应软件包。
7.1 源码层面的机制解释
为什么会出现这条消息?从 src/services/cryptoservice.cpp 的实现可以看清完整链路:
writeSecret()使用 QtKeychain 的WritePasswordJob写入密钥;写入失败时打印Could not write secret to keychain: <key> <errorString>(见 cryptoservice.cpp)。isKeychainAvailable()采用静态缓存,每次应用运行只检测一次系统钥匙串是否可用(见 cryptoservice.cpp);若检测到没有可用的钥匙串,会输出提示并将密钥存入 legacy 存储。- 若钥匙串不可用或写入失败,
storeSecret()会自动回退到 legacy 加密(legacyEncryptToString),保证 Nextcloud 密码等敏感设置仍能加密保存,只是不经过系统钥匙串(见 cryptoservice.cpp)。
官方文档也明确说明:"如果桌面钥匙串不可用,QOwnNotes 将回退到 legacy 加密。"这意味着该警告不影响笔记本身的加解密功能,但为了把密钥安全托管给系统钥匙串,还是建议按上文补齐 Secret Service 组件并重启桌面会话。
八、小结
通过 Nix 安装 QOwnNotes 是一站式获得 Qt6 版本、系统 botan3/libgit2 依赖、bash/fish 补全与 macOS 原生二进制的推荐路径。掌握安装命令、qownnotes/QOwnNotes 双命令名、qc 片段管理器以及 Could not write secret to keychain 的排查方法,即可在 Nix 生态中顺畅使用这款纯文本 Markdown 笔记与待办管理工具。若需深入构建细节或自行验证,可直接参考仓库根目录的 default.nix、flake.nix 与 tests/vm/qownnotes.nix。