在 Raspberry Pi OS 上安装 QOwnNotes：官方 OBS apt 仓库配置、版本对照与密钥链故障排查指南

QOwnNotes 通过 Open Build Service（OBS）为 Raspberry Pi OS（含旧称 Raspbian）维护了独立的 apt 软件仓库，覆盖 Raspberry Pi OS 12、11、10 与 Raspbian 9.0 四个版本分支，为树莓派 ARM 设备提供原生的 Debian 系二进制安装包。本文基于仓库官方安装文档（见 英文原版安装文档），完整给出各版本的仓库信任、源配置与安装命令，并结合源码解析安装后可能遇到的 "Could not write secret to keychain" 错误及其底层加密回退机制，帮助你在树莓派上一步到位完成部署与排障。

为什么树莓派需要独立的软件仓库

QOwnNotes 的 Linux 安装包主要由两个渠道提供：面向 Ubuntu 等桌面发行版的 PPA 仓库，以及面向更广泛发行版的 OBS（Open Build Service）仓库。树莓派之所以需要专门配置 OBS 仓库，原因在于两点：

1. 架构差异：树莓派运行的是 ARM 架构，而多数桌面仓库默认只构建 x86/x86_64 包；OBS 的 Raspbian_* 仓库针对树莓派的 Debian 派生系统构建了 ARM 版二进制包。
2. 发行版差异：Raspberry Pi OS（早期名为 Raspbian）虽然基于 Debian，但其软件源结构与上游 Debian 并不完全一致，不能直接套用 Debian 仓库地址。

仓库同步脚本 build-systems/obs/cmake-qt6/sync-obs-repositories.sh 中明确将 Raspbian_12、Raspbian_13 列入 Qt6 构建目标仓库列表，说明树莓派仓库与主构建流程一起在持续维护。而 CHANGELOG.md 的版本记录也印证了这一演进脉络：24.7.2 版本新增 Raspberry Pi OS 12 软件仓库，21.11.11 版本新增 Raspberry Pi OS 11 软件仓库。

补充：Ubuntu 安装文档（见 Ubuntu 安装文档）同样提到 PPA 仓库中包含 ARM 包，可在树莓派上使用；本文聚焦 OBS 的 Raspbian 仓库这一官方推荐路径。

安装前置准备

• 系统为 Raspberry Pi OS（或 Raspbian），可通过 cat /etc/os-release 确认版本代号，据此选择下方对应章节。
• 需要具有 sudo 权限的账户；文档命令使用 sudo 逐条执行。
• 树莓派需联网，能访问 download.opensuse.org。

Raspberry Pi OS 12

在终端中执行以下命令，导入并信任仓库签名密钥：

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

然后写入 apt 源、刷新索引并安装：

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

第一条命令把仓库地址追加到独立文件 /etc/apt/sources.list.d/qownnotes.list（而不是直接改动主 sources.list），这样卸载时只需删除该文件即可干净移除源。三行命令分别对应：信任密钥、注册源、安装软件。

Raspberry Pi OS 11

信任仓库密钥：

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

添加仓库并安装：

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

Raspberry Pi OS 10

信任仓库密钥：

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

添加仓库并安装：

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

Raspbian 9.0

信任仓库密钥：

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

添加仓库并安装：

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

版本对照速查表

系统版本	对应 OBS 仓库目录	注意事项
Raspberry Pi OS 12	Raspbian_12	当前主推版本，在 CHANGELOG.md 24.7.2 中新增；同步脚本 sync-obs-repositories.sh 同时启用了 Raspbian_13 目标
Raspberry Pi OS 11	Raspbian_11	在 CHANGELOG.md 21.11.11 中新增
Raspberry Pi OS 10	Raspbian_10	基于 Debian 10，适合仍运行 Buster 的老设备
Raspbian 9.0	Raspbian_9.0	基于 Debian 9，属于较老分支，仅建议存量系统使用

如果安装过程中 apt 提示密钥问题或找不到软件包，请先核对系统版本与所选仓库目录是否匹配。此外，官方文档同时提供了各版本对应的直接下载页面（可直接从对应 OBS 仓库目录下载 .deb 安装包），适合不方便配置软件源或需要离线安装的场景：使用浏览器或 wget 打开对应版本仓库目录，选择 qownnotes_*_armhf.deb（或对应架构的 deb 包），随后用 sudo dpkg -i 包名.deb 安装。

常见故障：Could not write secret to keychain

安装完成后首次运行 QOwnNotes，日志中可能出现：

Could not write secret to keychain

这表示系统缺少可用的 Secret Service（密钥链服务），导致应用无法把加密口令等机密数据写入桌面密钥链。官方文档给出的处理方式是安装缺失的密钥链软件包，然后重启桌面会话。

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

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

KDE Plasma 桌面环境：

sudo apt install kwalletmanager

源码层面的回退机制

这个故障提示并非简单的报错，背后是一套设计完善的降级策略，实现在 加密服务源码 中：

• 应用启动后会检查系统密钥链是否可用：CryptoService::isKeychainAvailable()（cryptoservice.cpp#L408-L421）在一次运行中只探测一次，若不可用则记录警告 No system keychain is available, secrets will be stored with the legacy encryption。
• 在 Linux 上，可用性探测（cryptoservice.cpp#L191-L201）不仅检查 libsecret 库能否被加载，还会通过 D-Bus 探测是否存在可以实际存储机密的 Secret Service 实现——这就是为什么文档要求安装 gnome-keyring（提供 Secret Service）与 libsecret-1-0（提供客户端库）两个层面的软件包。
• 写入机密时（writeSecret 实现），如果密钥链不可用或写入超时/失败，会打印 Could not write secret to keychain，随后调用方通过 storeSecret 实现 自动回退到 legacy 加密：即使用基于 SimpleCrypt 的旧式加密方式将机密保存在本地设置中。
• 回退的加密实现（legacyEncryptToString / legacyDecryptToString）明确保持了与引入 qtkeychain 之前旧格式的兼容性，因此即使没有桌面密钥链，QOwnNotes 依然可以正常工作，只是机密存储强度低于系统密钥链。
• 等待密钥链响应的超时时间可通过设置项 keychainTimeout 调整，取值范围被限制在 1~120 秒之间，默认 2 秒（cryptoservice.cpp#L397-L402）。
• 从打包层面看，OBS 的 RPM 构建描述 obs/qownnotes.spec 也将 libsecret-1 列为构建依赖，进一步印证密钥链（Secret Service）是官方发行包的组成部分。

因此，遇到该提示时优先按上文安装 gnome-keyring 或 kwalletmanager 并重启桌面会话；若出于某种原因密钥链始终不可用，QOwnNotes 也会透明地回退到 legacy 加密，不影响基本使用。

安装验证与日常更新

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

# 查看安装的版本
apt-cache policy qownnotes

# 或从命令行启动应用
qownnotes

后续版本更新只需常规执行：

sudo apt-get update
sudo apt-get upgrade qownnotes

即可从 OBS 仓库获取最新版本。若需彻底移除仓库源，删除 /etc/apt/sources.list.d/qownnotes.list 后再执行 sudo apt-get update 即可，应用本体可用 sudo apt-get remove qownnotes 卸载。

小结

在树莓派上安装 QOwnNotes 的正确姿势是：按系统版本选择对应的 Raspbian_* OBS 仓库 → 信任 Release.key → 写入独立源文件 → apt 安装。本文覆盖的 Raspberry Pi OS 12/11/10 与 Raspbian 9.0 四个分支的命令均可直接复制执行；若遇到密钥链写入失败，先补装 Secret Service 软件包并重启桌面会话，同时理解源码中的 SimpleCrypt 回退机制有助于判断系统状态。对于需要更多发行版安装方式的读者，可进一步参考仓库内的 Ubuntu 安装文档 与 AppImage 安装说明（若存在），树莓派与桌面端可以共用同一套笔记数据，通过 Nextcloud/ownCloud 同步。