Homepage 集成 Seerr 请求统计 Widget：配置、字段详解与源码解析

Homepage 集成 Seerr 请求统计 Widget：配置、字段详解与源码解析

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage

Seerr（由 Jellyseerr 与 Overseerr 合并而来的媒体请求管理平台）是自托管影音栈中管理"想看清单"的核心服务。本文以 Homepage 仓库中的 Seerr Widget 官方文档 为主体，完整讲解如何在 Homepage 的services.yaml中配置该 Widget、理解六个可选统计字段的含义与默认值，并深入src/widgets/seerr源码与测试，剖析 API 端点、认证机制、渲染回退等底层实现，帮助你一步到位把媒体请求数据呈现在个人主页上。

Widget 是什么：一条 YAML 与一个统计面板

在 Homepage 中，每个 Widget 都是一段挂在某个服务（service）下的 YAML 配置。Seerr Widget 负责从 Seerr 的 API 拉取请求与问题（issue）统计数据，并以一组数字块（Block）的形式展示在服务条目上，例如待处理请求数、已批准数、已完成数等。整个集成不需要编写任何代码，只需要提供服务地址与 API Key。

前置条件：获取 Seerr 的 API Key

文档明确指出，API Key 的获取位置在 Seerr 的Settings > General > API Key。该 Key 是 Widget 调用 Seerr API 的唯一凭证，在后续配置中填入key字段。如果你的实例尚未开启 API，请先在 Seerr 管理后台确认该项存在且已生成。

注意：文档同时强调，Jellyseerr 与 Overseerr 已合并为 Seerr。因此配置时请使用type: seerr，而旧写法type: jellyseerr与type: overseerr仍作为别名继续可用（详见下文"类型别名"一节）。

快速配置：最小 YAML 示例

在services.yaml中为对应服务条目追加如下 Widget 配置（源自 seerr.md）：

widget: type: seerr url: http://seerr.host.or.ip key: apikeyapikeyapikeyapikeyapikey

字段说明：

配置完成后刷新页面，服务卡片上即可看到默认的三个统计块：pending（待处理）、approved（已批准）、completed（已完成）。

字段体系：Allowed Fields 与 Default Fields

文档给出了完整的字段白名单与默认值：

• Allowed fields：["pending", "approved", "available", "completed", "processing", "issues"]
• Default fields：["pending", "approved", "completed"]

也就是说，不写fields时默认展示前三者；如需展示更多维度，可通过fields显式指定，例如：

widget: type: seerr url: http://seerr.host.or.ip key: apikeyapikeyapikeyapikeyapikey fields: - pending - approved - completed - issues

各字段的业务含义：

一个需要留意的实现约束：前端组件最多只渲染4 个统计块。在 component.jsx 中定义了MAX_ALLOWED_FIELDS = 4，配置时如果fields超过 4 项，会被slice(0, 4)截断（component.jsx）。因此请根据实际关注度取舍字段优先级，避免想要的字段被截掉。

类型别名：jellyseerr / overseerr 自动映射为 seerr

文档声明旧类型名已合并为别名，这一点在源码中有明确佐证：

• 在 widgets.js 的 Widget 定义注册表中，jellyseerr（widgets.js）与overseerr（widgets.js）均直接指向seerr的配置对象，而seerr本身也在 widgets.js 注册；
• 在 components.js 的前端组件映射中，jellyseerr（components.js）、overseerr（components.js）与seerr（components.js）三者都动态加载同一个./seerr/component。

因此，升级自 Jellyseerr/Overseerr 的老用户无需改动任何字段逻辑，只需把type改成（或继续沿用）旧名即可，统计行为完全一致。这也意味着如果你曾经参照过旧的 overseerr.md 文档配置，迁移到 Seerr 后配置依然有效。

底层实现：API 端点与数据校验

Widget 的请求行为由 widget.js 定义，它非常精简：

const widget = { api: "{url}/api/v1/{endpoint}", proxyHandler: credentialedProxyHandler, mappings: { "request/count": { endpoint: "request/count", validate: ["pending", "approved", "available"], }, "issue/count": { endpoint: "issue/count", validate: ["open", "total"], }, }, };

从中可以读出三个关键实现事实：

1. API 模板：所有请求都发往{url}/api/v1/{endpoint}，即 Seerr 的 v1 API。url与key在配置中提供，endpoint由组件按需传入（见下文）。
2. 两个可用端点：request/count返回请求统计（校验pending、approved、available字段）；issue/count返回问题统计（校验open、total字段）。这是组件渲染issues块的数来源。
3. 校验机制：mappings 中的validate字段会配合validate-widget-data工具对返回数据做字段级校验，保证渲染的是结构正确的数据，而不是脏响应。

认证与代理：X-API-Key 如何被附加

Seerr Widget 走的是credentialedProxyHandler（带凭证的代理处理器），实现在 credentialed.js。该处理器会：

1. 根据group、service等查询参数从配置中取出 Widget 定义（credentialed.js）；
2. 校验该类型确实支持 API 调用（credentialed.js）；
3. 用formatApiCall把api模板与endpoint拼成真实 URL；
4. 在 credentialed.js 的默认分支中，为请求附加X-API-Key: <key>请求头——这正是 Seerr 所要求的认证方式，你配置的key由此被安全地注入到服务端请求中，而不是暴露在前端代码里；
5. 通过httpProxy发出请求，并对 4xx/5xx 状态返回结构化错误、对 200 响应执行数据校验（credentialed.js）。

渲染逻辑与边界行为

component.jsx 定义了统计块的实际渲染逻辑，几个值得注意的细节：

• issues 是独立数据通道：组件始终调用request/count；只有当fields包含issues时才追加调用issue/count（component.jsx）。issues块以${open} / ${total}的格式展示"未解决 / 总数"（component.jsx）。
• completed → available 自动回退：如果请求了completed或available，但旧版 Seerr 响应中不存在completed字段，组件会把completed字段映射为available继续渲染，避免出现空块（component.jsx）。
• 错误处理：请求统计出错，或启用了issues但问题接口出错时，组件会以错误态渲染容器，便于在页面上直观定位配置问题（component.jsx）。

这些边界行为都有对应的单元测试覆盖（见 component.test.jsx），例如：默认只渲染 3 个块、jellyseerr/overseerr别名保持相同默认字段、processing作为独立可选字段、启用了issues时会调用issue/count并渲染open / total、旧响应无completed时回退到available等。测试还验证了 Widget 配置对象本身符合框架规范（widget.test.js）。

常见问题排查

如果你配置的是多个 Homepage 服务条目，也请确认该 Widget 只挂在正确的 Seerr 服务下，避免与其他服务（如 Jellyfin、Radarr）混用配置。完整的 Widget 列表可从 docs/widgets/services/index.md 进入查看，Seerr 条目即指向本文对应的 seerr.md。

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage