企业官网建设流程全解析

• 桌面应用

本文是一份面向 Gentoo Linux 用户的 QOwnNotes 实战安装指南。QOwnNotes 是一款基于纯文本文件的 Markdown 笔记与待办事项管理工具，并深度集成 Nextcloud / ownCloud 云同步。文章将带你通过官方的 qownnotes-overlay 仓库，使用emerge完成安装，同时深入讲解安装后可能遇到的Could not write secret to keychain报错的成因、对应各桌面环境的 Secret Service 包安装方案，以及其背后的密钥链（keychain）与旧版加密回退机制。

一、背景：为什么 Gentoo 上安装 QOwnNotes 使用 Overlay

QOwnNotes 的官方安装页面（webpage/src/installation/gentoo.md）为 Gentoo Linux 提供了专门的安装方式：通过 eselect-repository 启用 qownnotes-overlay 覆盖层。

与 Debian、Ubuntu 等使用预编译二进制包的发行版不同，Gentoo 采用源码构建（Portage）哲学，软件包通常需要从 ebuild 脚本编译安装。QOwnNotes 官方维护了一个专门的 Gentoo overlay 仓库（qownnotes/gentoo-overlay），其中存放了对应版本的 ebuild 文件，用户启用该 overlay 后即可用emerge以 Gentoo 的标准方式安装 QOwnNotes。

在仓库中还可以看到这个 overlay 的构建与维护脚本：build-systems/gentoo/build-for-gentoo.sh。该脚本从 QOwnNotes 源码仓库的最新main分支检出代码，从 src/version.h 提取版本号，生成qownnotes-<版本号>.tar.xz源码归档，并基于 build-systems/gentoo/qownnotes.ebuild 模板生成对应版本的 ebuild 与 Manifest（含 SHA512 校验值），再推送到 overlay 仓库。这意味着 overlay 中的 ebuild 与当前源码仓库始终保持同步，版本号直接取自 src/version.h。

二、安装前的准备：启用 eselect-repository

Gentoo 从 2016 年起（参考仓库中的博客 webpage/src/blog/2016-03-01-QOwnNotes-Gentoo-Linux-Overlay.md）即为 QOwnNotes 提供了官方 overlay。要使用它，首先要通过eselect-repository启用：

sudo eselect repository enable qownnotes-overlay

eselect-repository是 Gentoo 官方推荐的 overlay 管理工具（可通过app-eselect/eselect-repository包安装）。启用后，Portage 会在同步时自动拉取该 overlay 的仓库列表。

三、安装 QOwnNotes：emerge 命令详解

启用 overlay 后，就可以按照 Gentoo 的常规方式安装 QOwnNotes：

sudo emerge --sync qownnotes-overlay && sudo emerge -av qownnotes

这条命令分为两部分：

• sudo emerge --sync qownnotes-overlay：仅同步 qownnotes-overlay 仓库，将其中的 ebuild 与 Manifest 拉到本地，确保能获取到最新版本的 QOwnNotes ebuild。
• sudo emerge -av qownnotes：以验证模式（-a/--ask，会在安装前询问确认）安装app-office/qownnotes包。-v/--verbose会展示将要构建的 USE 标记、依赖关系等详细信息。

3.1 从 ebuild 看安装内容

通过阅读 build-systems/gentoo/qownnotes.ebuild，可以清晰了解这个包在 Gentoo 上的构建与安装行为：

值得注意的几点：

• 该 ebuild 基于Qt 6构建（eqmake6、qtbase-6.9:6），并且显式依赖app-crypt/libsecret——这正是后面 keychain 报错的关键依赖。
• 在src_prepare()阶段，ebuild 会向 release.h 写入#define RELEASE "Gentoo"，使构建产物标记为 Gentoo 版本。
• 安装内容包括：编译后的QOwnNotes可执行文件、languages/*.qm翻译文件（源码仓库中的多语言翻译见 src/languages）、多尺寸图标（128/16/24/256/32/48/512/64/96 及 scalable SVG，见 src/images/icons）以及 PBE.QOwnNotes.desktop 桌面入口。
• 由于 KEYWORDS 为~amd64 ~x86，若你的 profile 未包含对应测试关键字，可能需要按 Gentoo 惯例接受相应关键字（如向/etc/portage/package.accept_keywords添加app-office/qownnotes）。

3.2 包依赖与构建验证

ebuild 中列出的app-crypt/libsecret依赖与仓库其他发行版的打包信息一致：例如 Debian 的构建依赖中同样包含libsecret-1-dev（见 src/debian/control），源码构建层面也在 src/CMakeLists.txt 中通过pkg_check_modules(LIBSECRET libsecret-1)探测 libsecret。这说明libsecret 是 QOwnNotes 在 Linux 上访问系统密钥链的关键依赖，在 Gentoo 上由 ebuild 自动保证。

四、安装后的常见问题：Could not write secret to keychain

如果你在 QOwnNotes 中看到日志输出Could not write secret to keychain，说明系统中缺少可用的 Secret Service 实现（或该服务未运行）。

4.1 报错的源码成因

该错误信息来自 QOwnNotes 的加密服务模块 src/services/cryptoservice.cpp。核心逻辑如下：

• writeSecret()（src/services/cryptoservice.cpp#L527-L550）通过 QtKeychain 的QKeychain::WritePasswordJob写入密钥；当写入失败（job->error() != QKeychain::NoError）时，会输出qWarning() << "Could not write secret to keychain:" ...。
• 在写入之前，writeSecret()会先调用isKeychainAvailable()检查系统密钥链是否可用；若不可用则直接返回false，不执行写入（src/services/cryptoservice.cpp#L530-L532）。
• isKeychainAvailable()采用“每次运行只探测一次”的静态缓存，并会输出No system keychain is available, secrets will be stored with the legacy encryption的警告（src/services/cryptoservice.cpp#L408-L421）。
• 在 Linux 上，可用性探测分为两层：QKeychain::isAvailable()（检查 libsecret 库能否加载）之外，还会通过 D-Bus 探测org.freedesktop.secrets、org.kde.kwalletd6、org.kde.kwalletd5等服务是否已注册或可激活（见isDBusSecretServiceReachable()，src/services/cryptoservice.cpp#L139-L189）。这正是“光装了库还不够，桌面密钥服务本身必须可用”的源码级原因。

4.2 解决方案：安装 Secret Service 包并重启桌面会话

官方文档给出的解决办法是：安装缺失的 Secret Service 包，然后重启桌面会话。针对不同桌面环境，Gentoo 上对应的包如下：

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

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

其中：

• gnome-extra/gnome-keyring：提供 GNOME Keyring 守护进程，即org.freedesktop.secretsD-Bus Secret Service 的标准实现；
• app-crypt/libsecret：libsecret 客户端库，QOwnNotes 通过它访问 Secret Service API；
• app-crypt/seahorse：GNOME 的密钥管理 GUI，便于查看和管理已存储的密码。

KDE Plasma：

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

其中：

• kde-frameworks/kwallet：KDE Wallet（KWallet）框架，提供org.kde.kwalletd5/org.kde.kwalletd6D-Bus 服务；
• kde-apps/kwalletmanager：KWallet 的管理 GUI。

安装完成后，重启桌面会话（注销并重新登录）以确保密钥服务守护进程随会话启动——因为 QOwnNotes 的 D-Bus 探测发生在应用启动时，且isKeychainAvailable()的结果在一次运行内会被缓存。

4.3 无密钥链时的回退行为：旧版加密

官方文档明确指出：如果桌面密钥链不可用，QOwnNotes 将回退到旧版加密（legacy encryption）。

从源码可以确认这一行为：storeSecret()（src/services/cryptoservice.cpp#L494-L506）在密钥链不可用或写入失败时，返回legacyEncryptToString(text)，即使用 SimpleCrypt 算法进行本地加密存储（src/services/cryptoservice.cpp#L468-L471）。legacyEncryptToString的注释明确写着“Keep this compatible with the pre-qtkeychain SimpleCrypt storage format”，即与引入 QtKeychain 之前的存储格式保持兼容。

同时，CryptoService构造时（src/services/cryptoservice.cpp#L204-L220）会从设置中读取cryptoKey（若不存在则用QRandomGenerator生成并持久化），并基于它创建SimpleCrypt实例。而migrateSecrets()会在密钥链可用时，把旧版 SimpleCrypt 加密的密文迁移到系统密钥链（以secrets/开头的 key 引用存储），实现从旧版加密到密钥链的平滑过渡（相关逻辑见migrateSecret()，src/services/cryptoservice.cpp#L552-L594）。

因此，即便暂时不安装密钥服务，QOwnNotes 仍能正常工作，只是敏感数据（如云连接密码、脚本的加密变量）会以 SimpleCrypt 加密形式存放在本地，而非系统密钥链中。安装密钥服务并重启会话后，QOwnNotes 会重新探测并使用密钥链。

4.4 关于 keychainTimeout 的补充

密钥链读写是通过同步等待方式执行的，QOwnNotes 为此提供了一个可配置的超时（默认 2 秒，取值范围 1–120 秒），定义在 src/services/cryptoservice.cpp#L34 和keychainTimeout()（src/services/cryptoservice.cpp#L397-L402），并可在设置界面的“常规设置”中通过keychainTimeout旋钮调整（见 src/widgets/settings/generalsettingswidget.ui 与 src/widgets/settings/generalsettingswidget.cpp）。当密钥链服务无响应导致作业超时时，源码会输出Timed out writing secret to keychain等警告（src/services/cryptoservice.cpp#L540-L544）。如果桌面密钥服务启动缓慢，可适当调大该值。

五、小结

在 Gentoo Linux 上安装 QOwnNotes 的完整路径如下：

1. 用eselect-repository启用 qownnotes-overlay；
2. 同步 overlay 并用emerge -av qownnotes安装（ebuild 基于 Qt 6 构建，自动拉入 libsecret 依赖）；
3. 若出现Could not write secret to keychain，按桌面环境安装 Secret Service 实现（GNOME 系装 gnome-keyring + libsecret + seahorse；KDE 系装 kwalletmanager + kwallet），然后重启桌面会话；
4. 密钥链不可用期间，QOwnNotes 会自动回退到 SimpleCrypt 旧版加密，并在密钥链恢复后自动迁移密文。

安装完成后，建议进一步阅读仓库中的使用文档以掌握 QOwnNotes 的笔记、待办与 Nextcloud/ownCloud 同步能力：官方安装页面 webpage/src/installation/gentoo.md 及其他发行版安装文档见 webpage/src/installation。

• 桌面应用