homepage 集成 Jellystat 统计小组件配置、鉴权与数据映射深度解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageJellystat 是 Jellyfin 生态中常用的统计分析工具能够记录用户的播放行为并汇总歌曲、电影、剧集等媒体库的观看次数。本文基于 homepage 开源项目仓库根目录 README.md的官方文档 jellystat 组件文档 与对应源码实现完整讲解如何在 homepage 服务仪表盘中接入 Jellystat 小组件包括 API Key 的获取、widget配置项详解、days统计时间窗口的行为以及前端渲染到后端代理请求的完整数据链路。读完本文你将能独立完成 Jellystat 小组件的配置与排障并理解其底层实现原理。一、Jellystat 小组件概览Jellystat 小组件用于在 homepage 的服务卡片上展示媒体库在指定时间范围内的观看统计共显示四个统计维度即官方文档中提到的 Allowed fields[songs, movies, episodes, other]分别对应歌曲Songs、电影Movies、剧集Episodes与其他Other的播放次数。官方文档明确指出该小组件至少支持Jellystat 1.1.6及以上版本原文档表述为 The widget supports (at least) Jellystat version 1.1.6。在启用组件前你需要确保 Jellystat 服务本身已正确部署并监听一个可访问的地址。二、获取 API KeyJellystat 小组件属于带凭证的代理组件访问其统计接口需要携带 API 令牌。获取方式非常简单登录 Jellystat 的 Web 管理界面进入Settings API Key生成或复制一个 API Key将其填入 homepage 的widget配置中。从源码实现看这个 Key 会被直接用作请求头中的令牌。在 credentialed 代理处理器 中jellystat与autobrr、pulse三类组件走同一条分支统一注入如下请求头} else if ([autobrr, jellystat, pulse].includes(widget.type)) { headers[X-API-Token] ${widget.key}; }也就是说homepage 在代理请求 Jellystat API 时会携带X-API-Token: 你的key与 Jellystat 服务端校验逻辑匹配。因此配置key时不需要手动设置任何额外的请求头。三、配置项详解在服务service的 YAML 配置中为某个服务添加如下widget块即可启用 Jellystat 小组件widget: type: jellystat url: http://jellystat.host.or.ip key: apikeyapikeyapikeyapikeyapikey days: 30 # optional, defaults to 30各配置项说明如下配置项必填类型默认值说明type是string无固定为jellystat用于匹配 widgets 注册表 中的组件定义url是string无Jellystat 实例的访问地址如http://jellystat.host.or.ip末尾斜杠会被自动去除key是string无在 JellystatSettings API Key中生成的 API Key最终以X-API-Token请求头发送days否number30统计时间窗口天。必须是大于 0 的整数否则会被强制回退为默认值30其中url的处理细节可以在 api-helpers.js 中看到模板变量替换时会对{url}调用replace(/\/$/, )去除末尾的斜杠所以http://jellystat.host.or.ip/与http://jellystat.host.or.ip写法等价不会导致接口拼接出双斜杠。days的校验逻辑位于 组件渲染入口// Days validation if (!(Number.isInteger(widget.days) 0 widget.days)) widget.days 30;这意味着days未配置、为0或负数、为小数、或非数字类型时都会被重置为30。对应的单元测试 component.test.jsx 也验证了传入非法值-1后service.widget.days被改写为30这一行为同时确认useWidgetAPI会以{ days: 30 }作为查询参数发起请求。四、底层 API 映射从配置到接口调用Jellystat 小组件的后端数据源定义在 widget.js完整内容如下import credentialedProxyHandler from utils/proxy/handlers/credentialed; const widget { api: {url}/{endpoint}, proxyHandler: credentialedProxyHandler, mappings: { getViewsByLibraryType: { endpoint: stats/getViewsByLibraryType, params: [days], }, }, }; export default widget;通过这个映射声明可以梳理出完整的数据请求链路组件定义type: jellystat在 widgets.js 中被导入并注册进全局组件表URL 模板api: {url}/{endpoint}定义了向 Jellystat 发起请求的地址模板{url}替换为配置中的url{endpoint}替换为具体映射的 endpoint接口映射getViewsByLibraryType映射到 Jellystat 的stats/getViewsByLibraryType接口并声明该接口接受days参数代理处理器credentialedProxyHandler负责构造请求头注入X-API-Token并转发请求详见 credentialed.js前端发起use-widget-api.js 通过 SWR 请求由 formatProxyUrl 生成的/api/services/proxy?...代理地址其中查询参数会被序列化为queryJSON 传给代理接口数据校验代理返回 200 后会通过validateWidgetData校验数据结构是否合法credentialed.js。最终homepage 请求的实际目标地址为http://jellystat.host.or.ip/stats/getViewsByLibraryType?days30请求头中携带X-API-Token: key。五、前端渲染四个统计维度的数据映射组件渲染逻辑位于 component.jsx。它通过useWidgetAPI拉取getViewsByLibraryType接口的数据并将 Jellystat 返回的字段映射为四个展示块展示标签国际化 keyJellystat 返回字段含义jellystat.songsviewsData.Audio歌曲播放统计jellystat.moviesviewsData.Movie电影播放统计jellystat.episodesviewsData.Series剧集分集播放统计jellystat.otherviewsData.Other其他类型媒体统计对应的文案在语言包 public/locales/en/common.json 中定义为 Songs、Movies、Episodes、Other而项目内置的 40 余种语言目录均包含同结构的jellystat词条小组件会自动随界面语言切换显示。渲染过程有三个状态加载中数据尚未返回时显示四个无值占位块component.jsx请求出错viewsError或返回数据中携带message字段时展示错误容器component.jsx错误信息会被sanitizeErrorURL脱敏只保留主机名完整地址记入日志数据就绪将Audio、Movie、Series、Other四个字段分别渲染为数值块component.jsx。上述行为均有测试覆盖component.test.jsx 分别验证了非法 days 回退为 30 并渲染四个占位块、接口报错时渲染错误 UI、数据返回后正确展示 1/2/3/4 四个数值三种场景widget.test.js 则通过expectWidgetConfigShape校验了组件配置结构api、proxyHandler、mappings的合法性。六、常见问题与排查建议401 / 无权限确认key与 JellystatSettings API Key中生成的值完全一致。注意代理层发送的是X-API-Token请求头不要在 Jellystat 端误配成其他认证方式。数据始终为空或显示错误确认days为大于 0 的整数。按照 component.jsx 的校验逻辑任何非法值都会被重置为 30不会报错但可能不符合你的统计预期。接口路径 404确认 Jellystat 版本不低于 1.1.6且stats/getViewsByLibraryType接口可用可先用curl -H X-API-Token: key http://jellystat/stats/getViewsByLibraryType?days30直接验证同时确认url未包含多余的路径前缀因为代理层只会做去末尾斜杠处理。错误信息脱敏当请求失败时homepage 只会在界面展示主机名见 api-helpers.js完整错误 URL 需要查看 homepage 服务端日志其中记录了实际请求的目标地址与状态码credentialed.js。七、小结Jellystat 小组件是 homepage 服务仪表盘中统计类组件的典型代表前端通过 SWR 与统一代理接口通信代理层完成凭证注入与数据校验最终将 Jellystat 的stats/getViewsByLibraryType响应映射为四个简洁的统计块。从配置上看你只需要提供url、key与可选的days三个关键信息即可完成接入从源码上看其完整链路覆盖了 widget 映射、代理处理器、组件渲染 与配套测试为自定义组件的开发提供了可参考的实现范式。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 homepage 集成 Jellystat 统计小组件：配置、鉴权与数据映射深度解析
homepage 集成 Jellystat 统计小组件配置、鉴权与数据映射深度解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageJellystat 是 Jellyfin 生态中常用的统计分析工具能够记录用户的播放行为并汇总歌曲、电影、剧集等媒体库的观看次数。本文基于 homepage 开源项目仓库根目录 README.md的官方文档 jellystat 组件文档 与对应源码实现完整讲解如何在 homepage 服务仪表盘中接入 Jellystat 小组件包括 API Key 的获取、widget配置项详解、days统计时间窗口的行为以及前端渲染到后端代理请求的完整数据链路。读完本文你将能独立完成 Jellystat 小组件的配置与排障并理解其底层实现原理。一、Jellystat 小组件概览Jellystat 小组件用于在 homepage 的服务卡片上展示媒体库在指定时间范围内的观看统计共显示四个统计维度即官方文档中提到的 Allowed fields[songs, movies, episodes, other]分别对应歌曲Songs、电影Movies、剧集Episodes与其他Other的播放次数。官方文档明确指出该小组件至少支持Jellystat 1.1.6及以上版本原文档表述为 The widget supports (at least) Jellystat version 1.1.6。在启用组件前你需要确保 Jellystat 服务本身已正确部署并监听一个可访问的地址。二、获取 API KeyJellystat 小组件属于带凭证的代理组件访问其统计接口需要携带 API 令牌。获取方式非常简单登录 Jellystat 的 Web 管理界面进入Settings API Key生成或复制一个 API Key将其填入 homepage 的widget配置中。从源码实现看这个 Key 会被直接用作请求头中的令牌。在 credentialed 代理处理器 中jellystat与autobrr、pulse三类组件走同一条分支统一注入如下请求头} else if ([autobrr, jellystat, pulse].includes(widget.type)) { headers[X-API-Token] ${widget.key}; }也就是说homepage 在代理请求 Jellystat API 时会携带X-API-Token: 你的key与 Jellystat 服务端校验逻辑匹配。因此配置key时不需要手动设置任何额外的请求头。三、配置项详解在服务service的 YAML 配置中为某个服务添加如下widget块即可启用 Jellystat 小组件widget: type: jellystat url: http://jellystat.host.or.ip key: apikeyapikeyapikeyapikeyapikey days: 30 # optional, defaults to 30各配置项说明如下配置项必填类型默认值说明type是string无固定为jellystat用于匹配 widgets 注册表 中的组件定义url是string无Jellystat 实例的访问地址如http://jellystat.host.or.ip末尾斜杠会被自动去除key是string无在 JellystatSettings API Key中生成的 API Key最终以X-API-Token请求头发送days否number30统计时间窗口天。必须是大于 0 的整数否则会被强制回退为默认值30其中url的处理细节可以在 api-helpers.js 中看到模板变量替换时会对{url}调用replace(/\/$/, )去除末尾的斜杠所以http://jellystat.host.or.ip/与http://jellystat.host.or.ip写法等价不会导致接口拼接出双斜杠。days的校验逻辑位于 组件渲染入口// Days validation if (!(Number.isInteger(widget.days) 0 widget.days)) widget.days 30;这意味着days未配置、为0或负数、为小数、或非数字类型时都会被重置为30。对应的单元测试 component.test.jsx 也验证了传入非法值-1后service.widget.days被改写为30这一行为同时确认useWidgetAPI会以{ days: 30 }作为查询参数发起请求。四、底层 API 映射从配置到接口调用Jellystat 小组件的后端数据源定义在 widget.js完整内容如下import credentialedProxyHandler from utils/proxy/handlers/credentialed; const widget { api: {url}/{endpoint}, proxyHandler: credentialedProxyHandler, mappings: { getViewsByLibraryType: { endpoint: stats/getViewsByLibraryType, params: [days], }, }, }; export default widget;通过这个映射声明可以梳理出完整的数据请求链路组件定义type: jellystat在 widgets.js 中被导入并注册进全局组件表URL 模板api: {url}/{endpoint}定义了向 Jellystat 发起请求的地址模板{url}替换为配置中的url{endpoint}替换为具体映射的 endpoint接口映射getViewsByLibraryType映射到 Jellystat 的stats/getViewsByLibraryType接口并声明该接口接受days参数代理处理器credentialedProxyHandler负责构造请求头注入X-API-Token并转发请求详见 credentialed.js前端发起use-widget-api.js 通过 SWR 请求由 formatProxyUrl 生成的/api/services/proxy?...代理地址其中查询参数会被序列化为queryJSON 传给代理接口数据校验代理返回 200 后会通过validateWidgetData校验数据结构是否合法credentialed.js。最终homepage 请求的实际目标地址为http://jellystat.host.or.ip/stats/getViewsByLibraryType?days30请求头中携带X-API-Token: key。五、前端渲染四个统计维度的数据映射组件渲染逻辑位于 component.jsx。它通过useWidgetAPI拉取getViewsByLibraryType接口的数据并将 Jellystat 返回的字段映射为四个展示块展示标签国际化 keyJellystat 返回字段含义jellystat.songsviewsData.Audio歌曲播放统计jellystat.moviesviewsData.Movie电影播放统计jellystat.episodesviewsData.Series剧集分集播放统计jellystat.otherviewsData.Other其他类型媒体统计对应的文案在语言包 public/locales/en/common.json 中定义为 Songs、Movies、Episodes、Other而项目内置的 40 余种语言目录均包含同结构的jellystat词条小组件会自动随界面语言切换显示。渲染过程有三个状态加载中数据尚未返回时显示四个无值占位块component.jsx请求出错viewsError或返回数据中携带message字段时展示错误容器component.jsx错误信息会被sanitizeErrorURL脱敏只保留主机名完整地址记入日志数据就绪将Audio、Movie、Series、Other四个字段分别渲染为数值块component.jsx。上述行为均有测试覆盖component.test.jsx 分别验证了非法 days 回退为 30 并渲染四个占位块、接口报错时渲染错误 UI、数据返回后正确展示 1/2/3/4 四个数值三种场景widget.test.js 则通过expectWidgetConfigShape校验了组件配置结构api、proxyHandler、mappings的合法性。六、常见问题与排查建议401 / 无权限确认key与 JellystatSettings API Key中生成的值完全一致。注意代理层发送的是X-API-Token请求头不要在 Jellystat 端误配成其他认证方式。数据始终为空或显示错误确认days为大于 0 的整数。按照 component.jsx 的校验逻辑任何非法值都会被重置为 30不会报错但可能不符合你的统计预期。接口路径 404确认 Jellystat 版本不低于 1.1.6且stats/getViewsByLibraryType接口可用可先用curl -H X-API-Token: key http://jellystat/stats/getViewsByLibraryType?days30直接验证同时确认url未包含多余的路径前缀因为代理层只会做去末尾斜杠处理。错误信息脱敏当请求失败时homepage 只会在界面展示主机名见 api-helpers.js完整错误 URL 需要查看 homepage 服务端日志其中记录了实际请求的目标地址与状态码credentialed.js。七、小结Jellystat 小组件是 homepage 服务仪表盘中统计类组件的典型代表前端通过 SWR 与统一代理接口通信代理层完成凭证注入与数据校验最终将 Jellystat 的stats/getViewsByLibraryType响应映射为四个简洁的统计块。从配置上看你只需要提供url、key与可选的days三个关键信息即可完成接入从源码上看其完整链路覆盖了 widget 映射、代理处理器、组件渲染 与配套测试为自定义组件的开发提供了可参考的实现范式。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考