QOwnNotes 的 Nix 安装全指南:在 NixOS、Linux、macOS 与 Windows 上部署、验证与排查

原创2026-10-12 22:29:33844 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

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,其构建流程值得展开:

  1. 版本自动提取:表达式用正则从 src/version.h 中读取 #define VERSION "…" 得到当前版本号(当前源码版本为 26.10.3,见 src/version.h),确保打包版本与源码同步,无需手工维护。
  2. 构建输入:Linux 下追加 libsecret(桌面钥匙串支持)与 qtwayland(Wayland 会话支持);Darwin 下追加 makeWrapper。开发者若启用 useQlitehtml,会额外传入 -DUSE_QLITEHTML=ON -DQLITEHTML_LIBRARY_TYPE=STATIC 以使用仓库自带的 qlitehtml 渲染引擎。
  3. 补全集成:postInstall 阶段在 Linux 上借助 xvfb-run(无头 X 环境)运行 QOwnNotes --completion bash/fish,分别以 QOwnNotes 和 qownnotes 两个命令名安装补全脚本;macOS 则直接运行二进制生成。
  4. 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 的实现可以看清完整链路:

  1. writeSecret() 使用 QtKeychain 的 WritePasswordJob 写入密钥;写入失败时打印 Could not write secret to keychain: <key> <errorString>(见 cryptoservice.cpp)。
  2. isKeychainAvailable() 采用静态缓存,每次应用运行只检测一次系统钥匙串是否可用(见 cryptoservice.cpp);若检测到没有可用的钥匙串,会输出提示并将密钥存入 legacy 存储。
  3. 若钥匙串不可用或写入失败,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。

登录后查看全文
QOwnNotes