• 桌面应用

QOwnNotes 是一款支持 Markdown 与待办事项管理的开源纯文本笔记软件，Funtoo Linux 的用户可以通过官方desktop-kit中自动生成的 Portage 软件包直接安装。本文以 webpage/src/installation/funtoo.md（及对应的波斯语译本 webpage/src/fa/installation/funtoo.md）为核心，完整讲解 emerge 安装步骤，并深入剖析安装后最常见的报错Could not write secret to keychain的成因与两种桌面环境下的修复方案，最后结合仓库源码解释 QOwnNotes 的密钥存储回退机制。读完本文，你将能够在 Funtoo Linux 上顺利安装并配置好 QOwnNotes 的加密密钥存储环境。

一、在 Funtoo Linux 上安装 QOwnNotes

Funtoo Linux 的 desktop-kit 软件仓库中提供了 QOwnNotes 的自动生成（autogenerated）软件包，位于app-office/qownnotes，可以直接通过 Funtoo 的包管理器 Portage 安装。

打开终端，执行以下命令：

sudo emerge -av qownnotes

命令参数说明：

• sudo：emerge 需要 root 权限安装系统软件包；
• -a（--ask）：在执行前询问确认，便于你核对将要安装的依赖与 USE 变更；
• -v（--verbose）：输出详细的安装信息，包括版本、USE 标志与依赖关系。

安装完成后，与其他发行版一致，在终端输入QOwnNotes即可启动程序（参见安装目录的通用说明 webpage/src/installation/README.md）。

提示：如果你在使用过程中遇到软件包或软件仓库本身的问题，可以在 QOwnNotes 的 Issues 页面反馈。Gentoo 用户（同为 Portage 系）则可以通过 webpage/src/installation/gentoo.md 中的 overlay 方式安装，两者的后续密钥链排查方法完全一致。

二、常见报错：Could not write secret to keychain

安装并首次启动 QOwnNotes 后，日志中如果出现如下提示：

Could not write secret to keychain

这通常意味着当前桌面会话中没有可用的系统密钥链服务（Secret Service），QOwnNotes 无法把密码、令牌等敏感信息安全地写入系统密钥链。此时需要安装缺失的 Secret Service 软件包，然后重启桌面会话。

2.1 GNOME 及其他基于 Secret Service 的桌面

对于 GNOME 以及其他基于 Secret Service（org.freedesktop.secrets）的桌面环境，安装以下软件包：

sudo emerge -av gnome-extra/gnome-keyring app-crypt/libsecret app-crypt/seahorse

• gnome-extra/gnome-keyring：GNOME Keyring，Secret Service 的实际守护进程；
• app-crypt/libsecret：Secret Service 的客户端库，Qt 的 qtkeychain 后端依赖它访问密钥链；
• app-crypt/seahorse：GNOME 的密钥管理图形界面，便于查看和管理已保存的密钥。

2.2 KDE Plasma 桌面

对于 KDE Plasma 桌面环境，安装 KWallet 相关软件包：

sudo emerge -av kde-apps/kwalletmanager kde-frameworks/kwallet

• kde-apps/kwalletmanager：KWallet 的管理工具；
• kde-frameworks/kwallet：KWallet 的框架库，提供密钥链服务（org.kde.kwalletd6/org.kde.kwalletd5）。

安装完成后，请注销并重新登录桌面会话（或重启系统），再启动 QOwnNotes。

2.3 密钥链不可用时的降级行为

官方文档同时明确说明：如果桌面密钥链不可用，QOwnNotes 会自动回退到旧式加密（legacy encryption）方式存储密钥。也就是说，即使你不安装上述软件包，QOwnNotes 仍然可以正常工作，只是敏感信息的存放方式从系统密钥链降级为应用自身的加密存储。

三、源码级原理解析：密钥链探测与回退机制

上述报错与降级行为并非黑盒，其完整逻辑可以在仓库的 src/services/cryptoservice.cpp 中逐行验证。

3.1 报错的产生位置

日志消息Could not write secret to keychain精确出现在 src/services/cryptoservice.cpp#L543：

} else if (!result.ok) { qWarning() << "Could not write secret to keychain:" << key << job->errorString(); }

这里writeSecret()通过 qtkeychain 的WritePasswordJob向系统密钥链写入密码，当任务返回失败（!result.ok）时输出告警。qtkeychain 作为内置库随项目一起构建，见 src/CMakeLists.txt#L162 的add_subdirectory(libraries/qtkeychain EXCLUDE_FROM_ALL)，以及 qmake 工程文件 src/QOwnNotes.pro#L40 的include(libraries/qtkeychain/qtkeychain.pri)。

3.2 写入失败后的自动降级

writeSecret()的调用方storeSecret()在写入失败时会自动切换到旧式加密，见 src/services/cryptoservice.cpp#L494-L506：

QString CryptoService::storeSecret(const QString &key, const QString &text) { if (writeSecret(key, text)) { return markerForKey(key); } // A missing keychain was already reported once in isKeychainAvailable() if (isKeychainAvailable()) { qWarning() << "Could not store secret in keychain, falling back to legacy encryption:" << key; } return legacyEncryptToString(text); }

其中legacyEncryptToString()使用项目内置的 SimpleCrypt 库进行加密，代码注释明确要求“与引入 qtkeychain 之前的 SimpleCrypt 存储格式保持兼容”，见 src/services/cryptoservice.cpp#L468-L476；SimpleCrypt 的加密密钥来自设置项cryptoKey，若不存在会在CryptoService构造函数中自动生成，见 src/services/cryptoservice.cpp#L204-L219。

3.3 密钥链可用性探测：D-Bus 服务名检查

为什么缺少 GNOME Keyring 或 KWallet 时 QOwnNotes 能“提前知道”密钥链不可用？关键在isKeychainAvailable()与isDBusSecretServiceReachable()的配合：

• src/services/cryptoservice.cpp#L408-L421：isKeychainAvailable()使用静态变量缓存探测结果，每次应用运行只探测一次；探测失败时同样输出告警No system keychain is available, secrets will be stored with the legacy encryption；
• src/services/cryptoservice.cpp#L139-L189：isDBusSecretServiceReachable()通过会话总线 D-Bus 检查以下服务是否已注册或可被激活：
  • org.freedesktop.secrets（Secret Service，对应 GNOME Keyring / libsecret）；
  • org.kde.kwalletd6、org.kde.kwalletd5（KWallet 各版本）。

代码注释还解释了为何需要这一层探测：QKeychain::isAvailable()在 Linux 上只检查 libsecret 库能否被加载，并不保证有真正能存储密钥的服务在运行（见 src/services/cryptoservice.cpp#L191-L201）。这也正是文档建议“安装缺失的 Secret Service 软件包并重启桌面会话”的原因——重启后 D-Bus 会话中才会出现对应的密钥链服务。

3.4 可调参数：密钥链超时

与密钥链相关的行为还有一个可调设置keychainTimeout，其默认值为 2 秒，且被强制限制在 1～120 秒之间，见 src/services/cryptoservice.cpp#L397-L402：

return qBound( 1, settings.value(QStringLiteral("keychainTimeout"), DefaultKeychainTimeout).toInt(), 120);

密钥链操作通过事件循环加定时器执行（src/services/cryptoservice.cpp#L78-L102），超时后不会阻塞界面。若你的桌面环境密钥链服务响应较慢，可以适当调大该值。

四、总结与验证清单

在 Funtoo Linux 上使用 QOwnNotes 的完整流程可归纳为三步：

1. 安装：sudo emerge -av qownnotes（软件包来自 desktop-kit 的app-office/qownnotes）；
2. 按桌面环境补齐密钥链：
   • GNOME 等 Secret Service 桌面：sudo emerge -av gnome-extra/gnome-keyring app-crypt/libsecret app-crypt/seahorse；
   • KDE Plasma：sudo emerge -av kde-apps/kwalletmanager kde-frameworks/kwallet；
   • 安装后重启桌面会话；
3. 验证：启动 QOwnNotes，观察日志中不再出现Could not write secret to keychain；即使密钥链不可用，QOwnNotes 也会按 src/services/cryptoservice.cpp 中实现的回退逻辑改用旧式加密存储，功能不受影响。

整体加密接口（encryptToString/decryptToString、密钥链引用与迁移）可进一步查阅 src/services/cryptoservice.h 了解全貌。

• 桌面应用