QOwnNotes 的 Nix 安装指南:NixOS / Linux / macOS 下的包管理、命令补全与密钥环配置

原创2026-10-13 17:39:461,922 阅读
文章标签:桌面应用知识管理富文本插件系统跨平台

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. Supports fish, 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.kwalletmanager
  • kdePackages.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 包管理器相比传统包管理的核心价值。

登录后查看全文
QOwnNotes