Homepage 项目 ruTorrent 组件接入指南基于 httprpc 插件的种子状态监控面板【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文讲解如何在 Homepage一个高度可定制的起始页 / 应用仪表盘项目中接入 ruTorrent 服务组件通过官方httprpc插件实时展示活动种子数、上传速率与下载速率。读完本文你将掌握 ruTorrent 组件的 YAML 配置方法、active/upload/download三个字段的语义以及该组件在 Homepage 源码中的请求构造、数据解析与前端统计逻辑能够独立完成配置排障与二次理解。前置条件ruTorrent 端要求在 Homepage 中启用 ruTorrent 组件之前需要确认目标 ruTorrent 实例满足以下条件httprpc插件必须已安装并启用。该插件是 ruTorrent 默认插件集的一部分除非你曾显式删除或禁用它否则默认状态下即可直接使用。网络可达Homepage 所在环境需要能够访问 ruTorrent 的 Web 地址HTTP/HTTPS 均可取决于你的部署方式。认证信息可选如果 ruTorrent 前端配置了登录认证需要在组件配置中提供用户名与密码若未启用认证则无需填写。httprpc插件是 ruTorrent 的 HTTP-RPC 接口层Homepage 正是通过调用它来获取种子列表的原始数据详见下文源码分析因此这一前置条件是整个组件能否工作的关键。组件配置方法在 Homepage 的services.yaml即 src/skeleton/services.yaml 所示的骨架配置结构中为对应服务组添加widget配置块即可启用 ruTorrent 组件widget: type: rutorrent url: http://rutorrent.host.or.ip username: username # optional, false if not used password: password # optional, false if not used各参数说明如下参数必填说明type是固定为rutorrent用于声明组件类型url是ruTorrent 服务的访问地址如http://rutorrent.host.or.ip或https://rutorrent.example.comusername否认证用户名若 ruTorrent 未启用认证可省略或不填password否认证密码与username配套使用配置中的注释也提示了这一点username和password均为可选字段未使用时设置为false或不填写即可。组件支持的数据字段ruTorrent 组件允许在 widget 配置中展示的字段Allowed fields为[active, upload, download]这三个字段分别代表active当前处于活动状态正在下载或上传的种子数量upload所有种子的合计上传速率download所有种子的合计下载速率。在 Homepage 的界面配置如按字段定制显示顺序或布局时中应仅使用上述三个字段名。源码级解析数据是如何取到的请求入口与 API 端点组件入口定义在 src/widgets/rutorrent/widget.js它声明了组件使用的 API 地址模板与代理处理器const widget { api: {url}/plugins/httprpc/action.php, proxyHandler: rutorrentProxyHandler, };可以看到Homepage 会向{url}/plugins/httprpc/action.php发起请求这正是 ruTorrenthttprpc插件的 RPC 端点。{url}会被替换为配置中的url字段值。代理层POST 请求与 Basic Auth实际请求由 src/widgets/rutorrent/proxy.js 中的rutorrentProxyHandler完成关键流程如下从请求参数中读取group、service、index并调用getServiceWidget来自 src/utils/config/service-helpers.js获取服务对应的 widget 配置通过formatApiCallsrc/utils/proxy/api-helpers.js把{url}/plugins/httprpc/action.php模板展开为真实地址若配置中存在username则在请求头中附加 Basic 认证headers.Authorization Basic ${Buffer.from(${widget.username}:${widget.password}).toString(base64)};使用httpProxysrc/utils/proxy/http.js以POST方法、请求体为modelist的方式调用 ruTorrent RPC获取全部种子列表若 HTTP 状态码不是200记录错误日志并返回对应错误否则解析返回的 JSON。响应解析34 字段的种子信息映射httprpc的modelist响应结构为{ t: { hash: [字段数组...] } }其中每个 hash 对应一个种子字段数组是一组位置固定的取值。proxy.js中的getTorrentInfo函数把数组按位置映射为语义化键名代码注释标明该映射参考自node-rutorrent-promise项目共 34 个字段包括状态类d.is_open、d.is_hash_checking、d.is_hash_checked、d.get_state、d.is_active、d.is_private、d.is_multi_file速率与进度类d.get_up_rate上传速率、d.get_down_rate下载速率、d.get_bytes_done、d.get_left_bytes、d.get_size_bytes、d.get_ratio、d.get_completed_chunks、d.get_size_chunks元信息类d.get_name、d.get_size_bytes、d.get_creation_date、d.get_base_path、d.get_message、d.get_tracker_focus、d.get_free_diskspace等。解析完成后代理把对象数组以 JSON 形式返回给前端组件。此逻辑在 src/widgets/rutorrent/proxy.test.js 中有对应测试模拟httpProxy返回包含一个 hash、34 个零值字段的响应断言解析结果是一个数组且d.get_name可被正确读取。前端组件三项指标的统计口径前端渲染逻辑位于 src/widgets/rutorrent/component.jsx它通过useWidgetAPIsrc/utils/proxy/use-widget-api.js获取上述代理返回的数据然后进行统计const upload statusData.reduce((acc, torrent) acc parseInt(torrent[d.get_up_rate], 10), 0); const download statusData.reduce((acc, torrent) acc parseInt(torrent[d.get_down_rate], 10), 0); const active statusData.filter((torrent) torrent[d.get_state] 1);upload对所有种子的d.get_up_rate求和得到总上传速率download对所有种子的d.get_down_rate求和得到总下载速率active筛选出d.get_state 1状态为活动的种子并统计数量。最终组件渲染三个数据块上传与下载速率通过t(common.byterate, { value })格式化为可读的字节速率展示如 KB/s、MB/s。三个块对应的显示文案定义在 public/locales/en/common.json 中rutorrent: { active: Active, upload: Upload, download: Download }加载中或出错时组件会分别展示三个占位块或错误提示Container的error分支这一行为在 src/widgets/rutorrent/component.test.jsx 中有完整覆盖包括加载占位渲染、API 出错渲染以及给定三组种子数据后统计出active2、upload30、download20的聚合计算验证。常见问题与排障思路组件不显示数据 / 显示 HTTP Error优先确认 ruTorrent 的httprpc插件是否启用其次确认url在 Homepage 环境下可访问注意是否为内网地址、是否存在反向代理路径前缀。代理层在非 200 状态时会返回HTTP Error及对应状态码可据此判断是地址错误还是认证失败。401 / 认证失败确认username与password与 ruTorrent 的认证配置一致未启用认证时请移除或置空这两个字段避免发送无效的 Basic 头。JSON 解析失败httprpc的modelist响应必须是标准 JSON 结构。若 ruTorrent 版本或插件配置异常导致返回非预期内容代理层会返回Error parsing rutorrent data提示对应proxy.js中的捕获分支。速率显示为 0 或异常注意upload/download是所有种子的求和值且依赖d.get_up_rate/d.get_down_rate字段若对应种子处于暂停或停止状态这些字段会为 0属正常现象。小结ruTorrent 组件是 Homepage 下载类服务面板中的常用组件之一其核心链路可以概括为services.yaml声明type: rutorrent→ 代理层向{url}/plugins/httprpc/action.php发送modelist的 POST 请求可选 Basic Auth→ 解析 34 字段种子信息 → 前端聚合出活动种子数、总上传与下载速率。结合本文的源码路径你可以快速定位问题所在也可以基于getTorrentInfo的字段映射扩展更多展示维度。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考