QOwnNotes Homepage 建议 API 接入指南：本地书签搜索引擎配置与源码原理-北京尧图网络

桌面应用【免费下载链接】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 内置了一个与 Homepage 仪表盘suggestionUrl特性兼容的本地 HTTP 建议端点数据来自与 Web Companion 浏览器扩展相同的书签解析与索引机制。本文将完整讲解在 QOwnNotes 中启用该 API、在 Homepage 的settings.yaml中配置search块、使用仓库自带的custom.js/custom.css定制搜索建议展示并从 websocketserverservice.cpp 与 bookmark.cpp 的源码层面剖析端点协议、匹配算法与缓存机制帮助你在一台本机或跨主机环境中把 QOwnNotes 的书签变成 Homepage 搜索框的实时建议来源。功能概览Homepage 建议 API 是什么Homepage 是常见的自托管仪表盘应用其搜索框支持通过suggestionUrl对接外部建议数据源。QOwnNotes 借此暴露一个本地 HTTP 端点复用 Web Companion 数据源的书签解析/索引能力当你在 Homepage 搜索框中输入关键词时Homepage 会把查询转发给 QOwnNotes由 QOwnNotes 在本地书签库中检索匹配项并返回建议列表。从源码结构看该功能并非独立服务而是由 WebSocket 服务模块src/services/websocketserverservice.cpp附带的一个轻量 HTTP 服务实现其生命周期与Enable socket server开关、设置项变化联动refreshServers()中根据isBookmarkSuggestionApiEnabled()决定startSuggestionHttpServer()或stopSuggestionHttpServer()。关键安全约束服务只绑定127.0.0.1QHostAddress::LocalHost外部主机默认无法访问跨主机场景需要反向代理配合见下文。在 QOwnNotes 中启用建议 API启用步骤与原文档一致共三步打开设置 - Browser extension / command snippets即 Web Companion 设置页对应 webcompanionsettingswidget.ui 中的 Web socket server support 分组。勾选Enable socket server。该开关对应设置键enableSocketServer默认开启见 misc.cpp 中Utils::Misc::isSocketServerEnabled()的实现默认值为true。在Bookmark suggestion API分组框内勾选Enable Homepage-compatible bookmark suggestions API设置Suggestion API port端口输入框范围 165535默认22224另有重置端口按钮一键恢复默认值如需鉴权在Security token输入框中填写安全令牌下方按钮可显示/复制/重新生成令牌。对应源码确认启用开关对应设置键webSocketServerService/bookmarkSuggestionApiEnabled默认false端口对应webSocketServerService/bookmarkSuggestionApiPort默认端口在发布版为22224、Debug 构建为22225见 websocketserverservice.cpp。服务启动时调用m_pHttpServer-listen(QHostAddress::LocalHost, port)因此只接受来自本机 127.0.0.1 的连接若端口被占用会打印 Could not start bookmark suggestion API on port %1! 警告。安全令牌的生成与存储安全令牌token的读写集中在 websocketserverservice.cppgetBookmarkSuggestionApiToken()读取webSocketServerService/bookmarkSuggestionApiToken通过CryptoService::decryptToString()解密若遇到旧版/手工写入的明文值会自动回退读取并加密回写plaintext fallback。getOrGenerateBookmarkSuggestionApiToken()在令牌为空时调用Utils::Misc::generateRandomString(32)生成 32 位随机串并加密存储。在设置界面 webcompanionsettingswidget.cpp 中保存时若令牌为空也会自动生成 32 位随机串并通过CryptoService::encryptToString()加密写入。该令牌键被列入调试信息脱敏列表misc.cpp导出调试信息时不会暴露明文。HTTP 端点协议详解端点由processHttpRequest()websocketserverservice.cpp实现是一个极简的 HTTP/1.1 服务基于QTcpServerQTcpSocket仅接受 GET 请求。请求GET /suggest?qhome参数说明参数必填默认值约束q是—查询关键词为空时返回空建议列表limit否10最小1最大50超出自动截断token否—仅在 QOwnNotes 中配置了安全令牌时需要且必须与配置值完全一致源码行为佐证limit解析失败时回退为10limit 1强制为1limit 50强制为50websocketserverservice.cppq为空时直接返回空建议homepageSuggestionResponse()中对空查询的特殊处理见 websocketserverservice.cpp。鉴权与错误响应当配置了安全令牌时服务端会把请求中的token与getOrGenerateBookmarkSuggestionApiToken()的结果比对不一致返回 HTTP401 Unauthorized。其他错误场景包括请求行格式错误 →400 Bad Request{error:Bad request}非 GET 方法 →405 Method Not Allowed路径不是/suggest→404 Not Found响应格式与响应头成功时返回200 OKContent-Type: application/json; charsetutf-8格式为[query, [suggestion1, suggestion2, ...]][home, [Homepage, https://example.com/home, Some Home Link]]响应体由Bookmark::homepageSuggestionResponseJson()bookmark.cpp生成数组第一项是原样回显的查询词第二项是建议字符串数组。响应头包含Access-Control-Allow-Origin: *允许浏览器跨域请求Access-Control-Allow-Methods: GET, OPTIONSCache-Control: no-store禁止缓存保证建议实时性以上均来自httpResponse()的响应模板websocketserverservice.cpp。书签数据来源与建议匹配算法源码级建议数据从哪来getBookmarksForSuggestions()websocketserverservice.cpp按以下顺序汇集书签从书签 tag默认名为Bookmarks可通过webSocketServerService/bookmarksTag配置关联的所有笔记中解析书签按书签笔记名默认Bookmarks配置键webSocketServerService/bookmarksNoteName在所有笔记子文件夹中查找同名笔记并解析书签解析当前活动笔记中的书签Bookmark::parseBookmarks(activeEditor-toPlainText(), true)。结果缓存在m_cachedBookmarks中缓存有效期2.5 秒m_bookmarkCacheTimestamp.msecsTo(...) 2500到期重建并同时清空建议缓存避免频繁读写笔记。Bookmark::parseBookmarks()bookmark.cpp支持三种书签写法带标签与描述的 Markdown 链接- [name](http://link) #tag1 #tag2 描述文本普通命名链接[name](http://my.site.com)仅在withBasicUrls为 true 时解析并为书签附加current标签裸链接http://my.site.com同上匹配与排序逻辑Bookmark::suggestionStrings()bookmark.cpp实现匹配算法匹配范围书签的name、url以及元数据tags、description、markdown 文本拼接任一包含全部查询 token 即命中多 token 查询顺序无关要求所有 token 都出现在候选串中containsAllTokens。排序优先级前缀匹配候选串以整个查询串或以任一 token 开头优先于普通子串匹配前缀命中排在结果列表前面。去重建议按大小写折叠后去重同一条建议不会重复出现。截断总条数不超过limit先取前缀匹配不足再补子串匹配。输出内容命中的书签先输出name非空时再输出url当 url 或元数据命中时因此可能出现名称 URL相邻的成对建议——这正是custom.js中把名称文本映射回 URL 的依据。仓库单元测试 test_notes.cpp 覆盖了前缀/子串匹配、去重、多 token 顺序无关、名称与 URL 配对保持、元数据含 Markdown参与匹配、空查询返回空、limit 截断limit3返回 3 条、limit100被压回 50 条以及响应 JSON 形状等行为可作为算法行为的权威验证。建议响应的缓存homepageSuggestionResponse()websocketserverservice.cpp以query|limit为键缓存已生成的 JSON 响应缓存上限200 条超出后从最旧开始淘汰书签数据重建时缓存被清空。在 Homepage 中配置搜索建议基础配置示例在 Homepage 配置中添加search块provider设为custom并把suggestionUrl指向 QOwnNotes 本机端点search: provider: custom url: https://example.com/search?q suggestionUrl: http://127.0.0.1:22224/suggest?q showSearchSuggestions: true说明url是点击建议后的搜索引擎跳转地址?q后会被填入查询词suggestionUrl即 QOwnNotes 建议 API 端点端口与 QOwnNotes 设置中保持一致showSearchSuggestions: true启用搜索建议下拉。修改哪个配置文件在标准 Homepage 安装中将search块添加到以下任一文件settings.yaml全局 Homepage 设置settings.yml同上取决于你的部署方式挂载进容器后映射为/app/config/settings.yaml的那个文件如果 Homepage 部署把配置拆分到多个文件请编辑已经包含searchprovider 设置的那个文件避免重复定义导致配置互相覆盖。使用自定义 Homepage 资产custom.js / custom.css仓库的 docs/homepage 目录提供了开箱即用的 Homepage 定制示例custom.js与custom.css适用于支持加载custom.js/custom.css的 Homepage 部署。其作用是拦截 Homepage 搜索建议 API/api/search/searchsuggestion(s)的响应请求 QOwnNotes 建议端点并把两条数据源合并去重后 QOwnNotes 建议排在前面为 QOwnNotes 建议加前缀标记默认[QON]并把显示文本映射回书签 URL点击建议时直接打开书签 URL而不是作为搜索引擎查询词提交规避 Homepage 前端对合并建议的仅保留 4 条裁剪通过覆写splice为对应建议行添加 CSS 钩子类qon-suggestion。custom.js顶部集中了全部可调参数docs/homepage/custom.jsconst QON_URL http://127.0.0.1:22224/suggest?q; // QOwnNotes 建议端点 const QON_TOKEN ; // QOwnNotes 设置中配置的安全令牌 const QON_LIMIT 20; // 请求的 QOwnNotes 建议条数 const QON_LABEL [QON] ; // 建议列表中 QOwnNotes 条目的标记 const DEBUG false; // 设为 true 可输出调试日志配置了安全令牌时的两种用法方法一推荐保持 Homepage 的suggestionUrl不变仅把 QOwnNotes 的令牌填入custom.js的QON_TOKEN。脚本请求建议时会把QON_TOKEN作为token...查询参数附加到端点 URLfetchQown()中的tokenPart逻辑见 custom.js服务端校验通过后返回数据。方法二直接在suggestionUrl中附加token...例如http://127.0.0.1:22224/suggest?qtokenxxx。此时custom.js中无需再设置QON_TOKEN。两种方式二选一即可重复配置不影响鉴权结果但注意不要让 token 出现在 Homepage 的公开配置或日志中。样式定制custom.csscustom.css 提供对应样式QOwnNotes 建议行左侧绿色边线与绿色文本button.qon-suggestion、URL 提示行li.qon-li-has-url .qon-url-hint附加在li上以在 React 替换按钮节点后依然存活、键盘导航时禁用悬停干扰html.qon-keyboard-nav。跨主机部署与安全建议由于服务只监听 127.0.0.1当 Homepage 运行在与 QOwnNotes 不同的机器/容器时必须做以下两件事把custom.js/custom.css部署到 Homepage 所在主机让远端 Homepage 能发起对建议 API 的请求并合并/展示建议在 QOwnNotes 与 Homepage 之间放置反向代理把端点暴露给远端例如 Nginx 将/suggest反代到127.0.0.1:22224/suggest。安全上必须限制访问范围——书签数据可能包含敏感 URL原文档明确建议通过防火墙规则或 IP 白名单allowlist收紧反向代理入口并结合 QOwnNotes 侧的安全令牌做双重防护令牌必须同时配置在 QOwnNotes 设置Security token与custom.js的QON_TOKEN或suggestionUrl的token参数中令牌以密文形式存储在 QOwnNotes 配置中且会从调试信息中脱敏不要把它写进 Homepage 的公开仓库/配置。验证与故障排查本地验证端点在 QOwnNotes 运行并启用 API 后浏览器或 curl 访问http://127.0.0.1:22224/suggest?qhomelimit10配置了令牌则加token...应返回形如[home,[Homepage,https://example.com/home]]的 JSON。建议不出现检查Enable socket server与Enable Homepage-compatible bookmark suggestions API是否都已勾选确认 Homepagesearch.suggestionUrl的端口与 QOwnNotes 设置一致确认书签笔记的 tag 名/笔记名与设置一致默认分别为Bookmarks。401 Unauthorized令牌不匹配。核对custom.js的QON_TOKEN或 URL 中token参数与 QOwnNotes 设置中的值。外部主机无法访问这是预期行为仅绑定 127.0.0.1请按上文部署反向代理并配置防火墙/白名单。端口冲突QOwnNotes 日志会输出 Could not start bookmark suggestion API on port %1!换一个空闲端口并在 Homepage 配置中同步修改。赞分享桌面应用【免费下载链接】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 Homepage 书签建议 API 接入指南将本地书签注入 Homepage 搜索建议QOwnNotes Homepage 书签建议 API 接入指南将本地书签注入 Homepage 搜索建议 QOwnNotes 内置了一个仅绑定本机回环地址的桌面应用QOwnNotes Homepage 书签建议 API 实战:把本地书签接入 Homepage 搜索建议QOwnNotes Homepage 书签建议 API 实战:把本地书签接入 Homepage 搜索建议 QOwnNotes 除了常见的笔记与 Markdown桌面应用QOwnNotes Homepage 书签建议 API 接入指南为 Homepage 搜索框提供本地书签联想QOwnNotes Homepage 书签建议 API 接入指南为 Homepage 搜索框提供本地书签联想 QOwnNotes 内置了一个面向 Homepa桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

QOwnNotes Homepage 建议 API 接入指南：本地书签搜索引擎配置与源码原理

相关推荐

AI剪纸特效：工艺语义建模与负空间拓扑生成

Odoo 17数据字典中文版：字段类型、表结构及报表查询避坑指南

STM32输入捕获精准读取AM2301A温湿度传感器

更多资讯

两相短路故障Matlab/Simulink仿真模型搭建与波形分析详解

带注解的深度学习入门源码：MNIST神经网络训练与调参避坑指南

8086系统结构深度解析：从寄存器到分段寻址的底层原理

微信小程序闹钟源码实战：从定时逻辑到真机唤醒的完整避坑指南

C语言手写FFT：从DFT到O(N log N)的实战指南

易语言大漠模块封装与免注册调用实战指南

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？