Homepage 集成 Atsumeru Widget为自托管漫画服务器添加统计信息展示【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageAtsumeru 是一款自托管的漫画/轻小说阅读服务器而 Homepage 是一个高度可定制的应用仪表盘。通过本文你将掌握如何在 Homepage 的services.yaml中为 Atsumeru 配置 widget使其在仪表盘上实时显示系列series、归档archives、章节chapters与分类categories四项核心统计数据并理解该 widget 从配置到数据渲染的完整链路。本文以官方文档 docs/widgets/services/atsumeru.md 为主线结合仓库源码深入讲解其认证机制与实现原理。Atsumeru Widget 能做什么Atsumeru原 Comic Library是一个以一次导入、多端阅读为理念的自托管漫画服务器支持通过 Web 界面和多种移动端应用访问。当你在 Homepage 中为 Atsumeru 服务挂载 widget 后仪表盘上会直接呈现该服务器媒体库的四项统计数字无需再打开 Atsumeru 管理后台即可掌握库容状态Series系列总数按作品聚合Archives归档/文件总数导入的压缩包等原始媒体文件Chapters章节总数按阅读单位聚合Categories分类总数标签/分类体系的条目数量这些标签文案定义在 public/locales/en/common.json 中并随 Homepage 的多语言体系自动翻译你的仪表盘使用什么语言统计块的标题就显示什么语言。前置条件在开始配置之前请确认你已经有一个可访问的 Atsumeru 实例且其版本提供的 API 兼容/api/server/info端点本文以当前仓库实现所调用的端点为依据。你拥有与 Web 或受支持 App 登录完全相同的用户名和密码。这一点非常关键——官方文档明确指出Define same username and password that is used for login from web or supported apps也就是说该 widget 复用的是 Atsumeru 的正常账号体系不需要额外创建 API Key。你的 Homepage 已经能访问到 Atsumeru 所在的主机容器网络、反向代理或直连 IP 均可只要 URL 可解析。若你的 Homepage 与 Atsumeru 分别部署在不同主机请确认目标端口在防火墙/安全组中放行。配置 Atsumeru Widget完整 YAML 配置在 Homepage 的配置目录中找到services.yaml参考骨架文件 src/skeleton/services.yaml初始内容包含分组与服务示例在服务条目中加入widget段。原文档给出的最小可用配置如下widget: type: atsumeru url: http://atsumeru.host.or.ip:port username: username password: password将其放置到服务定义中完整的服务条目示例- 媒体中心: - Atsumeru 漫画库: icon: sh-atsumeru.png href: http://atsumeru.host.or.ip:port description: 自托管漫画阅读服务器 widget: type: atsumeru url: http://atsumeru.host.or.ip:port username: myaccount password: mypassword字段说明字段类型必填说明typestring是固定为atsumeru用于匹配 Homepage 内置的 Atsumeru widget 实现urlstring是Atsumeru 实例的访问地址格式为http://host:port或https://domain不含尾部/api路径usernamestring是Atsumeru Web/App 登录用户名passwordstring是对应的登录密码关于url的取值需要特别说明从源码看src/widgets/atsumeru/widget.js 中 API 模板定义为{url}/api/server/{endpoint}因此url只需填写 Atsumeru 的根地址含协议与端口Homepage 会自动拼接/api/server/info来拉取数据。支持展示的字段官方文档明确Allowed fields:[series, archives, chapters, categories]。这四个字段即 widget 上展示的四个统计块对应组件实现中的四个Block详见下文前端渲染层。配置中不需要也不能额外指定其他展示字段。配置完成后的效果与验证保存配置并刷新 Homepage 页面后Atsumeru 服务卡片上会出现四个统计块。数据未返回前四个块以占位符仅显示标签、无数值的形式呈现数据成功返回后依次填充对应的数值。若配置正确你看到的卡片大致为┌────────────────────────────┐ │ Atsumeru 漫画库 │ │ Series Archives Chapters │ │ 128 3,452 24,109 │ │ Categories │ │ 56 │ └────────────────────────────┘深入源码数据是怎么被取回来的理解了怎么配再看为什么这样配有助于排查问题。Atsumeru widget 的数据链路由三部分构成widget 定义声明式配置、通用代理处理器服务端转发、前端数据 Hook客户端拉取。1. Widget 定义层声明 API 模板与映射src/widgets/atsumeru/widget.js 是整个 widget 的身份证全文仅有十余行import genericProxyHandler from utils/proxy/handlers/generic; const widget { api: {url}/api/server/{endpoint}, proxyHandler: genericProxyHandler, mappings: { info: { endpoint: info, }, }, }; export default widget;要点解读api模板{url}会被替换成配置中的url{endpoint}会被替换为请求的端点名本 widget 唯一的端点是info最终请求地址为http://atsumeru.host.or.ip:port/api/server/info。mappings定义了端点与校验/处理规则的映射。info映射用于将 API 响应与前端请求端点关联起来。proxyHandler复用genericProxyHandler这是 Homepage 绝大多数基于简单 REST API 的 widget 使用的通用转发器。该 widget 通过 src/widgets/widgets.js 被注册进全局 widget 注册表Homepage 才能按type: atsumeru找到对应实现。2. 服务端转发层Basic Auth 与数据校验浏览器端无法直接请求 Atsumeru存在跨域与凭据安全问题因此所有 widget 数据请求都先打到 Homepage 自身的代理接口由 src/utils/proxy/handlers/generic.js 统一处理。与 Atsumeru 相关的过程如下第一步凭据注入。第 34–36 行if (widget.username widget.password) { headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)}; }这正是文档要求填写与 Web 登录相同的用户名密码的原因——Homepage 会将其编码为 HTTP Basic 认证头附加到对 Atsumeru 的请求上。只要 Atsumeru 能接受该账号密码代理即可通过认证。第二步URL 组装。第 22 行通过formatApiCall将api模板中的{url}、{endpoint}占位符替换为实际值。第三步响应校验。状态码为 200 时调用 src/utils/proxy/validate-widget-data.js 对返回数据做解析与校验JSON 解析失败或响应为空等异常会被标记为无效数据并以Invalid data形式返回前端展示错误。3. 前端渲染层四个统计块src/widgets/atsumeru/component.jsx 负责把数据渲染成卡片通过useWidgetAPI(widget, info)发起请求。该 Hooksrc/utils/proxy/use-widget-api.js基于 SWR 封装支持自动刷新与错误透传。数据未就绪时渲染四个无值Blockseries/archives/chapters/categories见组件第 17–26 行数据就绪后从响应中读取infoData.stats.total_series、total_archives、total_chapters、total_categories四个字段并格式化渲染见第 28–35 行Block labelatsumeru.series value{t(common.number, { value: infoData.stats.total_series })} / Block labelatsumeru.archives value{t(common.number, { value: infoData.stats.total_archives })} / Block labelatsumeru.chapters value{t(common.number, { value: infoData.stats.total_chapters })} / Block labelatsumeru.categories value{t(common.number, { value: infoData.stats.total_categories })} /由此可见Atsumeru 的/api/server/info响应中必须包含stats.total_series等四个字段否则统计块将无法正常取值。4. 测试印证仓库为该 widget 提供了完整的单元测试可作为实现行为的权威佐证src/widgets/atsumeru/widget.test.js校验 widget 配置对象的形状api、mappings、proxyHandler等字段合法src/widgets/atsumeru/component.test.jsx分别断言加载态渲染 4 个占位块、成功态渲染stats中1/2/3/4四个数值与上文所述渲染逻辑一一对应。常见问题排查1. 卡片一直显示占位符无数字说明useWidgetAPI尚未拿到数据。可能原因url填写错误或 Atsumeru 端口未开放Homepage 代理请求失败用户名/密码与 Atsumeru 登录凭据不一致返回 401/403genericProxyHandler 会将其作为HTTP Error透出。2. 卡片显示Invalid data说明请求成功200但响应体不是合法的 JSON或缺少stats.total_series等字段未能通过 src/utils/proxy/validate-widget-data.js 的校验。请确认 Atsumeru 版本提供的/api/server/info响应结构与本文描述一致。3. 如何确认代理请求本身是否成功可以直接在浏览器访问 Atsumeru 的http://atsumeru.host.or.ip:port/api/server/info带 Basic 认证观察返回的 JSON 结构是否包含stats对象与上述四个total_*字段即可快速定位是服务端问题还是 Homepage 侧问题。小结Atsumeru widget 是 Homepage 中典型的声明式配置 通用代理型集成配置侧只需提供url与登录凭据服务端由genericProxyHandler统一完成 Basic 认证与数据校验前端由组件读取/api/server/info的stats字段渲染四个统计块。掌握这一链路后你不仅能顺利接入 Atsumeru也能举一反三地理解 Homepage 其他基于 REST API 的 widget如 Komga、DiskStation 等的接入方式。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考