Homepage 集成 Seerr 请求统计 Widget配置、字段详解与源码解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageSeerr由 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.mdwidget: type: seerr url: http://seerr.host.or.ip key: apikeyapikeyapikeyapikeyapikey字段说明字段必填说明type是固定为seerr也可用旧别名jellyseerr/overseerrurl是Seerr 实例的地址支持域名或 IP如http://seerr.host.or.ipkey是在 SeerrSettings General API Key中获取的密钥配置完成后刷新页面服务卡片上即可看到默认的三个统计块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各字段的业务含义字段含义pending待处理等待审核的请求数approved已批准的请求数available已可获取资源已就绪的请求数completed已完成的请求数processing正在处理中的请求数issues问题报告数以未解决 / 总数open / total形式展示一个需要留意的实现约束前端组件最多只渲染4 个统计块。在 component.jsx 中定义了MAX_ALLOWED_FIELDS 4配置时如果fields超过 4 项会被slice(0, 4)截断component.jsx。因此请根据实际关注度取舍字段优先级避免想要的字段被截掉。类型别名jellyseerr / overseerr 自动映射为 seerr文档声明旧类型名已合并为别名这一点在源码中有明确佐证在 widgets.js 的 Widget 定义注册表中jellyseerrwidgets.js与overseerrwidgets.js均直接指向seerr的配置对象而seerr本身也在 widgets.js 注册在 components.js 的前端组件映射中jellyseerrcomponents.js、overseerrcomponents.js与seerrcomponents.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], }, }, };从中可以读出三个关键实现事实API 模板所有请求都发往{url}/api/v1/{endpoint}即 Seerr 的 v1 API。url与key在配置中提供endpoint由组件按需传入见下文。两个可用端点request/count返回请求统计校验pending、approved、available字段issue/count返回问题统计校验open、total字段。这是组件渲染issues块的数来源。校验机制mappings 中的validate字段会配合validate-widget-data工具对返回数据做字段级校验保证渲染的是结构正确的数据而不是脏响应。认证与代理X-API-Key 如何被附加Seerr Widget 走的是credentialedProxyHandler带凭证的代理处理器实现在 credentialed.js。该处理器会根据group、service等查询参数从配置中取出 Widget 定义credentialed.js校验该类型确实支持 API 调用credentialed.js用formatApiCall把api模板与endpoint拼成真实 URL在 credentialed.js 的默认分支中为请求附加X-API-Key: key请求头——这正是 Seerr 所要求的认证方式你配置的key由此被安全地注入到服务端请求中而不是暴露在前端代码里通过httpProxy发出请求并对 4xx/5xx 状态返回结构化错误、对 200 响应执行数据校验credentialed.js。渲染逻辑与边界行为component.jsx 定义了统计块的实际渲染逻辑几个值得注意的细节issues 是独立数据通道组件始终调用request/count只有当fields包含issues时才追加调用issue/countcomponent.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。常见问题排查现象可能原因与处理统计块一直显示加载/空值检查url是否可从 Homepage 所在网络访问且未漏掉协议头如http://确认key与 SeerrSettings General API Key完全一致出现 API 错误提示查看返回错误信息401/403 多为 Key 错误或未开启 API404 多为url路径不对Seerr 的 API 前缀是/api/v1issues不显示确认fields中包含issues且位于前 4 个字段之内超出会被截断同时确认 Seerr 侧存在问题数据字段数量与预期不符单 Widget 最多渲染 4 个块请精简fields优先级如果你配置的是多个 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考