Homepage 集成 Trilium 笔记服务基于 ETAPI 的监控 Widget 配置指南【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本篇指南围绕 Homepage 项目中的 Trilium 服务 Widget 展开讲解如何通过 TriliumNext 的 ETAPIEndpoints API接口让 Homepage 仪表盘直接展示 Trilium 知识库的版本号、笔记数量与数据库体积。读完本文你将掌握 Trilium Widget 的完整配置方法、ETAPI Token 的获取方式以及该 Widget 在前端展示与后端代理调用中的底层实现原理可直接在自建 Homepage 上落地使用。Trilium Widget 能做什么Trilium 是一款开源的层级化笔记应用TriliumNext 是其活跃维护的社区分支。Homepage 提供的 Trilium Widget 是一个只读状态监控型 Widget它不提供增删改查等操作而是通过 Trilium 的 ETAPI 接口读取运行状态并在服务卡片上展示三项指标展示字段含义数据来源ETAPI 响应字段版本VersionTrilium 应用版本号version.app展示时自动加v前缀笔记Notes知识库中的活动笔记总数database.activeNotes数据库大小Database Size知识库数据库文件体积statistics.databaseSizeBytes这三个字段由文档声明为 Allowed fields允许字段即[version, notesCount, dbSize]。三个字段均具备明确的 ETAPI 数据映射且前端的占位渲染与数据渲染完全对齐不存在文档与实现不一致的情况。环境与版本要求根据官方文档说明该 Widget 兼容TriliumNext 版本 v0.94.0v0.94.0 是 ETAPI 能力成熟、metrics接口可用的重要里程碑版本。在使用前请确认你的 Trilium 部署满足运行的是 TriliumNext/Notes 分支而非已停止维护的原 Trilium 主线且版本不低于 v0.94.0已启用并可从 Homepage 所在网络访问 ETAPI 服务通常与 Trilium Web 界面共用端口已创建具备读取权限的 ETAPI Token。获取 ETAPI TokenTrilium 的 ETAPIEndpoints API是官方提供的程序化访问接口需要独立的 Token 进行认证。在 Trilium 的 Web 界面中点击左下角或顶部菜单进入Options选项在选项页面中找到ETAPI分区点击Create new ETAPI token创建新的 ETAPI Token系统会生成一串 Token 字符串复制保存该 Token它将被作为key填入 Homepage 配置。建议为 Homepage 单独创建一个专用 Token便于日后按需吊销避免与其他自动化脚本共用凭证。在 services.yaml 中配置 WidgetTrilium Widget 属于服务型 Widget需要配置在 Homepage 的services.yaml或 Docker/Kubernetes 部署对应的服务配置中通过widget块声明。官方文档给出的最小配置如下widget: type: trilium url: https://trilium.host.or.ip key: etapi_token各字段说明字段必填说明type是固定为trilium用于让 Homepage 匹配到对应的 Widget 定义与代理处理器url是Trilium 服务的访问地址支持 HTTP/HTTPS可以是域名或 IP末尾的斜杠会被自动去除key是上文创建的 ETAPI Token用于接口认证一个完整的最小服务配置示例- Trilium: icon: trilium href: https://trilium.example.com description: 我的个人知识库 widget: type: trilium url: https://trilium.example.com key: your-etapi-token-here配置完成后重启 Homepage或等待其配置热重载服务卡片即会显示 Trilium 的版本、笔记数与数据库大小。底层实现ETAPI 调用链解析理解了配置方式后深入源码可以看清整个数据流从前端组件发起请求到后端代理拼接 URL、注入认证头、校验响应最后回传渲染。1. Widget 定义与代理处理器Trilium 的 Widget 定义位于 src/widgets/trilium/widget.jsimport credentialedProxyHandler from utils/proxy/handlers/credentialed; const widget { api: {url}/etapi/{endpoint}, proxyHandler: credentialedProxyHandler, mappings: { metrics: { endpoint: metrics?formatjson, validate: [version, database], }, }, }; export default widget;关键点api模板{url}/etapi/{endpoint}其中{url}来自配置的url字段{endpoint}由请求方指定mappings.metrics定义名为metrics的端点实际请求路径为metrics?formatjson即最终请求{url}/etapi/metrics?formatjsonvalidate校验清单[version, database]要求 ETAPI 响应中必须包含这两个顶层字段否则视为非法数据proxyHandler复用通用的credentialedProxyHandler代理处理器。2. 后端代理如何拼接 URL 与注入认证Widget 定义由widgets.js注册表统一导出见 src/widgets/widgets.js 中的import trilium from ./trilium/widget及其在导出对象中的挂载。当浏览器前端请求/api/services/proxy时后端会调用 src/utils/proxy/handlers/credentialed.js 中的credentialedProxyHandler处理请求其流程为通过getServiceWidget(group, service, index)从配置中取出对应 Widget用 src/utils/proxy/api-helpers.js 的formatApiCall()将{url}/etapi/{endpoint}模板替换为真实地址替换时自动去除url末尾的斜杠按 Widget 类型注入认证头——Trilium 走的是} else if (widget.type trilium) { headers.Authorization widget.key; }即把配置中的 ETAPI Token 原样放入 HTTPAuthorization请求头Trilium ETAPI 的认证约定而不是Basic或Bearer前缀形式调用httpProxy()发起带 Cookie 能力的代理请求并根据状态码处理结果200时进一步做数据校验 400时返回脱敏后的错误信息sanitizeErrorURL只保留主机名避免泄露完整内网地址。3. 响应数据校验代理拿到响应后会交给 src/utils/proxy/validate-widget-data.js 校验先尝试解析 JSON必要时去除空白后重试再逐项检查mapping.validate中的字段即version与database是否存在于响应中任一缺失即判定为非法数据向调用方返回错误。这套机制保证了即使 Trilium 侧接口返回异常也不会把脏数据渲染到仪表盘上。4. 前端组件渲染前端展示组件位于 src/widgets/trilium/component.jsx通过useWidgetAPI(widget, metrics)请求metrics端点加载中渲染三个无值的Block版本 / 笔记 / 数据库大小占位出错通过Container error{metricsError} /展示错误态数据就绪从响应中提取version.app、database.activeNotes、statistics.databaseSizeBytes三个字段版本号渲染为v 版本字符串笔记数经common.number格式化数据库大小经common.bytes格式化为可读体积。字段标签的国际化定义位于各语言包中例如 public/locales/en/common.json 中的trilium块以及简体中文翻译 public/locales/zh-Hans/common.json版本/笔记/数据库大小这意味着该 Widget 会自动跟随 Homepage 的界面语言切换显示。5. 测试用例佐证仓库为 Trilium Widget 提供了前后端测试验证了上述行为src/widgets/trilium/widget.test.js校验 Widget 配置对象结构合法expectWidgetConfigShape保证api、proxyHandler、mappings等字段齐备src/widgets/trilium/component.test.jsx模拟useWidgetAPI返回加载中状态与就绪数据断言加载时渲染 3 个占位块、就绪时分别渲染v1.0.0、笔记数 2、数据库大小 1024与真实渲染逻辑一一对应。常见问题排查现象可能原因与处理卡片显示错误 / 数据不刷新检查url是否能从 Homepage 容器内访问自建部署时确认 Homepage 与 Trilium 处于同一网络如 Docker 自定义 bridge 网络且未开启仅限 localhost 的访问限制提示 Invalid dataETAPI 响应中缺少version或database字段常见于 Trilium 版本低于 v0.94.0 或访问到的是非 ETAPI 端点401 认证失败key填写错误或 Token 已被吊销确认复制的 ETAPI Token 完整无多余空格版本字段显示 Unknown响应中version.app为空可先直接访问{url}/etapi/metrics?formatjson查看原始返回结构小结Trilium Widget 是 Homepage 中典型的轻量状态型服务 Widget配置仅需url与key两个字段后端复用credentialedProxyHandler完成 URL 拼接、Authorization 注入与响应校验前端则通过useWidgetAPI拉取metrics端点渲染三项指标。借助 src/widgets/trilium/widget.js 与 src/widgets/trilium/component.jsx 的源码你可以照此模式扩展出自己的 Trilium 监控面板或参考同一套mappingsvalidate机制为其他 ETAPI 类服务编写自定义 Widget。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考