Homepage 集成 PeaNUT UPS Widget：NUT 不间断电源监控的配置、字段映射与源码解析

Homepage 集成 PeaNUT UPS WidgetNUT 不间断电源监控的配置、字段映射与源码解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文介绍如何在 Homepage 仪表盘中通过 PeaNUT Widget 实时监控 Network UPS Tools (NUT) 管理的不间断电源UPS涵盖前置依赖、YAML 配置参数、多 UPS 实例拆分、字段映射与状态语义并结合仓库源码说明 Widget 背后的 API 请求链路与数据校验逻辑。读完本文你将能独立完成 UPS 监控 Widget 的配置、排错与界面理解。前置条件先有 NUT再有 PeaNUT然后才是 Homepage WidgetHomepage 的peanut类型 Widget 本身并不直接与 NUT 服务通信而是通过第三方工具PeaNUT一个面向 Network UPS Tools 的 Web 前端/API 网关读取 UPS 数据这一点在 官方 Widget 文档 中有明确说明。因此完整的数据链路为NUTupsd / upsc 守护进程 → PeaNUTREST API → Homepage Widget浏览器端渲染此外官方文档也提示如果不想引入 PeaNUT存在其他通过customapiWidget 实现类似效果的项目例如 NUTCase。因此本节建议先确认 PeaNUT 服务已部署且可访问再继续后续配置。最小可用配置一段 YAML 接入 UPS在 Homepage 的services.yaml仓库内置示例见 src/skeleton/services.yaml中为一个服务组添加如下 Widget 配置widget: type: peanut url: http://peanut.host.or.ip:port key: nameofyourups username: username # only needed if set password: password # only needed if set保存配置并刷新页面后服务卡片上会显示三块信息Battery Charge电池电量、UPS Load负载与UPS Status状态。核心参数逐个拆解参数必填默认值说明type是—固定为peanuturl是—PeaNUT 服务的地址格式为http://主机或IP:端口key是ups要监控的 UPS 名称对应 NUT 中的 upsnameusername否—仅当 PeaNUT 启用了认证时需要password否—仅当 PeaNUT 启用了认证时需要关于key的默认值官方文档明确指出默认 UPS 名称是upsNUT 默认配置下的标准 upsname。如果你的 NUT 配置了其他名称则必须通过key显式指定。底层原理Widget 如何拿到 UPS 数据API 模板与占位符替换Homepage 的每个 Widget 都由一个定义文件描述其 API 形态PeaNUT 的定义位于 src/widgets/peanut/widget.jsconst widget { api: {url}/api/v1/{endpoint}/{key}, proxyHandler: genericProxyHandler, mappings: { devices: { endpoint: devices }, }, };其中{url}、{endpoint}、{key}三个占位符会在请求时被替换。替换逻辑在 src/utils/proxy/api-helpers.js 的formatApiCall中实现其正则/\{.*?\}/g会匹配花括号内的键名并到 Widget 配置中取值同时对url做了去尾斜杠处理value.replace(/\/$/, )避免http://host:port/与模板拼接后出现双斜杠。结合mappings.devices.endpoint devices实际请求 URL 即http://peanut.host.or.ip:port/api/v1/devices/{key}代理处理器与 Basic AuthWidget 的请求统一经由genericProxyHandlersrc/utils/proxy/handlers/generic.js在服务端转发而非浏览器直接跨域调用。其中与 PeaNUT 配置直接相关的两点Basic 认证注入当配置中同时提供了username与password时处理器会拼接Authorization: Basic base64(username:password)请求头见 generic.js 中Buffer.from(...).toString(base64)的实现。这正是官方配置注释 only needed if set 的源码依据——两者必须同时存在才会启用认证。数据校验返回数据会经过validateWidgetData检查若结构不符合预期HTTP 200 但字段非法前端会收到 Invalid data 错误而非渲染脏数据。前端数据流与字段映射组件实现位于 src/widgets/peanut/component.jsx它通过useWidgetAPI(widget, devices)对应 src/utils/proxy/use-widget-api.js基于 SWR 的封装拉取数据然后兼容 PeaNUT v1 的旧字段名若返回数据中存在battery.charge、ups.load、ups.status这类点分命名PeaNUT v1 格式会自动映射为battery_charge、ups_load、ups_status保证新旧版本 API 都能正常渲染。这一逻辑由 src/widgets/peanut/component.test.jsx 中的 renders legacy field mapping and status translation 用例覆盖。状态码翻译NUT 的ups.status是短码枚举组件将其转换为可读文案原始值含义对应翻译键OLOnline市电在线peanut.onlineOBOn Battery电池供电peanut.on_batteryLBLow Battery电池电量低peanut.low_battery其他原样展示—翻译文案定义在 public/locales/en/common.json 的peanut命名空间下battery_charge、ups_load、ups_status、online、on_battery、low_battery其他语言可通过对应 locale 文件本地化。百分比渲染battery_charge与ups_load会通过common.percent翻译键渲染为带%的数值并以数值本身作为高亮阈值highlightValue。多 UPS 监控一个 UPS 一个 Widget官方文档明确要监控多个 UPS必须为每个 UPS 创建独立的 peanut 服务。原因是 Widget 的key字段是单值配置一次只能指向一个 UPS。典型做法是在同一服务组下并列多个条目例如- UPS 主机: widget: type: peanut url: http://peanut.host.or.ip:port key: ups - UPS 机房: widget: type: peanut url: http://peanut.host.or.ip:port key: rackups加载、错误与空白占位行为从组件实现看三个展示块在数据尚未返回时即以占位形式渲染Block labelpeanut.battery_charge /等不传value因此首屏会先出现三块灰色占位数据到达后填充真实数值。若useWidgetAPI返回错误整个 Container 会进入错误态配合 Homepage 的全局错误处理展示具体原因URL 中的敏感信息如认证字段会在错误日志中被sanitizeErrorURL脱敏为仅保留 hostname。验证与排错建议在浏览器直接访问http://peanut.host.or.ip:port/api/v1/devices/ups确认返回 JSON 中包含battery.charge/ups.load/ups.statusv1 风格或battery_charge/ups_load/ups_status新版风格字段若配置了认证先在浏览器用 Basic Auth 方式验证账号密码是否可用在 Homepage 中确认url未写错端口、key与 NUT 中实际的 UPS 名称一致若仍失败查看 Homepage 服务端日志中的 HTTP Error %d calling... 调试信息由 genericProxyHandler 输出其中会保留协议与主机名用于定位。小结PeaNUT Widget 是 Homepage 为数不多面向硬件电源场景的开箱即用集成只需一段 YAML 即可把 NUT 生态的 UPS 数据搬上仪表盘并且仓库源码同时兼容 PeaNUT v1 与新版字段命名状态短码也会被自动翻译为直观文案。结合服务端代理、Basic Auth 注入与数据校验机制整个链路在安全性与健壮性上都有保障。对于多 UPS 机房场景按一个 UPS 一个 Widget 实例的方式横向扩展即可。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考