QOwnNotes 的 Nix 安装与构建全指南:NixOS、Linux、macOS 全覆盖
QOwnNotes 的 Nix 安装与构建全指南:NixOS、Linux、macOS 全覆盖
QOwnNotes 是一款以纯文本文件为核心的笔记与待办事项管理器,内置 Markdown 支持与 Nextcloud / ownCloud 同步集成。通过 Nix 包管理器,你可以在 NixOS、其他 Linux 发行版、macOS 甚至 Windows 上安装官方 qownnotes 软件包,并直接使用 qownnotes 或 QOwnNotes 命令启动。读完本文,你将掌握 Nix 下安装、启动、验证 QOwnNotes 的完整流程,理解官方 Nix 构建配方(Qt6 + botan3 + libgit2)的底层配置,并能独立解决 Linux 桌面环境下密钥环(keychain)不可用导致的 Could not write secret to keychain 问题。
Nix 软件包概览:包名、构建基线与平台支持
官方 Nix 软件包名为 qownnotes,你可以在 NixOS 软件包搜索(Unstable 通道)中检索到它。该软件包具备如下特征,这些信息在官方安装文档中有明确记载,并与仓库根目录的 default.nix 构建配方一一对应:
| 特性 | 说明 |
|---|---|
| 包名 | qownnotes(安装后同时提供 qownnotes 与 QOwnNotes 两个命令) |
| Qt 版本 | 基于 Qt6 构建 |
| 加密后端 | 使用系统的 botan3 密码学库 |
| 版本控制 | 链接系统的 libgit2 库 |
| Shell 集成 | 为 fish 和 bash 安装命令行补全(shell completion) |
| 平台支持 | NixOS、其他 Linux 发行版、macOS(x86 与 Apple Silicon 原生支持)、Windows |
在 default.nix 的 stdenv.mkDerivation 中可以看到具体的构建输入与 CMake 开关:
buildInputs = [
qt6Packages.qtbase
qt6Packages.qtdeclarative
qt6Packages.qtsvg
qt6Packages.qtwebsockets
botan3
libgit2
aspell
]
++ lib.optionals stdenv.hostPlatform.isLinux [
libsecret
qt6Packages.qtwayland
];
cmakeFlags = [
"-DQON_QT6_BUILD=ON"
"-DBUILD_WITH_SYSTEM_BOTAN=ON"
"-DBUILD_WITH_LIBGIT2=ON"
"-DBUILD_WITH_ASPELL=ON"
];
提示:为获取 QOwnNotes 的最新版本,建议使用 NixOS Unstable 通道(nixos-unstable)安装。
安装 QOwnNotes
NixOS 系统级安装
在 NixOS 上,最推荐的方式是把软件包加入系统配置。编辑 /etc/nixos/configuration.nix,在 environment.systemPackages 中添加 qownnotes:
{ config, pkgs, ... }:
{
environment.systemPackages = with pkgs; [
qownnotes
];
}
然后重建系统配置:
sudo nixos-rebuild switch
其他 Linux 发行版与 macOS 的用户级安装
在装有 Nix 包管理器的任意 Linux 发行版或 macOS 上,可以直接使用 nix-env 进行用户级安装:
nix-env -iA nixos.qownnotes # 使用 nixos-unstable 通道时
临时试用(不提交到系统)
如果只想先体验一下,不需要持久安装,可以用 nix-shell 创建临时环境:
nix-shell -p qownnotes --run "qownnotes"
无论采用哪种方式,安装完成后都应能通过 qownnotes 或 QOwnNotes 命令启动 QOwnNotes。之所以有两个命令名,是因为在 Linux 构建阶段,default.nix 会为 QOwnNotes 二进制创建一个小写符号链接:
# Create a lowercase symlink for Linux
+ lib.optionalString stdenv.hostPlatform.isLinux ''
ln -s $out/bin/${finalAttrs.appname} $out/bin/${finalAttrs.pname}
''
在 macOS 上则相反,构建过程会直接把可执行文件重命名为小写形式的 qownnotes(见 default.nix)。
启动与版本验证
安装后即可启动应用:
qownnotes
# 或
QOwnNotes
如需验证安装是否正常,可先查看版本号:
qownnotes --version
仓库的 NixOS 虚拟机测试 tests/vm/qownnotes.nix 正是通过这种方式断言安装正确性——它启动虚拟机、执行 qownnotes --version,然后等待控制台输出形如 QOwnNotes 26.10.3 的版本字符串(当前仓库 src/version.h 中的版本为 26.10.3)。测试还会进一步验证首次运行向导、创建新笔记等核心流程,说明该 Nix 软件包经过完整的端到端可用性验证。
安装命令行代码片段管理器 qc
QOwnNotes 官方的命令行代码片段管理器 qc 同样可以从 Nix 软件仓库安装。安装之后即可使用 qc exec 执行代码片段:
nix-shell -p qc --run "qc exec"
nix-shell -p qc 会构建一个仅包含 qc 的临时环境,--run 参数则在其中立即执行 qc exec——非常适合先试用再决定是否持久安装。
从 flake 构建:官方多形态构建矩阵
除了使用预编译软件包,你还可以直接从仓库源码用 Nix 构建 QOwnNotes。仓库根目录的 flake.nix 定义了一个完整的构建矩阵,覆盖 Qt6 与 Qt5 的多条构建路径:
| flake 输出 | 说明 |
|---|---|
qownnotes-qt6 |
默认 Qt6 构建(对应 default.nix) |
qownnotes-qt6-qlitehtml |
Qt6 + QLiteHtml 预览引擎(useQlitehtml = true) |
qownnotes-qt69 |
固定 nixpkgs 快照下的 Qt 6.9 构建 |
qownnotes-qt5 |
Qt5 + qmake 构建(build-systems/nix/default-qt5.nix) |
qownnotes-cmake-qt5 |
Qt5 + CMake 构建(build-systems/nix/default-cmake-qt5.nix) |
qownnotes-qt5153 |
固定快照下的 Qt 5.15.3 构建 |
default |
跟随 nixpkgs Qt6 的默认包 |
flake 声明的支持系统为 x86_64-linux、aarch64-linux、x86_64-darwin 与 aarch64-darwin(见 flake.nix)——这也从构建配置层面印证了文档中"macOS 原生支持 x86 与 Apple Silicon"的表述。
从仓库构建 Qt6 版本的命令(justfile 中 nix-build-qt6 的定义):
nix build '.?submodules=1#qownnotes-qt6'
需要 QLiteHtml 预览支持时:
nix build '.?submodules=1#qownnotes-qt6-qlitehtml'
小知识:
USE_QLITEHTML对应源码中的 src/CMakeLists.txt CMake 选项。QLiteHtml 需要 Qt 6+,在 Qt 5 构建中会被自动禁用。QOwnNotes 默认开启 QLiteHtml 预览,且默认将其编译为静态库以避免共享库问题。
另外,仓库还提供了开发 shell(nix develop 或 devenv),其中预置了 cmake、qmake、botan3、libsecret 等开发依赖(见 devenv.nix),适合希望从源码调试 QOwnNotes 的开发者。
解决 Could not write secret to keychain 错误
在 Linux 桌面上,如果 QOwnNotes 的日志中出现如下警告:
Could not write secret to keychain: <key> <error>
这表示系统缺少可用的 Secret Service(Secret Service API)实现,QOwnNotes 无法把加密密钥等机密信息写入系统密钥环。解决方法是安装一个 Secret Service 实现,然后重启桌面会话(或重新登录)。
GNOME 及基于 Secret Service 的桌面
对于 GNOME 及其他遵循 Secret Service API 的桌面环境,将以下软件包加入你的环境(NixOS 的 environment.systemPackages,或其他发行版的系统包):
gnome-keyring:GNOME 密钥环守护进程,提供org.freedesktop.secretsD-Bus 服务libsecret:Secret Service API 的客户端库seahorse:GNOME 的密钥管理图形工具(便于查看与管理存储的密钥)
KDE Plasma
对于 KDE Plasma,需要 KWallet 支持:
kdePackages.kwalletmanager:KWallet 图形管理工具kdePackages.kwallet:KWallet 核心实现
密钥环不可用时的降级行为
需要特别注意的是:即使密钥环不可用,QOwnNotes 也不会拒绝工作。根据文档说明,QOwnNotes 会回退到 legacy encryption(旧版加密),将机密信息改用内置的 SimpleCrypt 方案加密存储。
源码 src/services/cryptoservice.cpp 揭示了这一机制的精妙之处:
bool CryptoService::isKeychainAvailable() {
static int availability = -1;
if (availability == -1) {
availability = detectKeychainAvailability() ? 1 : 0;
if (availability == 0) {
qWarning() << "No system keychain is available, secrets will be stored with the "
"legacy encryption";
}
}
return availability == 1;
}
isKeychainAvailable() 使用静态变量缓存结果,每次应用运行只探测一次密钥环可用性。Linux 上的探测逻辑(detectKeychainAvailability,见 cryptoservice.cpp)比 QtKeychain 默认的库加载检查更进一步:它会通过 D-Bus 检查 org.freedesktop.secrets、org.kde.kwalletd6、org.kde.kwalletd5 服务是否已注册或可被 D-Bus 激活(cryptoservice.cpp),确保不仅"库可用"而且"真的有服务在运行"。
当写入失败时,源码会打出警告并触发降级:
} else if (!result.ok) {
qWarning() << "Could not write secret to keychain:" << key << job->errorString();
}
随后 storeSecret() 返回 false,调用方自动改用 legacyEncryptToString()(SimpleCrypt 加密)存储机密(cryptoservice.cpp)。同时,CryptoService 构造时会调用 migrateSecrets() 把旧版存储的机密迁移到密钥环(cryptoservice.cpp),迁移过程同样遵循"密钥环可用才写入、否则保留旧版"的降级原则。
在 NixOS 上进行自动化验证
如果你希望在 NixOS 上自动化验证 QOwnNotes 的可用性,仓库自带的虚拟机测试可以作为参考范例。flake.nix 中注册了 checks.x86_64-linux.qownnotes(见 flake.nix),运行测试:
nix build .?submodules=1#checks.x86_64-linux.qownnotes -L --no-link
该测试(tests/vm/qownnotes.nix)在虚拟机中依次完成:启动 X 服务、校验 qownnotes --version 输出、启动 QOwnNotes 主窗口、走完首次运行向导(创建 /home/alice/Notes 笔记目录、选择布局预设、Nextcloud 配置等)、创建并保存新笔记后验证文件内容写入磁盘。如果你正在维护 QOwnNotes 的 Nix 打包或希望在自定义发行版镜像中预装它,这套测试流程可以直接复用。
相关仓库文件速查
- 官方安装文档:webpage/src/nl/installation/nix.md(多语言版本见 webpage/src/installation/nix.md)
- Qt6 构建配方:default.nix
- Flake 构建矩阵与开发环境:flake.nix、devenv.nix
- CMake 选项定义:src/CMakeLists.txt
- qmake 工程文件:src/QOwnNotes.pro
- Botan 后端开关:src/libraries/botan/botan.pri
- 密钥环与降级加密实现:src/services/cryptoservice.cpp
- NixOS 虚拟机测试:tests/vm/qownnotes.nix
- Nix 构建快捷命令:justfile(
nix-build、nix-build-qt6、vm-test等 recipe)