QOwnNotes 在 Ubuntu、elementary OS 与 Linux Mint 上的安装指南:Qt6 PPA、OBS 仓库与 Qt5 迁移实战

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

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

各条命令的作用如下:

  1. 移除 Qt5 PPA:add-apt-repository --remove 会删除旧源。官方文档要求先移除旧 Qt5 PPA 再添加 Qt6 PPA,是为了避免两个源同时提供 qownnotes 包导致版本冲突或源优先级混乱;如果你从未添加过 Qt5 PPA,这条命令可跳过。
  2. 添加 Qt6 PPA:将 ppa:pbek/qownnotes-qt6 写入系统的 APT 源列表。该 PPA 由 QOwnNotes 维护者(pbek)托管在 Ubuntu Launchpad 上。
  3. 刷新并安装: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。

登录后查看全文
QOwnNotes