★ FEATURED ARTICLE 桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载导读本文基于 QOwnNotes 官方《Konzept》概念文档系统梳理 QOwnNotes 的生态架构与核心设计理念——笔记为何以纯文本 Markdown 文件形式存放在你的本地文件夹、如何通过 Nextcloud/ownCloud 实现多端同步以及浏览器扩展、Homepage 书签建议 API、命令行片段管理器、TUI、语法检查服务、Android 应用等周边组件各自扮演的角色。读完本文你将掌握 QOwnNotes 生态的全局视图、各组件间的数据流向并能独立完成 Homepage 仪表盘建议接口、LanguageTool/Harper 语法检查等功能的配置。一、整体架构本地文件为核云端服务为翼QOwnNotes 的设计哲学可以用一句话概括笔记永远是你本地磁盘上的普通 Markdown 文件而所有云服务Nextcloud、ownCloud都只是这些文件的同步与扩展手段。官方概念文档用一张架构图展示了这一理念整个系统可以划分为两个域你的电脑Your computer一侧QOwnNotes 桌面应用直接读写本地 Markdown 文件Nextcloud 桌面同步客户端负责把笔记文件夹同步到服务器浏览器扩展Web Companion通过本地 WebSocket 服务与 QOwnNotes 通信管理书签、作为 Web clipper命令行片段管理器与QOwnNotes TUI分别从命令行和终端访问笔记Homepage 仪表盘通过本地 HTTP 建议接口消费书签数据。你的 Nextcloud 服务器一侧QOwnNotesAPI 应用提供服务器端回收站与笔记版本访问能力Nextcloud Notes与Nextcloud Deck服务应用分别负责网页端笔记编辑与提醒/待办卡片QOwnNotes Android通过 Nextcloud Notes API 和 QOwnNotesAPI 与服务器交互。此外编辑器可选接入LanguageTool与Harper两个语法/风格检查服务桌面应用还会通过api.qownnotes.org其背后数据源是 GitHub Releases检查新版本。架构上值得注意的是媒体/附件文件不会由 QOwnNotes 同步。官方文档明确指出文件同步是复杂工程已有成熟方案如 Nextcloud 桌面同步客户端可以胜任QOwnNotes 刻意不重复造轮子。二、QOwnNotes 桌面应用本地优先的 Markdown 笔记与待办管理QOwnNotes 是这套生态的核心节点其职责可以归纳为四点以 Markdown 文件保存笔记所有笔记存放在你指定的笔记文件夹中格式为纯文本 Markdown与 Nextcloud / ownCloud 服务器通信可以把笔记以公开链接形式分享给其他人访问服务器端历史与回收站通过 QOwnNotesAPI Nextcloud 应用读取笔记版本历史与已删除笔记操作服务器端待办列表可访问托管在 Nextcloud/ownCloud 服务器上的 To-do 列表。对应源码入口位于 src/mainwindow.cpp 与 src/mainwindow.h围绕笔记编辑、搜索、待办、分享等核心交互展开云端连接能力则由 src/services/cloudservice.cpp 等服务层实现。三、Markdown 笔记文件所有权与开放性这是 QOwnNotes 最根本的设计决策概念文档用三条要点强调你拥有所有笔记与媒体/附件文件——数据不锁定在任何专有格式或服务器里笔记以明文 Markdown 文件保存在桌面 PC——任何时刻都可以直接用任意文本编辑器打开、查看甚至编辑通过 Nextcloud 或 ownCloud 客户端同步到其他设备桌面与移动端实现多端一致。仓库自带的演示笔记如 src/demonotes/Markdown Showcase.md、src/demonotes/Markdown%20Cheatsheet.md展示了这套 Markdown 语法所支持的范围是了解 QOwnNotes 笔记格式的最佳起点。四、QOwnNotes 浏览器扩展Web Companion书签管理与 Web Clipper浏览器扩展让你能够管理浏览器书签书签以 Markdown 形式存储在 QOwnNotes 笔记中作为 Web clipper 使用把网页内容快速剪藏到笔记。官方概念文档特别强调浏览器扩展完全离线工作不需要互联网连接数据在本地解析与索引。值得关注的是这套书签解析与索引逻辑并不仅服务于浏览器——它同时为 Homepage 仪表盘的本地建议 API 提供数据支撑见下节。实现层面书签解析逻辑集中在 src/entities/bookmark.cpp 与 src/entities/bookmark.h可复用于多个消费端。详细配置与使用方式参见 浏览器扩展文档。五、Homepage 仪表盘把书签变成搜索建议这是概念文档中实操性最强的一节。QOwnNotes 可以暴露一个本地 HTTP 端点为 Homepage 的suggestionUrl提供支持其数据来源正是 Web Companion 同款的书签解析与索引机制。5.1 在 QOwnNotes 中启用打开Settings - Browser extension / command snippets浏览器扩展/命令片段勾选Enable socket server启用套接字服务器在Bookmark suggestion API区块中勾选Enable Homepage-compatible bookmark suggestions API启用 Homepage 兼容书签建议 API为本地端点设置端口可选设置安全令牌security token要求 Homepage 请求携带令牌认证。该服务只绑定127.0.0.1不会暴露到局域网或公网。从源码看这一约束由 src/services/websocketserverservice.cpp 中的m_pHttpServer-listen(QHostAddress::LocalHost, port)第 244 行强制保证。5.2 端点规格与响应格式端点为GET /suggest?qhome支持两个可选参数参数说明默认值上限q查询关键字必填—limit返回建议条数1050token安全令牌若在 QOwnNotes 中配置了令牌可选—端口默认值与构建模式相关发布版默认22224调试版默认22225见 src/services/websocketserverservice.cpp 第 142-148 行的getBookmarkSuggestionApiDefaultPort()。建议接口在 processHttpRequest 中实现仅接受GET方法、仅响应/suggest路径令牌不匹配返回401limit超出范围会被裁剪到[1, 50]。响应是 Homepage 期望的 JSON 数组格式例如[home, [Homepage, https://example.com/home, Some Home Link]]响应组装逻辑见 src/entities/bookmark.cpp 的homepageSuggestionResponseJson()匹配算法则在suggestionStrings()第 173 行起中实现——查询词会被分词按前缀匹配优先、子串匹配次之排序并做去重与limit裁剪。getBookmarksForSuggestions()websocketserverservice.cpp则负责从书签标签、书签笔记与当前编辑器中聚合书签数据并带有 2.5 秒的缓存窗口。5.3 Homepage 配置示例search: provider: custom url: https://example.com/search?q suggestionUrl: http://127.0.0.1:22224/suggest?q showSearchSuggestions: trueprovider: custom使用自定义搜索提供方suggestionUrl指向 QOwnNotes 本地建议接口端口需与 QOwnNotes 中设置的端口一致showSearchSuggestions: true开启搜索建议下拉。5.4 自定义前端资源与安全令牌仓库的 docs/homepage 目录提供了开箱即用的 Homepage 定制资源custom.js拦截 Homepage 的搜索建议请求从http://127.0.0.1:22224/suggest?qquerylimitQON_LIMIT拉取 QOwnNotes 建议并合并展示用[QON]前缀标记来源同时拦截window.open让书签建议直接以新标签页打开对应 URL并防止 Homepage 客户端把合并后的建议硬截断为 4 条custom.css为qon-suggestion建议行添加左边框与绿色文字样式使其在视觉上可区分。custom.js 中的可调配置项docs/homepage/custom.js配置项作用QON_URLQOwnNotes 本地建议 API 端点QON_TOKEN与 QOwnNotes 设置中一致的安全令牌QON_LIMIT请求的建议条数QON_LABEL建议文本前缀标记DEBUG设为true时开启控制台日志令牌机制如果你在 QOwnNotes 中设置了安全令牌请保持 Homepage 配置里的suggestionUrl不变转而把令牌填到 custom.js 的QON_TOKEN中——脚本会在请求时自动追加token...。从源码看令牌由 websocketserverservice.cpp 管理为空时会用Utils::Misc::generateRandomString(32)自动生成 32 位随机串并加密存储。使用场景提示如果 Homepage 运行在另一台主机/容器中必须把 custom.js/custom.css 部署到该 Homepage 实例上才能查询本地 QOwnNotes 建议接口如需突破 localhost 访问应在端点前架设反向代理并通过防火墙或白名单限制访问因为书签数据可能包含敏感 URL。更完整的说明参见 Homepage suggestion API 文档。六、QOwnNotes 命令行片段管理器你可以把常用命令片段command snippets交给 QOwnNotes 管理并在命令行上直接执行。这一功能把笔记应用延伸到终端工作流中——片段以笔记形式存储、可在 QOwnNotes 内维护通过浏览器扩展/命令片段设置区接入。详细用法参见 命令行片段管理器文档。七、QOwnNotes TUI终端里的笔记浏览器QOwnNotes TUI 是一个键盘优先的终端界面用于浏览和编辑笔记。它的关键特性是直接在本地 Markdown 笔记文件上工作复用 QOwnNotes 中配置的笔记文件夹遵循 QOwnNotes 的笔记排序设置。这意味着桌面端与终端可以共享同一套文件夹与排序约定无需额外配置两套体系。详见 QOwnNotes TUI 文档。八、LanguageTool 服务在线语法与风格检查QOwnNotes 编辑器可接入本地或远程的 LanguageTool 服务器进行语法与风格检查可选功能与现有的拼写检查器spell checker并行工作在Settings - Editor中启用随后配置服务器 URL、语言、可选API key及需要检查的类别可从Spelling菜单快速切换菜单项为Check grammar with LanguageTool检测到的问题会通过编辑器上下文菜单提供建议与操作。从源码看languagetoolchecker.cpp 的readSettings()揭示了各设置的默认值设置键默认值说明languageToolServerUrlhttp://localhost:8081本地/远程 LanguageTool 服务地址languageToolLanguageauto检查语言可留空自动检测languageToolApiKey空可选 API key仅在启用时从密钥环解密languageToolEnabledCategoriesTYPOS、GRAMMAR、STYLE、REDUNDANCY、PUNCTUATION、TYPOGRAPHY启用的检查类别languageToolCheckDelay1500ms输入防抖延迟languageToolTimeout5000ms请求超时客户端实现见 src/services/languagetoolclient.cpp请求会按 LanguageTool HTTP API 组装URL 自动补齐到/v2/check路径并携带language空值回落为auto与可选apiKey参数。详细介绍参见 LanguageTool 文档。九、Harper 服务离线语法与风格检查Harper 是另一个语法/风格检查后端与 LanguageTool 的区别在于它可以完全离线运行可选功能与现有拼写检查器并行工作在Settings - Editor - Harper中启用随后配置transport传输方式、harper-ls命令或TCP 目标、dialect方言及要使用的linters检查器可从Edit菜单快速切换菜单项为Check grammar with Harper检测到的问题通过编辑器上下文菜单提供建议与忽略操作。harperchecker.cpp 的readSettings()显示设置键默认值说明harperTransportMode0传输方式stdio 进程 / TCP 连接harperBinaryPathharper-lsharper-ls可执行文件或命令harperTcpAddress127.0.0.1TCP 模式目标地址harperTcpPort4000TCP 模式目标端口harperDialectAmerican检查方言harperEnabledLintersSpellCheck、AnA、SentenceCapitalization、RepeatedWords、LongSentences、Spaces、QuoteSpacing、NoFrenchSpaces、WrongApostrophe、CorrectNumberSuffix、UnclosedQuotes启用的检查器列表harperCheckDelay1500ms输入防抖延迟harperTimeout5000ms请求超时客户端在 src/services/harperclient.cpp 中实现根据transportMode选择HarperStdioTransport默认调用harper-ls或HarperTcpTransport默认127.0.0.1:4000并通过harper-ls的语言服务协议下发配置与文本。检查器会跳过标题、代码块等 Markdown 特殊区块harperchecker.cpp避免误报。详细介绍参见 Harper 文档。十、同步与托管Nextcloud 生态10.1 Nextcloud 桌面同步客户端使用 Nextcloud 或 ownCloud 同步客户端可以在桌面与移动端之间同步笔记。官方文档同时指出其他方案同样可行Dropbox、Syncthing、Seafile、BitTorrent Sync 等均可用于同步笔记与其他文件也可以使用git配合工具如 gitomatic进行同步。QOwnNotes 自身不负责文件级同步这一职责明确交给这些成熟方案。10.2 Nextcloud 服务器要在线使用笔记可以选择 Nextcloud 或 ownCloud 服务器——自建托管或使用托管服务均可。官方文档还提到社区维护的 Nextcloud 提供商列表与支持 Nextcloud 的设备列表可作参考。10.3 QOwnNotesAPI Nextcloud 应用QOwnNotesAPI是部署在 Nextcloud 服务器上的应用负责提供两项关键能力服务器端已删除笔记trash的访问笔记版本历史的访问。桌面端通过它读取云端回收站与版本记录对应客户端的回收站/版本界面src/dialogs/trashdialog.cpp、src/dialogs/versiondialog.cpp 等。详细说明参见 QOwnNotesAPI 文档。10.4 Nextcloud Notes 服务器应用Nextcloud Notes让你在浏览器Web中直接编辑笔记。需要特别注意的限制是Nextcloud Notes 目前只支持到一级子文件夹嵌套更深的结构在网页端无法完整呈现。10.5 Nextcloud Deck 服务器应用QOwnNotes 可以快速在Nextcloud Deck中创建卡片cards用于管理提醒与待办。从 src/services/nextclouddeckservice.cpp 可以看到其通过 Deck REST API 工作创建/更新卡片走/index.php/apps/deck/api/v1.1/boards/{boardId}/stacks/{stackId}/cards归档走/index.php/apps/deck/cards/{cardId}/archive卡片 owner 字段取自当前 Nextcloud 连接的用户名第 41-86 行。十一、QOwnNotes Android移动端离线笔记QOwnNotes for Android是官方推荐的移动端访问方案用于通过 Nextcloud / ownCloud 阅读和编辑笔记。它是一款支持离线的 Markdown 笔记应用通过Nextcloud Notes API与QOwnNotesAPI与服务器同步。核心特性以Room作为本地数据权威source of truth编辑即时缓存、服务器可达时自动同步对接服务器上的Nextcloud Notes与QOwnNotesAPI可访问笔记版本历史与服务器端回收站支持从 Nextcloud Files Android 应用单点登录SSO导入渲染CommonMark 与 GitHub Flavored Markdown支持三态复选框开启/完成/部分、wiki 链接、表格、围栏代码与远程图片提供Markdown 编辑器格式化操作、撤销/重做、光标保持与本地草稿持久化支持收藏笔记离线切换收藏状态、收藏优先排序可从其他 Android 应用分享的文本直接创建笔记Android 9 提供浅色与深色主题。11.1 其他 Android 应用Nextcloud Notes for Android第三方可直接使用也可以搭配任意同步工具如Synchronize Ultimate、FolderSync同步笔记文件再用neutriNotes或Markor等编辑器查看编辑。11.2 iOSCloudNotes for iOS第三方也可用Notebooks通过 WebDAV 同步笔记官方文档附有相关使用教程。详见 QOwnNotes Android 文档。十二、api.qownnotes.org版本更新服务api.qownnotes.org是 QOwnNotes 的在线服务用于检测新版本与 GitHub 通信查询最近一次发布获取对应的下载 URL将Changelog 变更内容编译为 HTML结合当前 QOwnNotes 版本号在更新对话框中展示额外提供版本发布 RSS 订阅http://api.qownnotes.org/rss/app-releases与供旧版 QOwnNotes 使用的legacy 更新检查 API。客户端实现见 src/services/updateservice.cppcheckForUpdates()请求https://api.qownnotes.org/latest_releases/PLATFORM携带更新模式参数um手动/周期等随后根据响应决定是否弹出更新对话框。十三、QOwnNotes Web 应用手机照片直插桌面笔记使用Web 应用app.qownnotes.org你可以从手机直接把照片插入桌面 QOwnNotes 的当前笔记——例如随手拍一张会议白板照片下一秒它就出现在你正在编辑的笔记里。该功能的具体使用步骤参见 QOwnNotes Web-App 文档。十四、总结一张图理解整个生态把全文压缩成一张心智模型[浏览器扩展] ──书签/剪藏──▶ [QOwnNotes 桌面] ──读写──▶ [本地 Markdown 笔记文件夹] [Homepage 仪表盘] ──suggest API──▶ [QOwnNotes 桌面] │ [命令行片段管理器] ──────▶ [QOwnNotes 桌面] [Nextcloud 同步客户端] ◀──同步──▶ [Nextcloud 服务器] [QOwnNotes TUI] ──直接读写──▶ [本地 Markdown 笔记文件夹] │ [QOwnNotes Android] ──Notes API / QOwnNotesAPI──▶ [Nextcloud 服务器] ├── QOwnNotesAPI回收站/版本历史 [LanguageTool / Harper] ──检查服务──▶ [编辑器] ├── Nextcloud Notes网页编辑 [api.qownnotes.org] ──版本检查──▶ [QOwnNotes 桌面] └── Nextcloud Deck卡片/待办QOwnNotes 生态的设计基调始终一致本地 Markdown 文件是数据根基桌面/终端/移动端共享同一份笔记Nextcloud 只承担同步、托管与在线能力语法检查、版本更新等服务以可选或松耦合方式接入。无论你只想用它做一款纯本地笔记工具还是搭建完整的桌面 手机 网页 仪表盘工作流都可以按需启用对应模块。赞分享桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载相关推荐QOwnNotes 概念全景以 Markdown 文件为中心、Nextcloud 为枢纽的笔记生态架构QOwnNotes 概念全景以 Markdown 文件为中心、Nextcloud 为枢纽的笔记生态架构 本文基于 QOwnNotes 官网文档站的《Conce桌面应用Kotlin 协程基本概念从回调地狱到结构化并发的完整理解基于 YCBlogs Kotlin 笔记Kotlin 协程基本概念从回调地狱到结构化并发的完整理解基于 YCBlogs Kotlin 笔记 本篇以 YCBlogs 仓库中的 Kotlin 协程研教程技术博客文档all-of-frontend 微前端架构解析从概念到落地的完整方案all of frontend 微前端架构解析从概念到落地的完整方案 微前端架构作为现代前端开发的革命性解决方案正在改变企业级应用的构建方式。本文将为你详细前端文档教程技术博客上一篇Campus-imaotai开源自动预约系统的完整解决方案终极指南下一篇解密RAG-Anything多模态智能的终极架构指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
