QOwnNotes 在 Ubuntu、elementary OS 与 Linux Mint 上的安装指南:Qt6 PPA、OBS 仓库与 Qt5 迁移实战
QOwnNotes 在 Ubuntu、elementary OS 与 Linux Mint 上的安装指南:Qt6 PPA、OBS 仓库与 Qt5 迁移实战
QOwnNotes 是一款基于纯文本文件、支持 Markdown 并集成 Nextcloud/ownCloud 的笔记与待办事项管理工具。本文以官方安装文档为主线,系统讲解在 Ubuntu Linux、elementary OS 与 Linux Mint 上通过 PPA(Personal Package Archive)与 OBS(Open Build Service)仓库安装 QOwnNotes 的完整方案,并深入说明 Qt6/Qt5 双版本通道的现状、ARM 平台(Raspberry Pi)支持以及桌面密钥链问题的排查方法。读完本文,你将能够根据自己的系统版本选择正确的安装通道、理解每条命令的作用,并在遇到密钥链报错时快速修复。
一、先了解现状:Qt6 主版本与 Qt5 遗留通道
在动手安装之前,有必要先厘清 QOwnNotes 当前的版本与构建体系。仓库源码中记录的版本为 26.10.3(见 src/version.h),从源码结构看,项目同时保留 Qt5 与 Qt6 两套构建路径:在 src/CMakeLists.txt 中,通过 QON_QT6_BUILD 编译选项决定使用 Qt 6 还是 Qt 5,默认关闭(即默认 Qt5 构建),而官方 Ubuntu 发行渠道则早已全面转向 Qt6。
这一转变与仓库内的 Qt5 退役决策直接相关:docs/qt5-retirement-recommendation.md 明确记载,项目已决定停止通过发行流程发布 Qt5 软件包。对应到 Ubuntu 生态,官方文档已经将原来的 Qt5 PPA(ppa:pbek/qownnotes)标记为"不再更新",仅保留既有软件包供无法运行 Qt6 构建的旧系统使用。因此:
- 新安装用户:一律优先选择 Qt6 通道(
ppa:pbek/qownnotes-qt6或 OBS Qt6 仓库); - 已在用 Qt5 旧包的用户:建议按本文第二、五节迁移到 Qt6 通道;
- 系统过于老旧、无法满足 Qt6 依赖要求的用户:保留最终 Qt5 包,或改用 AppImage 方案。
二、方案一(推荐):Ubuntu 24.04 及更新系统使用 Qt6 PPA
本节方案适用于 Ubuntu Linux(最低 24.04)、elementary OS 以及 Linux Mint 22.1 及以上版本。该通道的 QOwnNotes 使用 Qt6 构建。
打开终端,依次执行以下命令:
# 若此前安装过 Qt5 PPA,先将其移除
sudo add-apt-repository --remove ppa:pbek/qownnotes
# 添加 Qt6 PPA
sudo add-apt-repository ppa:pbek/qownnotes-qt6
# 安装 QOwnNotes
sudo apt-get update
sudo apt-get install qownnotes
各条命令的作用如下:
- 移除 Qt5 PPA:
add-apt-repository --remove会删除旧源。官方文档要求先移除旧 Qt5 PPA 再添加 Qt6 PPA,是为了避免两个源同时提供qownnotes包导致版本冲突或源优先级混乱;如果你从未添加过 Qt5 PPA,这条命令可跳过。 - 添加 Qt6 PPA:将
ppa:pbek/qownnotes-qt6写入系统的 APT 源列表。该 PPA 由 QOwnNotes 维护者(pbek)托管在 Ubuntu Launchpad 上。 - 刷新并安装:
apt-get update拉取新源的软件包索引,apt-get install qownnotes安装主程序包。
值得注意的是,该仓库同时提供 ARM 架构的软件包,如果你打算在 Raspberry Pi 上运行 QOwnNotes,直接使用同一条 apt-get install qownnotes 命令即可,无需额外配置交叉源。官方另外为 Raspberry Pi OS 提供了专门的 OBS 仓库安装说明(见 webpage/src/installation/raspberry-pi-os.md),可作为参考。
2.1 这个 Qt6 包内部由什么构成?
从打包描述文件可以精确看到 Qt6 版 Debian 包的依赖组成。ubuntu-launchpad/qt6/control 声明了 qownnotes 包的运行时依赖,主要包括:
libqt6core6、libqt6gui6、libqt6widgets6、libqt6sql6+libqt6sql6-sqlite:Qt6 核心、界面、数据库(SQLite 用于笔记索引)组件;libqt6qml6、qml6-module-qtqml*:QML 运行时,服务于脚本扩展与部分界面;libqt6svg6、libqt6network6、libqt6xml6、libqt6websockets6:SVG 图标、网络请求、XML 解析与 WebSocket 服务(QOwnNotes 的本地 Web 应用/脚本通信依赖);qt6-wayland、qt6-qpa-plugins:Wayland 会话与 Qt 平台插件支持;libsecret-1-0:桌面密钥链(Secret Service)集成,用于安全保存密码;openssl:加解密与 TLS 支持。
同时该文件显示 Qt6 包的构建依赖为 CMake(cmake (>= 3.16))加 Qt6 开发组件,印证了官方文档"Qt6 版本以 CMake 构建"的说法。构建时的关键开关在 ubuntu-launchpad/qt6/rules 中:dh_auto_configure 阶段显式传入 -DQON_QT6_BUILD=ON,并设置 QT_SELECT := 6,这正是 src/CMakeLists.txt 中那个 QON_QT6_BUILD 选项的实际应用。对比 src/debian/control 中的旧版 Qt5 包(依赖 libqt5core5a、libqt5qml5 等),可以清晰看到两代包在依赖体系上的差异。
三、方案二:旧版系统使用 Qt5 legacy PPA(Ubuntu 20.04 及以上)
如果你的系统是较旧但仍在支持的 Ubuntu(最低 20.04)、elementary OS 或 Linux Mint 18 及以上,可以使用 Qt5 版本的最终软件包。需要特别说明的是,该 Qt5 PPA 已不再更新,其中保留的是面向无法运行 Qt6 构建的旧系统的最后一批软件包。
sudo add-apt-repository ppa:pbek/qownnotes
sudo apt-get update
sudo apt-get install qownnotes
同样地,该仓库也包含 ARM 架构软件包,可供 Raspberry Pi 使用。对于仍停留在这些系统上的用户,Qt5 包是官方最后提供的发行版通道之一;若希望长期跟随新功能,则应考虑升级系统或改用下一节介绍的 AppImage 方案。
四、方案三:更旧发行版与衍生发行版 → AppImage
对于比 Qt5 PPA 最低要求(Ubuntu 20.04)更旧的 Ubuntu 及其衍生发行版,官方文档的建议是优先使用 AppImage。AppImage 是免安装的单文件可执行格式,不依赖具体发行版的软件包管理,非常适合无法满足 PPA 依赖的老系统。
详细的下载、授权执行、便携模式(--portable)等操作,请参见官方安装指南 webpage/src/installation/appimage.md。要点包括:
- 从 QOwnNotes 发布页获取
QOwnNotes-x86_64.AppImage,执行chmod a+x QOwnNotes-*.AppImage赋予执行权限后即可运行; - 当前 AppImage 已内置 FUSE 用户态库,系统只需具备内核 FUSE 支持;较老的 AppImage 可能仍需单独安装
libfuse2; - 若需使用自动更新功能,请将 AppImage 放在当前用户具有写权限的目录(如主目录下);
- 若因 glibc 版本过旧无法运行,可尝试 OBS 构建的 AppImage 版本(其基于 glibc 2.16 构建)。
五、方案四:OBS 仓库安装(面向 Launchpad 未覆盖的 Ubuntu 版本)
对于 Ubuntu Launchpad 上已不再更新、但 OBS 仍在提供包的 Ubuntu 版本,可以改用 Open Build Service 上的 QOwnNotes 仓库。Ubuntu 24.04 及以上版本的 OBS 软件包同样采用 CMake 与 Qt6 构建(旧的 Qt5 OBS 包已停止更新)。以下以 xUbuntu 24.04 仓库为例给出完整命令。
第一步:信任仓库签名密钥。
wget http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/xUbuntu_24.04/Release.key -O - | sudo apt-key add -
这条命令从 OBS 仓库下载 Release.key 公钥并通过管道交给 apt-key add,使 APT 能够校验该仓库发布的软件包签名。
第二步:添加仓库源并安装。
sudo su -
sh -c "echo 'deb http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/xUbuntu_24.04/ /' >> /etc/apt/sources.list.d/qownnotes.list"
apt-get update
apt-get install qownnotes
这里 deb 行以 / 结尾,表示该仓库直接位于该路径下(扁平仓库结构),这是 OBS 仓库的典型写法;>> 将源行追加到独立的 qownnotes.list 文件中,避免污染主源文件。
需要提醒的是,apt-key add 在较新的 Ubuntu 上已被标记为弃用(官方推荐使用 /etc/apt/keyrings/ + signed-by 方式),上述命令是官方文档中给出的原始示例,在较老系统上仍可直接使用;若你的系统提示 apt-key 已移除,可改用现代方式信任该密钥,或优先选择第二节的官方 PPA 方案。
六、密钥链(Secret Service)问题排查
如果在日志中看到如下错误:
Could not write secret to keychain
说明 QOwnNotes 无法将密钥写入桌面的 Secret Service 密钥链。该功能由 libsecret-1-0 运行时依赖承载(见 ubuntu-launchpad/qt6/control 与 src/debian/control 中的 libsecret-1-0),它需要桌面环境提供对应的密钥链守护进程。解决办法是按桌面环境安装缺失的软件包,然后重启桌面会话:
GNOME 及其他基于 Secret Service 的桌面:
sudo apt install gnome-keyring libsecret-1-0 seahorse
KDE Plasma:
sudo apt install kwalletmanager
此外,官方文档明确说明:若桌面密钥链不可用,QOwnNotes 会自动回退到 legacy encryption(传统加密)方式。也就是说,该问题不会阻断 QOwnNotes 的加密功能,但会降级到旧式加密存储,建议仍按上述步骤补齐密钥链以获得更安全的密钥保管。这一回退逻辑也与项目大量使用 qtkeychain 库(见 src/QOwnNotes.pro 中的 include(libraries/qtkeychain/qtkeychain.pri) 及 CMake 中对 qt6keychain/qt5keychain 的链接)的密钥存储架构相吻合。
七、安装完成后的验证与更多安装方式
安装完成后,在终端执行:
QOwnNotes
即可启动应用(若未生效,可先重新登录桌面会话或注销再登录)。你可以在应用的"关于"对话框(或设置界面)中核对版本号,确认自己安装的是 Qt6 还是 Qt5 通道的软件包。
若你的发行版或使用场景不适用于上述 PPA/OBS 方案,仓库还提供了覆盖更多操作系统的官方安装文档入口(见 webpage/src/installation/README.md),其中包括:
- Flatpak:社区维护的
org.qownnotes.QOwnNotes包(详见 webpage/src/installation/flatpak.md); - Snap:基于 snap/snapcraft.yaml 构建的 snap 包(该文件同时展示了 Qt5 版 snap 的完整依赖与
--portable式的打包方式); - AppImage:见第四节引用文档。
如果你在使用软件包或仓库时遇到问题,官方建议在 QOwnNotes 的 Issues 页面提交反馈;涉及 Qt5 通道退役的更多背景与后续计划,可进一步阅读 docs/qt5-retirement-recommendation.md。