企业官网建设流程全解析

• 桌面应用

QOwnNotes 是一款支持 Markdown 与 Nextcloud / ownCloud 集成的纯文本笔记与待办事项管理软件。本文围绕 webpage/src/installation/solus.md 这一安装文档展开，介绍在 Solus 发行版上通过官方维护的qownnotes软件包完成安装的完整流程，并结合仓库源码深入讲解安装后可能遇到的Could not write secret to keychain日志问题——即桌面 Secret Service 钥匙串缺失时的表现、修复方法，以及 QOwnNotes 底层如何优雅回退到传统加密存储。

读完本文，你将能够在 Solus 上快速安装 QOwnNotes、正确补齐桌面钥匙串依赖（GNOME 与 KDE Plasma 两套方案），并理解 QOwnNotes 密钥存储架构的工作原理。

Solus 官方仓库中的 qownnotes 软件包

Solus 发行版使用自研的eopkg包管理器，软件包由 Solus Project 官方仓库维护。QOwnNotes 在 Solus 仓库中的软件包名为qownnotes，与发行版软件源保持同步更新，安装后即可获得与系统 Qt 环境匹配的版本。

由于该软件包由 Solus Project 官方维护，因此无需像其他发行版那样手动添加第三方 OBS 仓库或信任签名密钥，直接通过软件源安装即可。

使用 eopkg 安装 QOwnNotes

在终端中执行以下命令：

sudo eopkg install qownnotes

eopkg 会解析依赖并自动安装 QOwnNotes 所需的运行库。安装完成后，在应用菜单中找到 QOwnNotes，或在终端中直接输入命令启动：

QOwnNotes

关于 QOwnNotes 在其他发行版上的安装方式（如 Debian/Ubuntu 的 apt、Arch 的 pacman、Snap 等），可参考 webpage/src/installation/README.md 与同目录下的各发行版安装文档。

处理 "Could not write secret to keychain" 日志

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

Could not write secret to keychain

这表示 QOwnNotes 尝试把密码、API 密钥等敏感信息写入操作系统的桌面钥匙串（Secret Service）时失败。该日志的确切输出位置在源码 src/services/cryptoservice.cpp 中，由writeSecret()在QKeychain::WritePasswordJob返回失败时通过qWarning()打印：

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

为什么会发生：底层密钥存储架构

QOwnNotes 的密钥存储由 CryptoService 负责，其 Linux 端实现基于QtKeychain（仓库内置子模块 src/libraries/qtkeychain）与libsecret。从构建配置可以确认这一点：

• src/CMakeLists.txt 通过pkg_check_modules(LIBSECRET libsecret-1)探测 libsecret；
• src/debian/control 的Build-Depends声明了libsecret-1-dev，运行时依赖包含libsecret-1-0。

QtKeychain 在 Linux 上依赖 libsecret 访问桌面环境的 Secret Service 守护进程。值得注意的是，QOwnNotes 对"钥匙串是否可用"的检测比单纯的库加载更严格：源码 src/services/cryptoservice.cpp 中的detectKeychainAvailability()会先通过 D-Bus 探测org.freedesktop.secrets（GNOME Keyring）或org.kde.kwalletd6/org.kde.kwalletd5（KWallet）服务是否已注册或可被激活（见 isDBusSecretServiceReachable），只有 D-Bus 探测通过并且QKeychain::isAvailable()为真时，才认定系统钥匙串可用。

因此，当 Solus 系统上缺少 Secret Service 相关组件（例如未安装 gnome-keyring、libsecret，或桌面会话未启动钥匙串守护进程）时，写入操作就会失败并打印上述警告。

修复方案一：GNOME 及其他基于 Secret Service 的桌面

如果使用的是 GNOME 或其他基于 Secret Service 的桌面环境，请安装以下三个软件包：

sudo eopkg install gnome-keyring libsecret seahorse

• gnome-keyring：提供org.freedesktop.secrets的 D-Bus Secret Service 实现，是 QtKeychain 在 Linux 上写入密钥的后端；
• libsecret：QtKeychain 所依赖的客户端库，用于访问 Secret Service API；
• seahorse：GNOME 的钥匙串图形管理工具，可用于查看、解锁和整理已保存的密码。

安装完成后，需要重新启动桌面会话（重新登录），让 gnome-keyring 守护进程随会话正常启动并解锁。

修复方案二：KDE Plasma

如果使用的是 KDE Plasma 桌面，则应从已配置的软件源中安装 KWallet 支持（例如kwalletmanager等 KWallet 相关软件包）：

sudo eopkg install kwalletmanager kwallet

KWallet 通过org.kde.kwalletd5/org.kde.kwalletd6D-Bus 服务提供密钥存储，QOwnNotes 的 D-Bus 探测逻辑会同时识别这些服务名（见 src/services/cryptoservice.cpp）。

验证与启动

安装完成后重启桌面会话，重新启动 QOwnNotes，日志中的Could not write secret to keychain警告即应消失。首次写入密钥时，系统可能会弹出解锁钥匙串（或 KWallet）的授权提示，输入桌面会话密码即可。

钥匙串不可用时的回退机制：传统加密

如果系统钥匙串确实不可用（例如在无桌面环境的服务器场景），QOwnNotes不会拒绝运行，而是会自动回退到传统加密存储。这一点在原文档中明确说明，并且源码提供了完整的实现证据。

检测与回退流程

启动时，CryptoService::isKeychainAvailable() 会在本次运行期间只检测一次钥匙串可用性；若不可用，会打印：

No system keychain is available, secrets will be stored with the legacy encryption

随后 storeSecret() 在writeSecret()失败时，将密钥内容改用SimpleCrypt（传统加密）处理后存储：

QString CryptoService::storeSecret(const QString &key, const QString &text) { if (writeSecret(key, text)) { return markerForKey(key); } // ... return legacyEncryptToString(text); }

legacyEncryptToString()使用仓库内置的 src/libraries/simplecrypt/simplecrypt.h 实现，并保持与早期版本 SimpleCrypt 存储格式的兼容（见 src/services/cryptoservice.cpp）。

密钥迁移：从传统加密到系统钥匙串

当系统补装钥匙串组件后，QOwnNotes 会在启动阶段自动将旧的传统加密密钥迁移到系统钥匙串中。CryptoService::migrateSecrets() 依次迁移三类密钥：

1. 设置项密钥（migrateSettingsSecrets）：包括代理密码、ownCloud 密码、CalDAV 待办日历密码、AI API 密钥等（见 encryptedSettingsKeys）；
2. 云连接密码（migrateCloudConnectionSecrets）：迁移磁盘数据库中cloudConnection表的密码字段；
3. 脚本密钥（migrateScriptSecrets）：迁移脚本设置中以!前缀标记为密钥的变量。

迁移前，如果检测到存在旧的传统加密密钥且系统钥匙串可用，QOwnNotes 会弹出一个提示框，说明需要将已保存的密码和 API 密钥移动到操作系统的安全凭据存储中，并提示"系统可能会多次要求你解锁钥匙串，这是预期行为，QOwnNotes 不会获取你的钥匙串密码"（见 src/main.cpp）。

迁移后的存储形态

迁移完成后，设置中的密钥值会变成以qtkeychain:为前缀的引用标记（KeychainMarkerPrefix，见 src/services/cryptoservice.cpp），真正的密钥内容保存在系统钥匙串中。读取时，decryptToString() 会先判断值是否为钥匙串引用，是则从钥匙串读取，否则走传统解密路径。

这套设计保证了：有钥匙串时优先使用操作系统级安全存储，没有钥匙串时功能照常可用（只是密钥落盘强度较弱），并且在环境改善后可以无缝迁移，这正是 Solus 上处理该警告的正确姿势——补装组件、重启会话，让 QOwnNotes 自动完成迁移，而不是忽略或掩盖警告。

小结

相关参考资源：

• 安装文档原文：webpage/src/installation/solus.md
• 密钥存储实现：src/services/cryptoservice.cpp 与 src/services/cryptoservice.h
• 启动迁移与提示逻辑：src/main.cpp
• 构建期 libsecret 探测：src/CMakeLists.txt
• 其他发行版安装方式：webpage/src/installation/README.md

• 桌面应用