Homepage 集成 Radarr 服务组件Wanted/Missing/Queued 电影看板与队列详解【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文讲解开源项目 Homepage 中 Radarr 服务组件的完整接入方法。通过配置type: radarr的 widget你可以在自建导航页上实时展示 Radarr 中「待看Wanted」「缺失Missing」「排队下载Queued」「已入库Movies」四类电影数量并可选择性开启详细下载队列视图直观看到每个任务的下载进度、剩余时间与导入状态。读完本文你将掌握 Radarr 组件的 YAML 配置、各统计字段的精确语义、详细队列的开关与渲染原理以及底层 API 代理与数据映射的实现机制。Radarr 组件能做什么Radarr 是开源电影自动化管理工具Plex 生态常用的电影库管理服务而 Homepage 内置的 Radarr 服务组件利用其 v3 API把电影库和下载队列的关键信息汇总到导航页面上无需打开 Radarr 后台即可一屏掌握。组件展示的核心数据点即官方配置文档允许的四个字段字段含义wanted已监控monitored但尚未下载入库、且已可获取isAvailable的电影数量missing已监控但尚无文件的电影数量wanted是它的子集queued当前下载队列中的任务总数movies已下载入库hasFile的电影总数这四个字段在 组件前端实现 中作为四个统计块Block渲染国际化标签定义在 英文语言包 中对应radarr.wanted、radarr.missing、radarr.queued、radarr.movies。快速开始最小配置在 Homepage 的services.yaml中为 Radarr 服务添加如下 widget 配置widget: type: radarr url: http://radarr.host.or.ip key: apikeyapikeyapikeyapikeyapikeytype固定为radarr用于在服务端匹配对应的代理处理器urlRadarr 实例的地址需从 Homepage 所在环境可访问支持主机名或 IPkeyRadarr 的 API Key。在 Radarr 界面中通过Settings General找到。这是最精简的配置只展示四个统计数字不渲染详细队列。原文档docs/widgets/services/radarr.md明确指出详细队列列表默认关闭可通过enableQueue选项开启。开启详细下载队列enableQueue详细队列默认关闭开启方式如下widget: type: radarr url: http://radarr.host.or.ip key: apikeyapikeyapikeyapikeyapikey enableQueue: true # optional, defaults to false开启后组件会在四个统计块下方逐条渲染下载队列中的任务每条队列条目包含电影标题通过与movie接口的id关联查找得出下载进度按sizeLeft / size计算见下文getProgress活动状态如downloading、queued、import pending、import blocked等剩余时间timeLeft字段来自 Radarr queue 接口。队列条目组件由 队列条目实现 提供渲染为一条带进度底色条、左侧标题、右侧「状态 - 剩余时间」文本的横向条目。详细队列的启用条件从源码看详细队列并非简单开关const enableQueue widget?.enableQueue Array.isArray(queueDetailsData) queueDetailsData.length 0;也就是说enableQueue: true只是必要条件只有当queue/details接口返回的数组非空时队列条目才会渲染见 组件前端实现。队列为空时不会展示空列表也不会报错。数据从哪来widget 定义与 API 映射Homepage 通过统一的「服务代理proxy」机制转发前端请求到 Radarr API核心定义在 Radarr widget 定义const widget { api: {url}/api/v3/{endpoint}?apikey{key}, proxyHandler: genericProxyHandler, mappings: { movie: { ... }, queue/status: { ... }, queue/details: { ... }, calendar: { ... }, }, };api模板声明所有请求都走 Radarrv3 API{url}、{endpoint}、{key}分别由配置项、前端请求的 endpoint 参数和key配置填充proxyHandler使用通用代理处理器 genericProxyHandler它负责拼接 URL、附加请求头、转发请求并对返回数据执行map映射。movie 映射四个统计数字的来源movie端点拉取 Radarr 的全部电影列表并在服务端完成过滤与计数widget.jsmovie: { endpoint: movie, map: (data) ({ wanted: jsonArrayFilter(data, (item) item.monitored !item.hasFile item.isAvailable).length, have: jsonArrayFilter(data, (item) item.hasFile).length, missing: jsonArrayFilter(data, (item) item.monitored !item.hasFile).length, all: asJson(data).map((entry) ({ title: entry.title, id: entry.id, })), }), },关键点wanted monitored 且没有文件且已可获取missing monitored 且没有文件不要求 isAvailable。所以wanted在逻辑上是missing的子集前者代表“真正能搜到资源”的缺口后者代表“所有应下载而未下载”的缺口movies块显示的have hasFile 的电影数即已入库的电影总量all保留{ title, id }的轻量映射供详细队列通过movieId反查电影标题使用jsonArrayFilter与asJson来自 API 辅助函数asJson把 Buffer 响应解析为 JSONjsonArrayFilter先解析再按谓词过滤二者均对非数组数据做容错处理。queue/status 与 queue/detailsqueue/status端点只返回队列概况校验字段totalCount对应统计块「Queued」的数字widget.jsqueue/details端点拉取完整队列并做两件事widget.js字段精简映射只保留trackedDownloadState、trackedDownloadStatus、timeleft、size、sizeleft、movieId缺失时回退到id与status排序正在下载status或trackedDownloadState为downloading的任务排在最前其余任务按剩余比例sizeLeft / size升序排列——剩余比例越小越接近完成越靠前。该排序逻辑由测试用例显式验证在 widget 测试 中一个status: downloading、sizeleft/size 50%的任务被排在status: queued且 size 为 0 的任务之前断言结果[2, 1]与预期一致。calendar 端点映射中还声明了calendar端点widget.js透传start、end、unmonitored三个查询参数供日历类功能复用当前组件 UI 未直接使用。前端渲染与状态呈现统计块与加载态组件在数据未就绪时渲染四个占位块就绪后填入计数component.jsxBlock labelradarr.wanted value{t(common.number, { value: moviesData.wanted })} / Block labelradarr.missing value{t(common.number, { value: moviesData.missing })} / Block labelradarr.queued value{t(common.number, { value: queuedData.totalCount })} / Block labelradarr.movies value{t(common.number, { value: moviesData.have })} /任一请求失败时组件会显示错误容器而非崩溃优先展示最早失败的请求错误。队列条目的进度与状态计算队列条目的两个核心数值由以下两个函数计算component.jsxfunction getProgress(sizeLeft, size) { if (!Number.isFinite(size) || size 0) return 0; return Math.min(100, Math.max(0, (1 - sizeLeft / size) * 100)); }当size非法或为 0如刚加入队列尚无元数据时进度视为 0否则进度 (1 - sizeLeft / size) * 100并夹在 0~100 之间。function formatDownloadState(downloadState) { switch (downloadState) { case importBlocked: return import blocked; case importPending: return import pending; case failedPending: return failed pending; default: return downloadState; } }getActivity会优先使用 Radarr 的trackedDownloadState当任务status为completed且处于importBlocked/importPending/importing/failedPending这类“已完成但待处理”状态时显示对应的导入/失败等待状态否则回退到status或trackedDownloadState原值。组件测试component.test.jsx用两组典型数据验证了完整链路queued任务显示activityqueued / progress0completed importPending任务显示activityimport pending / progress100并断言四个统计块的值分别为 wanted1、missing2、queued1、movies3。组件是如何被代理调用的前端通过useWidgetAPI(widget, endpoint)发起请求component.jsx最终落到服务端通用代理处理器 genericProxyHandler根据group、service、index从配置中解析出 widget 定义用 formatApiCall 按api模板生成目标 URL{url}/api/v3/{endpoint}?apikey{key}多余的?会被替换为合并请求头若配置了username/password会附加 Basic AuthRadarr 场景通常只用key发起 HTTP 转发200响应经validateWidgetData校验后执行映射map错误响应会返回脱敏后的 hostnamesanitizeErrorURL避免在页面暴露完整内网地址与查询串。这也解释了为什么 widget 配置中的url、key会被同时用于多个端点所有请求都走同一个api模板与同一个代理入口。配置速查与排错建议# services.yaml 中 Radarr 服务的完整 widget 配置 widget: type: radarr url: http://radarr.host.or.ip # Radarr 地址确保 Homepage 可达 key: apikeyapikeyapikeyapikeyapikey # Settings General 中获取 enableQueue: true # 可选默认 false开启详细队列常见问题排查统计块全部显示错误先确认url从 Homepage 所在容器/主机可访问再核对key是否与 RadarrSettings General中的 API Key 一致v3 API 以 query 参数apikey传参配置即映射到该参数enableQueue: true但看不到队列条目这是正常行为。源码要求queue/details返回非空数组才渲染component.jsx队列为空时不展示列表队列条目标题显示 UnknownmovieId无法在movie接口返回的all映射中匹配到电影时会回退到翻译键radarr.unknown语言包通常是电影刚从队列移除或数据未同步所致监控状态影响计数wanted/missing只统计monitored: true的电影未被监控的条目不会进入缺口统计。总结Homepage 的 Radarr 组件是一个“配置驱动 服务端映射 前端渲染”三层的典型服务组件YAML 配置只负责声明type、url、key与可选开关widget.js 定义 v3 API 端点与数据映射含计数过滤、队列排序component.jsx 负责统计块与详细队列条目的渲染两条测试链路widget.test.js、component.test.jsx则锁定了排序与渲染行为。掌握这些层级关系后你不仅能快速接入 Radarr也能举一反三理解 Homepage 中其他 API 型服务组件如 Sonarr、Readarr 等同族组件的接入套路。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考