QOwnNotes 的 QOwnNotesAPI 应用：在 Nextcloud / ownCloud 上恢复已删除笔记与历史版本

• 桌面应用

本篇技术指南介绍 QOwnNotes 与服务器端配套应用QOwnNotesAPI的协作机制：它专门为 QOwnNotes 提供两类「补救能力」——访问已删除（回收站）笔记与笔记历史版本。你将了解如何在 Nextcloud / ownCloud 服务器上安装启用该应用、在 QOwnNotes 客户端中完成云连接配置与连接测试，以及从源码层面看清其 REST API 端点的真实调用链与恢复流程。

QOwnNotesAPI 是什么

QOwnNotes 本身是一个以纯文本 Markdown 文件为核心的笔记与待办事项管理工具（项目描述见 README.md），通过 Nextcloud / ownCloud 实现云同步。而QOwnNotesAPI是部署在 Nextcloud / ownCloud 服务器上的一款配套应用（app），它的职责非常单一：为 QOwnNotes 客户端提供访问回收站中的已删除笔记和笔记历史版本的通道。

它的定位可以从客户端源码中直观确认：在 src/services/cloudservice.cpp 中，所有 QOwnNotesAPI 相关请求都挂在统一的根路径之下：

const QString CloudService::rootPath = QStringLiteral("/index.php/apps/qownnotesapi/api/v1/");

也就是说，QOwnNotes 与 QOwnNotesAPI 的全部交互都发生在服务器 Web 应用目录/index.php/apps/qownnotesapi/api/v1/这一组 HTTP 接口上，格式固定为json（见同文件 src/services/cloudservice.cpp 的CloudService::format常量）。

QOwnNotesAPI 能做什么

• 访问你已删除的笔记：即回收站（trash）功能，可以查看被删除到服务器回收站的笔记；
• 访问你的笔记版本：即历史版本（versions）功能，可以查看并恢复某个笔记的历史内容。

QOwnNotesAPI 不做什么

明确的功能边界同样写在官方入门文档中（英文原文见 webpage/src/getting-started/qownnotesapi.md）：

• 不同步你的笔记：笔记同步请使用 ownCloud / Nextcloud 官方同步客户端；
• 不负责笔记分享：分享功能直接由 ownCloud / Nextcloud 自身的 API 完成；
• 不访问 Nextcloud Text 中的图片：图片访问直接通过 Nextcloud API 完成。

因此 QOwnNotesAPI 是「锦上添花」的数据恢复组件，而非同步链路的一部分。作为佐证，客户端源码中笔记分享走的是OCS v2的 files_sharing 接口（src/services/cloudservice.cpp），任务（todo）则直接通过 CalDAV 访问（src/services/cloudservice.cpp），这两者都不依赖 QOwnNotesAPI。

在 Nextcloud / ownCloud 服务器上安装并启用

官方文档给出的启用方式非常直接：在服务器管理界面的应用（Apps）页面搜索qownnotes并安装即可。

具体来说，打开你的云服务管理后台：

https://<your-cloud-domain>/settings/apps

在应用市场搜索qownnotes，找到 QOwnNotesAPI 应用并启用。它同时支持两大云平台：Nextcloud 应用商店与 ownCloud 应用市场均有对应分发。

提示：QOwnNotes 客户端在云连接配置中会检测服务器上 QOwnNotesAPI 的版本，并提示升级到不低于最低版本的要求。该最低版本在客户端源码中被硬编码为0.4.2（src/services/cloudservice.h）：

#define QOWNNOTESAPI_MIN_VERSION "0.4.2"

如果服务器上的应用版本过低，客户端会弹出警告：「请考虑升级你服务器上的 QOwnNotesAPI 应用，当前版本过低可能会在 QOwnNotes 中引发问题」（对应checkAppVersion逻辑，见 src/services/cloudservice.cpp）。

客户端云连接配置

在 QOwnNotes 端，需要保证：

1. 云支持已在设置中开启——源码中对应配置项ownCloud/supportEnabled（src/services/cloudservice.cpp）；
2. 当前笔记文件夹关联了某个云连接（CloudConnection），而不是特殊的 "None" 连接；
3. 在云连接的设置界面勾选启用 QOwnNotesAPI 检测（对应CloudConnection::getAppQOwnNotesAPIEnabled()，见 src/services/cloudservice.cpp）。

云设置界面本身位于 src/widgets/settings/cloudsettingswidget.ui，其中包含一段提示文字：需要在你自己的 Nextcloud / ownCloud 服务器上安装最新版 QOwnNotesAPI（至少QOWNNOTESAPI_MIN_VERSION版本），QOwnNotes 才能访问笔记版本与已删除笔记。运行时该占位符会被替换为真实版本号（src/widgets/settings/cloudsettingswidget.cpp）。

连接测试与 App 信息探测

在云设置页面点击连接测试时，QOwnNotes 会向 QOwnNotesAPI 的note/app_info端点发起请求（src/services/cloudservice.cpp），并在checkAppInfo中解析返回的 JSON（src/services/cloudservice.cpp）。从解析逻辑可以还原出该端点的响应字段：

请求时会携带format=json与当前笔记目录路径notes_path查询参数。认证方面，所有请求都通过addAuthHeader注入 HTTP Basic 认证头，并额外携带OCS-APIRequest: true与自定义 User-Agent（src/services/cloudservice.cpp）。

核心功能一：笔记历史版本（Versions）

触发入口

在主窗口中执行「显示版本」动作时，QOwnNotes 首先校验当前笔记存在且当前笔记文件夹已绑定云连接，随后调用CloudService::loadVersions()并把当前笔记的相对路径作为file_name参数传给服务器（src/mainwindow.cpp）。

底层请求由loadVersions发出（src/services/cloudservice.cpp）：

GET {serverUrl}/index.php/apps/qownnotesapi/api/v1/note/versions ?format=json &file_name={服务器端笔记路径}

响应解析

响应到达后，由handleVersionsLoading处理（src/services/cloudservice.cpp）：

• 对返回的 JSON 先包裹成数组再交给 QJSEngine 解析；
• 若返回message字段（错误信息）则弹出服务器错误提示；
• 若缺少file_name或versions为空，则提示「该笔记没有版本，或服务器上未找到该笔记」；
• 成功时，把versions列表交给VersionDialog展示。

版本对话框与恢复

VersionDialog（src/dialogs/versiondialog.cpp）遍历版本列表，逐个读取：

• humanReadableTimestamp：人类可读的时间戳，作为版本列表项标题；
• diffHtml：与当前版本的差异 HTML，展示在 diff 浏览器中；
• data：该版本对应的笔记正文。

对话框提供「Restore selected version」按钮用于恢复所选版本。另外值得注意的一个细节：如果当前笔记是加密笔记，版本内容会在展示前被解密（currentNote.getDecryptedNoteText(...)），并应用加密笔记特有的红色虚线边框样式。

QOwnNotes 的这一整套流程也可以直接在 screenshots/screenshot-versioning.png 中看到实际界面效果。

核心功能二：已删除笔记（回收站）

触发入口

主窗口「显示回收站」动作同样先校验当前笔记文件夹是否绑定云连接，然后调用CloudService::loadTrash()（src/mainwindow.cpp）。

底层请求由loadTrash发出（src/services/cloudservice.cpp）：

GET {serverUrl}/index.php/apps/qownnotesapi/api/v1/note/trashed ?format=json &dir={当前笔记子文件夹路径} &extensions[]=md &extensions[]=... # 以及所有自定义笔记扩展名

注意这里extensions[]会逐条追加，覆盖Note::noteFileExtensionList()中配置的全部笔记扩展名（src/services/cloudservice.cpp），确保自定义笔记扩展名也能被回收站功能识别。

响应解析与展示

handleTrashedLoading（src/services/cloudservice.cpp）解析响应：

• 空数据或message字段存在时给出服务器错误提示；
• 缺少directory时同样报错；
• notes为空时提示「服务器上未找到已删除笔记」；
• 成功时把notes列表交给TrashDialog展示。

界面上呈现删除时间、原始文件名等信息，并支持预览笔记内容。实际界面可参考 screenshots/screenshot-trash.png。

恢复与彻底删除

在TrashDialog中执行恢复时，客户端调用restoreTrashedNoteOnServer()（src/services/cloudservice.cpp）：

GET {serverUrl}/index.php/apps/qownnotesapi/api/v1/note/restore_trashed ?format=json &file_name={服务器端完整笔记路径} &timestamp={删除时间戳}

其中file_name由当前笔记目录、当前活动子文件夹与文件名拼接而成；timestamp是笔记被删除时的时间戳，用于在回收站中唯一定位该文件。

此外还有彻底删除接口：deleteTrashedNoteOnServer()（src/services/cloudservice.cpp）不走 QOwnNotesAPI，而是直接对 WebDAV 回收站路径发起 HTTPDELETE请求：

DELETE /remote.php/dav/trashbin/{userName}/trash/{fileName}.d{timestamp}

该请求带 10 秒超时，并返回 HTTP 状态码供界面判断删除结果。也就是说：恢复已删除笔记依赖 QOwnNotesAPI，而彻底删除则复用 Nextcloud / ownCloud 自身的 DAV trashbin 接口。

恢复动作相关说明也存在于回收站对话框中：恢复已删除笔记会同时把服务器上的历史版本一并找回；而仅移除则不会恢复版本，笔记会继续保留在回收站中（相关文案见 src/dialogs/trashdialog.cpp）。

关于笔记同步的官方建议

QOwnNotes 的官方入门文档特别强调：请使用 Nextcloud / ownCloud 官方同步客户端来同步你的笔记，因为你的笔记本质上就是普通的 Markdown 纯文本文件，「没有必要重复发明轮子」。同时文档也指出，也有部分用户使用 Dropbox、Syncthing 或 Resilio Sync 等其他服务来同步笔记文件。

这意味着 QOwnNotesAPI 与同步客户端是两条互补的通道：

• 同步：由 ownCloud / Nextcloud 同步客户端（或其他文件同步服务）负责，保证笔记文件在本地与云端一致；
• 数据恢复：由 QOwnNotesAPI 负责，在文件被删除或需要回溯历史时提供回收站与版本访问能力。

小结：QOwnNotesAPI 在整体架构中的位置

把上面的信息汇总，可以清晰画出 QOwnNotes 云能力的分工图：

从源码结构看，QOwnNotes 将所有这些能力统一封装在CloudService（src/services/cloudservice.cpp）中，并把云连接信息（服务器地址、用户名、密码、是否启用 QOwnNotesAPI 检测等）建模为CloudConnection实体（src/entities/cloudconnection.cpp）。QOwnNotesAPI 在其中扮演的是一个轻量、专注的数据恢复角色——不碰同步、不碰分享，只负责把你可能以为永远丢失的笔记重新找回来。

延伸阅读

• 官方入门文档（英文）：webpage/src/getting-started/qownnotesapi.md
• 云服务实现：src/services/cloudservice.cpp
• 触发入口：src/mainwindow.cpp
• 版本对话框：src/dialogs/versiondialog.cpp
• 回收站对话框：src/dialogs/trashdialog.cpp
• 云设置界面：src/widgets/settings/cloudsettingswidget.cpp
• 云连接实体：src/entities/cloudconnection.cpp
• 本地回收站（不依赖云）：src/dialogs/localtrashdialog.cpp

• 桌面应用