QOwnNotes 在 Debian 上的官方安装指南：OBS 仓库 apt 源配置、Qt6 版本说明与 keychain 故障排查

本文以官方安装文档 webpage/src/installation/debian.md 为主体，完整给出 QOwnNotes 在 Debian Unstable / 13 / 12 / 11 / 10 各版本上通过 Open Build Service（OBS）官方仓库使用 apt 安装的逐步命令，逐条解释每条命令与参数的真实含义，并深入 src/services/cryptoservice.cpp 源码，说明系统 keychain（密钥环）不可用时 QOwnNotes 如何回退到旧式加密。读完本文，你可以在任意 Debian 版本上独立完成官方仓库的信任、源添加、安装与后续故障排查。

QOwnNotes 与 Debian 安装的总体背景

QOwnNotes 是一款以纯文本文件为存储格式的 Markdown 笔记与待办事项管理工具，内置 Nextcloud / ownCloud 同步集成。项目官方并不通过 Debian 主仓库发布软件包，而是通过 Open Build Service（OBS） 的 home:pbek:QOwnNotes 项目，为每个 Debian 版本维护独立子仓库，再以 apt 源的形式提供给用户。仓库内 obs/_service、obs/qownnotes.spec 等文件即为 OBS 打包与构建配置，其中 qownnotes.spec 声明了 Name: qownnotes 与 Group: System/GUI/Productivity 等打包元数据。

各 Debian 版本对应的 OBS 仓库路径如下：

Debian 版本	OBS 子仓库	构建所用的 Qt 主版本
Debian Unstable	Debian_Unstable	Qt6
Debian 13.0	Debian_13	Qt6
Debian 12.0	Debian_12	Qt6
Debian 11.0	Debian_11	Qt5（至少 5.11）
Debian 10.0	Debian_10	Qt5（至少 5.8）

说明：Debian_Unstable、Debian_13、Debian_12 三个仓库的软件包均以 Qt6 构建；Debian_11、Debian_10 则仍基于 Qt5。仓库源码 src/QOwnNotes.pro 中也保留了 Qt5 / Qt6 双构建的兼容逻辑。

安装前置条件

开始之前请确认系统满足以下条件：

• 已安装 curl、gpg、sudo、apt 等基础工具（Debian 默认均具备）；
• 拥有 sudo 权限，以下命令均需要 root 权限写入系统目录；
• 网络可访问 OBS 的下载域（download.opensuse.org）；
• 注意：OBS 仓库签名密钥存在有效期，文档明确提示「密钥过期时可能需要重复执行信任步骤」。

核心机制：为什么要「信任密钥 + 添加源」两步走

QOwnNotes 的 Debian 安装遵循现代 apt 仓库的标准两步流程，理解其原理有助于排错：

1. 信任仓库签名密钥：OBS 用 GPG 密钥对仓库的 Release 文件签名，apt 只有信任该密钥才能校验包列表的完整性。现代 Debian（11 及以上）推荐将密钥去装甲（dearmor）为二进制 keyring 文件存放在 /etc/apt/keyrings/，并通过源条目中的 signed-by= 显式指定，避免将密钥加入全局信任集。
2. 添加软件源并安装：在 /etc/apt/sources.list.d/ 下写入指向 OBS 子仓库的 deb 条目，随后 apt update 刷新索引，apt install qownnotes 完成安装。

其中几个关键点值得展开：

• gpg --dearmor：将文本格式（ASCII armored）的 Release.key 转换为二进制 keyring，这是现代 apt 推荐的做法；
• arch=${ARCHITECTURE}：通过 dpkg --print-architecture 自动探测当前系统架构（如 amd64），写入源条目后 apt 只会使用匹配当前架构的包；
• signed-by=${SIGNED_BY}：把仓库签名校验绑定到上一步生成的 keyring 文件，是 apt-key 时代之后的推荐安全实践；
• chmod u=rw,go=r：确保 keyring 文件权限为「属主可读写、其他用户只读」，避免被任意用户篡改。

分版本安装步骤

Debian Unstable

第一步：信任仓库密钥

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
sudo mkdir -p "$(dirname "${SIGNED_BY}")"
curl --silent --show-error --location http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_Unstable/Release.key | gpg --dearmor | sudo tee "${SIGNED_BY}" > /dev/null
sudo chmod u=rw,go=r "${SIGNED_BY}"

第二步：添加仓库并安装

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
ARCHITECTURE="$(dpkg --print-architecture)"
echo "deb [arch=${ARCHITECTURE} signed-by=${SIGNED_BY}] http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_Unstable/ /" | sudo tee /etc/apt/sources.list.d/qownnotes.list > /dev/null
sudo apt update
sudo apt install qownnotes

提示：此软件包以 Qt6 构建。OBS 对应仓库页面也提供 .deb 的直接下载入口。

Debian 13.0

第一步：信任仓库密钥

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
sudo mkdir -p "$(dirname "${SIGNED_BY}")"
curl --silent --show-error --location http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_13/Release.key | gpg --dearmor | sudo tee "${SIGNED_BY}" > /dev/null
sudo chmod u=rw,go=r "${SIGNED_BY}"

第二步：添加仓库并安装

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
ARCHITECTURE="$(dpkg --print-architecture)"
echo "deb [arch=${ARCHITECTURE} signed-by=${SIGNED_BY}] http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_13/ /" | sudo tee /etc/apt/sources.list.d/qownnotes.list > /dev/null
sudo apt update
sudo apt install qownnotes

提示：此软件包以 Qt6 构建。OBS 对应仓库页面也提供 .deb 的直接下载入口。

Debian 12.0

第一步：信任仓库密钥

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
sudo mkdir -p "$(dirname "${SIGNED_BY}")"
curl --silent --show-error --location http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_12/Release.key | gpg --dearmor | sudo tee "${SIGNED_BY}" > /dev/null
sudo chmod u=rw,go=r "${SIGNED_BY}"

第二步：添加仓库并安装

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
ARCHITECTURE="$(dpkg --print-architecture)"
echo "deb [arch=${ARCHITECTURE} signed-by=${SIGNED_BY}] http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_12/ /" | sudo tee /etc/apt/sources.list.d/qownnotes.list > /dev/null
sudo apt update
sudo apt install qownnotes

提示：此软件包以 Qt6 构建。OBS 对应仓库页面也提供 .deb 的直接下载入口。

Debian 11.0

第一步：信任仓库密钥

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
sudo mkdir -p "$(dirname "${SIGNED_BY}")"
curl --silent --show-error --location http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_11/Release.key | gpg --dearmor | sudo tee "${SIGNED_BY}" > /dev/null
sudo chmod u=rw,go=r "${SIGNED_BY}"

第二步：添加仓库并安装

SIGNED_BY='/etc/apt/keyrings/qownnotes.gpg'
ARCHITECTURE="$(dpkg --print-architecture)"
echo "deb [arch=${ARCHITECTURE} signed-by=${SIGNED_BY}] http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_11/ /" | sudo tee /etc/apt/sources.list.d/qownnotes.list > /dev/null
sudo apt update
sudo apt install qownnotes

提示：如果你将本仓库用于其他 Debian Linux 版本，请确保系统 Qt 版本至少为 5.11。

Debian 10.0

Debian 10（Buster）仍属于 apt-key 时代，官方文档采用旧式密钥信任方式，其余步骤与新版一致：

第一步：信任仓库密钥

wget http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_10/Release.key -O - | sudo apt-key add -

第二步：添加仓库并安装

sudo bash -c "echo 'deb http://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Debian_10/ /' >> /etc/apt/sources.list.d/qownnotes.list"
sudo apt-get update
sudo apt-get install qownnotes

提示：如果你将本仓库用于其他 Debian Linux 版本，请确保系统 Qt 版本至少为 5.8。

命令与参数逐项解读

下表汇总了上述命令中的关键变量与参数，便于你在自定义路径或排查问题时灵活调整：

变量 / 参数	含义	说明
SIGNED_BY	keyring 文件的存放路径	约定为 /etc/apt/keyrings/qownnotes.gpg，可自定义，但需保持两段命令一致
dirname "${SIGNED_BY}"	取路径所在目录	用于 mkdir -p 创建 /etc/apt/keyrings/
gpg --dearmor	将 ASCII 密钥转为二进制 keyring	现代 apt 推荐做法，替代直接信任 ASCII 密钥
tee "${SIGNED_BY}"	将密钥写入文件	配合 > /dev/null 抑制屏幕输出
chmod u=rw,go=r	设置 keyring 权限	属主读写、组与其他用户只读
ARCHITECTURE	当前系统架构	由 dpkg --print-architecture 自动探测，如 amd64、arm64
deb [arch=... signed-by=...] URL /	源条目	arch= 限定架构，signed-by= 绑定签名密钥，结尾 / 为仓库根目录
tee /etc/apt/sources.list.d/qownnotes.list	写入独立源文件	与 apt-key 全局信任不同，密钥作用域仅限该源
apt update	刷新软件包索引	出现 NO_PUBKEY 错误时说明密钥未正确导入
apt install qownnotes	安装软件包	Debian 10 使用 apt-get install 写法，效果相同

安装完成后的验证与日常维护

安装完成后，可以通过以下方式验证安装结果：

• 检查包版本：apt list -a qownnotes；
• 启动应用：桌面菜单中找到 QOwnNotes，或终端执行 qownnotes；
• 在「关于」对话框中核对版本号，例如当前仓库 src/version.h 中记录的版本为 26.10.3，OBS 各仓库构建的软件包版本会随上游发布节奏同步更新（历史版本可参阅 CHANGELOG.md）。

日常维护注意两点：

1. 密钥过期：OBS 签名密钥存在有效期，当 apt update 报 GPG 签名错误（如 The following signatures couldn't be verified）时，重新执行对应版本的「第一步：信任仓库密钥」即可；
2. 升级：QOwnNotes 不随 Debian 主仓库更新，需持续依赖本 apt 源，通过 sudo apt update && sudo apt upgrade 获取新版本。

常见问题：Could not write secret to keychain

在无桌面密钥环服务（Secret Service）的环境下启动 QOwnNotes，日志中可能出现 Could not write secret to keychain 提示。官方文档给出的处理方式如下：

• GNOME 及其他基于 Secret Service 的桌面环境：

sudo apt install gnome-keyring libsecret-1-0 seahorse

• KDE Plasma：

sudo apt install kwalletmanager

安装缺失的 Secret Service 软件包后，重新启动桌面会话即可让密钥环生效。

源码层面的回退机制

这一提示背后是 QOwnNotes 明确的降级策略，可从 src/services/cryptoservice.cpp 得到印证：

• writeSecret() 在写入前先检查密钥环是否可用：若不可用直接返回失败（见 src/services/cryptoservice.cpp#L527-L532）；
• isKeychainAvailable() 在每次程序运行中只探测一次，探测失败会输出警告「No system keychain is available, secrets will be stored with the legacy encryption」（见 src/services/cryptoservice.cpp#L408-L421）；
• storeSecret() 在写入失败且密钥环确实不可用时，输出 Could not store secret in keychain, falling back to legacy encryption，并调用 legacyEncryptToString() 改用旧式加密存储（见 src/services/cryptoservice.cpp#L494-L506）；
• 旧式加密基于 SimpleCrypt 实现，其存储格式与引入 qtkeychain 之前的版本保持兼容（见 src/services/cryptoservice.cpp#L468-L474）；
• 当密钥环恢复可用后，QOwnNotes 在启动时检测到遗留的旧式加密密钥，会自动执行迁移（见 src/main.cpp#L442）。

也就是说：即使完全没有配置桌面密钥环，QOwnNotes 也能正常运行，只是密钥会被降级存储在旧式加密格式中；补齐 Secret Service 依赖并重启会话后即可享受系统密钥环保护。

从源码看 Debian 包的运行依赖

OBS 构建出的 Debian 包依赖与源码中的打包清单一致，可参考 src/debian/control：

• 运行依赖（Depends）包含 libqt5core5a、libqt5gui5、libqt5sql5-sqlite、libqt5widgets5、libqt5qml5、libqt5svg5、libqt5network5、libqt5xml5、libqt5websockets5、libqt5x11extras5 等 Qt5 组件，以及 libsecret-1-0（Secret Service 客户端库）和 openssl（加密/网络基础库）；
• 构建依赖（Build-Depends）同样包含 libsecret-1-dev、qtbase5-dev、libqt5websockets5-dev 等，说明打包环境与运行依赖一一对应。

对照 obs/qownnotes.spec 可以看到 OBS 构建时同样声明了 pkgconfig(libsecret-1) 与 Qt5 各模块，验证了密钥环支持是官方打包中明确保障的依赖项。对于 Qt6 构建的 Debian 12/13/Unstable 包，依赖则对应 Qt6 模块，安装时 apt 会自动解析。

延伸阅读

• 官方英文安装文档：webpage/src/installation/debian.md
• 其他发行版安装指南：Ubuntu、Fedora、Arch Linux、openSUSE、Raspberry Pi OS
• 通用 AppImage 安装方式：webpage/src/installation/appimage.md
• 加密与密钥环实现源码：src/services/cryptoservice.cpp、src/services/cryptoservice.h
• OBS 打包配置：obs/qownnotes.spec、obs/_service