QOwnNotes 在 Ubuntu、elementary OS 与 Linux Mint 上的安装指南:Qt6 PPA、Qt5 遗留版本与 OBS 仓库详解
QOwnNotes 在 Ubuntu、elementary OS 与 Linux Mint 上的安装指南:Qt6 PPA、Qt5 遗留版本与 OBS 仓库详解
QOwnNotes 是一款以纯文本 Markdown 笔记与待办事项管理为核心的开源桌面应用,支持与 Nextcloud / ownCloud 深度集成。本指南以仓库内的官方安装文档(英文版见 webpage/src/installation/ubuntu.md,波兰语版见 webpage/src/pl/installation/ubuntu.md)为骨架,系统讲解在 Ubuntu 系发行版上的全部官方安装路径:Qt6 PPA、Qt5 遗留 PPA、AppImage 便携格式与 Open Build Service(OBS)仓库,并结合仓库源码说明各版本之间的构建差异与常见问题的底层原理。读完本文,你将能根据自己系统的 Ubuntu 版本与 Qt 环境,选择并正确执行最合适的安装方案,并自行解决桌面密钥环(keychain)相关故障。
安装方式总览:如何选择正确的通道
Ubuntu 系发行版上,QOwnNotes 官方提供四条安装通道,适用场景各不相同:
| 安装通道 | 适用系统 | Qt 版本 | 包管理方式 | 特点 |
|---|---|---|---|---|
Qt6 PPA(ppa:pbek/qownnotes-qt6) |
Ubuntu 24.04+、elementary OS、Linux Mint 22.1+ | Qt6 | APT(Launchpad PPA) | 当前主推通道,持续更新,含 ARM 架构包 |
Qt5 遗留 PPA(ppa:pbek/qownnotes) |
Ubuntu 20.04+ 的旧系统 | Qt5 | APT(Launchpad PPA) | 不再更新,仅保留最终版本包 |
| AppImage | 任意较老发行版及衍生版 | 视构建而定 | 无(单文件直接运行) | 免安装、支持 --portable 便携模式 |
| OBS 仓库 | Ubuntu 24.04+(CMake/Qt6 构建) | Qt6 | APT(openSUSE Build Service) | 面向 Launchpad 不再更新的系统,仓库根文件见 obs/qownnotes.spec |
仓库当前版本号为 26.10.3(见 src/version.h),本文所有命令均以该版本线为例。
Ubuntu 24.04 及以上版本:通过 Qt6 PPA 安装(推荐)
对于 Ubuntu Linux(最低 24.04)、elementary OS、Linux Mint 22.1 或更新版本,官方推荐使用 Qt6 PPA 安装 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:两个 PPA 都提供名为
qownnotes的软件包,若不移除旧源,APT 在解析软件包来源时可能产生歧义,导致无法正确升级到 Qt6 版本。 - ARM 架构支持:Qt6 PPA 仓库同时提供 ARM 架构软件包,因此你可以在 Raspberry Pi 上安装 QOwnNotes。
- Qt6 包的真实依赖:从 ubuntu-launchpad/qt6/control 的 Debian 控制文件可以看到,
qownnotes包依赖libqt6core6、libqt6gui6、libqt6sql6、libqt6sql6-sqlite、libqt6widgets6、libqt6qml6、libqt6svg6、libqt6network6、libqt6websockets6等 Qt6 运行库,以及libsecret-1-0(桌面密钥环访问)与openssl。依赖完整列出意味着apt-get install会自动拉齐所有运行所需组件。 - 构建方式:Qt6 版本由 CMake 构建,而非 Qt5 时代的 qmake。ubuntu-launchpad/qt6/rules 显示构建时以
-DQON_QT6_BUILD=ON传入 CMake;该选项在 src/CMakeLists.txt 中定义,开启后会将QT_VERSION_MAJOR设为 6 并选用 Qt6 模块。
Ubuntu 20.04 及以上(无法使用 Qt6):Qt5 遗留版本
对于无法使用 Qt6 PPA 的旧版 Ubuntu Linux、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)提供软件包。最低支持系统为 Ubuntu 20.04。
从仓库的迁移规划文档 docs/qt5-retirement-recommendation.md 可以了解 Qt5 通道的演进背景:项目已通过内部决议停止通过发布流程对外发布 Qt5 包,但会保留最终的外部 Qt5 包供无法运行 Qt6 构建的操作系统用户使用;Ubuntu 遗留 PPA 属于"发布已停止,用户需迁移到 Qt6 通道或保留最终包"的状态。因此,如果你仍在使用 Qt5 PPA,建议在系统允许的条件下尽早迁移到 Qt6 通道。
更旧的 Ubuntu 发行版及衍生版:使用 AppImage
对于 Ubuntu 24.04 以下的更旧发行版及衍生版,官方建议优先使用 GitHub Releases 发布的 AppImage。AppImage 是免安装的单文件应用格式,不依赖系统包管理器,非常适合老旧系统。
完整的 AppImage 安装说明见 webpage/src/installation/appimage.md,核心步骤摘录如下:
# 赋予执行权限
chmod a+x QOwnNotes-*.AppImage
# 直接运行
./QOwnNotes-x86_64.AppImage
几个重要的使用提示:
-
FUSE 依赖:当前版本的 QOwnNotes AppImage 已内置所需的 FUSE userspace 库,无需单独安装
libfuse2,但系统仍需内核支持 FUSE;较旧的 AppImage 版本可能仍然需要libfuse2。 -
自动更新:如果要使用 AppImage 的自动更新功能,请确保 AppImage 存放在你的用户账户有写权限的位置(例如主目录下),否则更新程序无法替换自身文件。
-
便携模式:通过
--portable参数可让 AppImage 以便携模式运行:./QOwnNotes-x86_64.AppImage --portable在便携模式下,所有应用数据都会存放在 AppImage 同级的
Data文件夹中,而不是主目录,包括:设置(Data/QOwnNotes.ini)、笔记数据库(Data/QOwnNotes.sqlite)、笔记本体(Data/Notes/),以及脚本、拼写检查词典等其他数据。这让你可以把 QOwnNotes 连同全部笔记一起放进 U 盘随身携带。从源码看,便携模式的判定与路径解析实现在 src/utils/misc.cpp 的portableDataPath()与makePathRelativeToPortableDataPathIfNeeded()中,AppImage 场景下会直接取 AppImage 文件所在目录作为数据根目录;运行./QOwnNotes-x86_64.AppImage --portable时请确保 AppImage 所在目录可写,以便Data文件夹能创建在其旁边。
使用 OBS 仓库安装(面向 Launchpad 不再覆盖的系统)
对于 Ubuntu Launchpad 上已不再更新的 Ubuntu 版本,还可以使用 Open Build Service(OBS) 提供的 QOwnNotes 仓库。OBS 上的 Ubuntu 24.04+ 软件包使用 CMake 与 Qt6 构建,仓库定义见 obs/qownnotes.spec。
以下以 xUbuntu 24.04 仓库为例(其余发行版版本号同理替换):
第一步:信任仓库密钥
wget http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/xUbuntu_24.04/Release.key -O - | sudo apt-key add -
第二步:添加仓库并安装
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
说明:第二步先切换到 root(sudo su -),然后将 OBS 仓库地址写入 qownnotes.list,再刷新软件源并安装。/ 结尾的 deb 行是 OBS 的标准写法,表示该仓库无发行版子目录。
仓库的 Qt5 遗留 OBS 软件包同样已不再更新。依据 docs/qt5-retirement-recommendation.md 的说明,当前活跃的 Qt6 OBS 包(home:pbek:QOwnNotes/desktop-cmake3)包含基于 CMake 的 Qt6 描述,可为大多数已配置的仓库成功产出软件包,但并非每个旧 Qt5 OBS 目标都有对应的 Qt6 替代品,迁移前建议核对具体发行版版本的可用性。
常见问题:Could not write secret to keychain 的处理
如果你在运行 QOwnNotes 时看到日志输出 Could not write secret to keychain,说明程序无法将密钥写入系统的桌面密钥环(Secret Service / keychain),需要安装缺失的 Secret Service 软件包,然后重启桌面会话。
GNOME 及其他基于 Secret Service 的桌面环境:
sudo apt install gnome-keyring libsecret-1-0 seahorse
KDE Plasma:
sudo apt install kwalletmanager
这条错误信息并非凭空而来,其来源在 src/services/cryptoservice.cpp:当 QKeychain::WritePasswordJob 写入密钥环超时或失败时,程序会记录该警告。底层原理如下:
- QOwnNotes 通过内置的
qtkeychain库(src/libraries/qtkeychain)访问桌面密钥环,用于安全保存笔记加密密钥等机密。 - detectKeychainAvailability() 会在 Linux 上额外通过 DBus 探测 Secret Service 是否真正可达——因为
QKeychain::isAvailable()只能判断 libsecret 库能否加载,无法判断是否存在可实际存储密钥的密钥环服务。 - 当检测到系统密钥环不可用时,QOwnNotes 会**自动回退到旧版加密(legacy encryption)**存储机密:
storeSecret()在写密钥环失败后调用legacyEncryptToString()(见 src/services/cryptoservice.cpp),并打印No system keychain is available, secrets will be stored with the legacy encryption。也就是说,即使不安装密钥环软件包,应用也不会崩溃,只是加密密钥的存储方式退化为旧方案。
因此,看到上述警告时,按你的桌面环境安装对应的 Secret Service 软件包并重启会话即可让密钥环恢复正常;若暂时无法安装,应用仍可通过旧版加密继续工作。
小结
QOwnNotes 在 Ubuntu 系发行版上的安装策略可以概括为三条原则:
- 能用 Qt6 就用 Qt6:Ubuntu 24.04+ / elementary OS / Linux Mint 22.1+ 直接使用
ppa:pbek/qownnotes-qt6安装,这是当前唯一持续更新的 APT 通道,且支持 ARM(Raspberry Pi)。 - 旧系统选 Qt5 PPA 或 OBS:Ubuntu 20.04+ 的旧系统可安装 Qt5 遗留最终包;Launchpad 已不覆盖的版本改用 OBS 仓库。
- 再老就用 AppImage:最老的一批发行版和衍生版直接下载 AppImage,配合
--portable还能随身携带全部笔记数据。
安装完成后如遇密钥环告警,按照本文提供的 GNOME / KDE 软件包列表补齐 Secret Service 组件并重启桌面会话即可。若需要从源码自行构建 QOwnNotes(含 Qt6 的 CMake 构建参数说明),可进一步阅读 webpage/src/installation/building.md 与 src/CMakeLists.txt。