Homepage 项目 APC UPS 监控 Widget 配置指南对接 apcupsd 实现不间断电源状态看板【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文以 homepage 开源项目中的 APC UPS 监控小部件type: apcups为主线介绍如何通过内置代理与apcupsd守护进程通信将 UPS 的在线状态、负载、电池电量与剩余时间直接呈现在首页服务看板上。读完本文你将掌握该 Widget 的完整 YAML 配置方法、apcupsd的网络监听调整要点以及其底层 TCP 协议解析与数据字段来源可直接落地部署。一、Widget 概述与适用前提APC UPS Widget 是 homepage 提供的轻量级监控组件用于从apcupsd守护进程提取 UPS 实时信息。项目文档明确指出其适用边界该 Widget 仅适用于 APC/Schneider 品牌的 UPS 产品如 Smart-UPS 系列因为其数据源apcupsd原生支持这些设备的串口 / USB / 网络通信。从仓库的目录结构看该功能模块完整分布在三个层次配置入口docs/widgets/services/apcups.md定义了 Widget 的公开使用方式后端代理src/widgets/apcups/proxy.js负责与 apcupsd 建立 TCP 连接并解析协议数据前端组件src/widgets/apcups/component.jsx负责将数据渲染为看板上的四个信息块。二、核心配置最小可用示例在services.yaml的任意服务分组中为某个服务条目加上widget字段即可启用监控- My UPS: icon: fas fa-battery-half href: https://your.ups.management.host widget: type: apcups url: tcp://your.acpupsd.host:3551其中两个参数是必需的参数说明type固定为apcups用于路由到本项目中的 apcups 代理处理器url采用tcp://协议的 apcupsd 地址格式为tcp://主机:端口值得注意的一点是在 homepage 的 Widget 体系中绝大多数 Widget 的url是 HTTP(S) API 地址而 apcups 走的是裸 TCP 协议。这一点在 src/widgets/apcups/widget.test.js 的测试断言中有明确印证——测试注释写道 “apcups talks TCP directly, so it does not use an{url}/...API template”并断言widget.api为undefined。也就是说它不经过通用的 HTTP API 模板层而是由专用代理直接建立 socket 连接。三、关键前置步骤让 apcupsd 允许局域网访问apcupsd默认只监听本机回环地址127.0.0.1而 homepage 通常以 Docker 容器方式运行在宿主机或另一台机器上两者无法直接通信。官方文档给出了明确的操作指引编辑/etc/apcupsd.conf将NISIP改为 homepage Docker 容器可达的 IP通常是你的内网 LAN 接口 IP。修改完成后需要重启 apcupsd 服务使配置生效。典型配置片段如下# /etc/apcupsd.conf NISIP 192.168.1.10 NISPORT 3551NISIP控制网络信息服务Network Information Server的绑定地址NISPORT默认为3551与 Widget 的url端口保持一致。若 homepage 与 apcupsd 位于同一台宿主机也可以直接填写宿主机 LAN IP而非127.0.0.1。从安全角度考虑由于该端口对外暴露了 UPS 状态查询能力建议仅在可信内网开放并通过防火墙限制来源。四、源码级解析代理如何与 apcupsd 通信理解了配置之后深入 src/widgets/apcups/proxy.js 可以看到完整的实现链路这对排查问题、理解字段来源非常有帮助。4.1 请求路由页面侧通过 src/utils/proxy/use-widget-api.js 发起请求该 Hook 将 Widget 的service_group、service_name、index拼装为/api/services/proxy?...的查询参数服务端由 src/pages/api/services/proxy.js 统一分发根据type从widgets注册表中取出对应 Widget若其存在proxyHandler则直接调用。apcups 的代理处理器即src/widgets/apcups/proxy.js中导出的apcupsProxyHandler。4.2 建立 TCP 连接并发送命令getStatus(host, port)函数使用 Node.js 原生net.Socket建立 TCP 连接并设置了5 秒超时socket.setTimeout(5000)。连接成功后向守护进程发送status命令const CMD status; const buffer Buffer.alloc(CMD.length 2); buffer.writeUInt16BE(CMD.length, 0); buffer.write(CMD, 2); socket.write(buffer);这里有一个重要的协议细节apcupsd 的 NIS 协议采用2 字节大端长度前缀 ASCII 数据的帧格式即每条消息先写入命令长度16 位无符号大端整数再写入命令本身。客户端读取响应时也遵循同样的帧结构。4.3 响应解析响应数据到达后parseResponse按相同帧格式逐条解包function parseResponse(buffer) { let ptr 0; const output []; while (ptr buffer.length) { const lineLen buffer.readUInt16BE(ptr); const asciiData buffer.toString(ascii, ptr 2, lineLen ptr 2); output.push(asciiData); ptr 2 lineLen; } return output; }随后statusAsJSON将KEY: VALUE形式的行转换为 JSON 对象并跳过END APC结束标记function statusAsJSON(statusOutput) { return statusOutput?.reduce((output, line) { if (!line || line.startsWith(END APC)) return output; const [key, value] line.trim().split(:); const newOutput { ...output }; newOutput[key.trim()] value?.trim(); return newOutput; }, {}); }最终代理只透出四个核心字段见 src/widgets/apcups/proxy.js返回字段对应 apcupsd 原始键含义statusSTATUSUPS 在线状态如ONLINEloadLOADPCT当前负载百分比bchargeBCHARGE电池剩余电量百分比timeleftTIMELEFT电池剩余供电时间如果连接失败、超时或响应异常代理会返回500并在响应体中携带错误信息缺少group或service参数时则返回400。五、前端展示与多语言标签前端组件 src/widgets/apcups/component.jsx 通过useWidgetAPI拉取上述代理接口用四个Block组件分别渲染状态apcups.status负载apcups.load电池电量apcups.bcharge剩余时间apcups.timeleft数据加载期间会先显示占位块加载完成后替换为真实数值。这些apcups.*标签是 i18n 翻译键在 public/locales/en/common.json 中对应英文标签apcups: { status: Status, load: Load, bcharge: Battery Charge, timeleft: Time Left }项目自带 zh-Hans、zh-Hant、ja、ko 等多语言翻译文件界面语言跟随浏览器或全局设置自动切换。六、测试用例协议行为的可验证依据仓库为 apcups Widget 提供了完整的单元测试可作为理解协议行为的参考实现src/widgets/apcups/proxy.test.js 使用模拟的node:net.Socket按真实帧格式构造响应每条记录encodeLine写入长度前缀结尾追加\x00\x00终止标记验证了STATUS : ONLINE、LOADPCT : 10.0、BCHARGE : 99.0、TIMELEFT : 12.3能被正确解析为 JSON 并返回200。该测试同时验证了响应结束判定逻辑当数据末尾的 2 字节为0时认为响应完整。src/widgets/apcups/component.test.jsx 验证了加载占位与数据渲染两种状态确保四个信息块正确展示。如果你想在接入前快速验证 apcupsd 是否可达可在 homepage 所在主机执行# 直接与 apcupsd 的 NIS 端口建立连接并发送 status 命令 printf \x00\x06status | timeout 5 nc your.acpupsd.host 3551若返回包含STATUS : ONLINE等键值行并以END APC结束则说明网络与守护进程配置正常。七、常见问题与排查要点现象可能原因处理建议页面显示错误/无数据homepage 容器访问不到 apcupsd确认NISIP已改为 LAN IP 而非127.0.0.1并重启 apcupsd代理返回socket timeout防火墙拦截或 apcupsd 未运行检查3551端口连通性确认NISPORT未被改动Unknown proxy service typetype拼写错误确保type: apcups完全一致数据为 0/空值设备非 APC 品牌或 apcupsd 未读到数据先在 apcupsd 本机运行apcaccess status确认数据源正常结语apcups Widget 是 homepage 中少有的“裸 TCP 直连”类监控组件通过内置代理将 apcupsd 的 NIS 协议透明地桥接为 JSON API。理解其配置三要素type、url、NISIP调整与协议帧格式即可在数分钟内为首页看板接入 APC UPS 的实时健康状态。更多服务型 Widget 的通用配置规范可参考 docs/widgets/services/index.md整体服务编排语法见 docs/configs/services.md。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Homepage 项目 APC UPS 监控 Widget 配置指南：对接 apcupsd 实现不间断电源状态看板
Homepage 项目 APC UPS 监控 Widget 配置指南对接 apcupsd 实现不间断电源状态看板【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文以 homepage 开源项目中的 APC UPS 监控小部件type: apcups为主线介绍如何通过内置代理与apcupsd守护进程通信将 UPS 的在线状态、负载、电池电量与剩余时间直接呈现在首页服务看板上。读完本文你将掌握该 Widget 的完整 YAML 配置方法、apcupsd的网络监听调整要点以及其底层 TCP 协议解析与数据字段来源可直接落地部署。一、Widget 概述与适用前提APC UPS Widget 是 homepage 提供的轻量级监控组件用于从apcupsd守护进程提取 UPS 实时信息。项目文档明确指出其适用边界该 Widget 仅适用于 APC/Schneider 品牌的 UPS 产品如 Smart-UPS 系列因为其数据源apcupsd原生支持这些设备的串口 / USB / 网络通信。从仓库的目录结构看该功能模块完整分布在三个层次配置入口docs/widgets/services/apcups.md定义了 Widget 的公开使用方式后端代理src/widgets/apcups/proxy.js负责与 apcupsd 建立 TCP 连接并解析协议数据前端组件src/widgets/apcups/component.jsx负责将数据渲染为看板上的四个信息块。二、核心配置最小可用示例在services.yaml的任意服务分组中为某个服务条目加上widget字段即可启用监控- My UPS: icon: fas fa-battery-half href: https://your.ups.management.host widget: type: apcups url: tcp://your.acpupsd.host:3551其中两个参数是必需的参数说明type固定为apcups用于路由到本项目中的 apcups 代理处理器url采用tcp://协议的 apcupsd 地址格式为tcp://主机:端口值得注意的一点是在 homepage 的 Widget 体系中绝大多数 Widget 的url是 HTTP(S) API 地址而 apcups 走的是裸 TCP 协议。这一点在 src/widgets/apcups/widget.test.js 的测试断言中有明确印证——测试注释写道 “apcups talks TCP directly, so it does not use an{url}/...API template”并断言widget.api为undefined。也就是说它不经过通用的 HTTP API 模板层而是由专用代理直接建立 socket 连接。三、关键前置步骤让 apcupsd 允许局域网访问apcupsd默认只监听本机回环地址127.0.0.1而 homepage 通常以 Docker 容器方式运行在宿主机或另一台机器上两者无法直接通信。官方文档给出了明确的操作指引编辑/etc/apcupsd.conf将NISIP改为 homepage Docker 容器可达的 IP通常是你的内网 LAN 接口 IP。修改完成后需要重启 apcupsd 服务使配置生效。典型配置片段如下# /etc/apcupsd.conf NISIP 192.168.1.10 NISPORT 3551NISIP控制网络信息服务Network Information Server的绑定地址NISPORT默认为3551与 Widget 的url端口保持一致。若 homepage 与 apcupsd 位于同一台宿主机也可以直接填写宿主机 LAN IP而非127.0.0.1。从安全角度考虑由于该端口对外暴露了 UPS 状态查询能力建议仅在可信内网开放并通过防火墙限制来源。四、源码级解析代理如何与 apcupsd 通信理解了配置之后深入 src/widgets/apcups/proxy.js 可以看到完整的实现链路这对排查问题、理解字段来源非常有帮助。4.1 请求路由页面侧通过 src/utils/proxy/use-widget-api.js 发起请求该 Hook 将 Widget 的service_group、service_name、index拼装为/api/services/proxy?...的查询参数服务端由 src/pages/api/services/proxy.js 统一分发根据type从widgets注册表中取出对应 Widget若其存在proxyHandler则直接调用。apcups 的代理处理器即src/widgets/apcups/proxy.js中导出的apcupsProxyHandler。4.2 建立 TCP 连接并发送命令getStatus(host, port)函数使用 Node.js 原生net.Socket建立 TCP 连接并设置了5 秒超时socket.setTimeout(5000)。连接成功后向守护进程发送status命令const CMD status; const buffer Buffer.alloc(CMD.length 2); buffer.writeUInt16BE(CMD.length, 0); buffer.write(CMD, 2); socket.write(buffer);这里有一个重要的协议细节apcupsd 的 NIS 协议采用2 字节大端长度前缀 ASCII 数据的帧格式即每条消息先写入命令长度16 位无符号大端整数再写入命令本身。客户端读取响应时也遵循同样的帧结构。4.3 响应解析响应数据到达后parseResponse按相同帧格式逐条解包function parseResponse(buffer) { let ptr 0; const output []; while (ptr buffer.length) { const lineLen buffer.readUInt16BE(ptr); const asciiData buffer.toString(ascii, ptr 2, lineLen ptr 2); output.push(asciiData); ptr 2 lineLen; } return output; }随后statusAsJSON将KEY: VALUE形式的行转换为 JSON 对象并跳过END APC结束标记function statusAsJSON(statusOutput) { return statusOutput?.reduce((output, line) { if (!line || line.startsWith(END APC)) return output; const [key, value] line.trim().split(:); const newOutput { ...output }; newOutput[key.trim()] value?.trim(); return newOutput; }, {}); }最终代理只透出四个核心字段见 src/widgets/apcups/proxy.js返回字段对应 apcupsd 原始键含义statusSTATUSUPS 在线状态如ONLINEloadLOADPCT当前负载百分比bchargeBCHARGE电池剩余电量百分比timeleftTIMELEFT电池剩余供电时间如果连接失败、超时或响应异常代理会返回500并在响应体中携带错误信息缺少group或service参数时则返回400。五、前端展示与多语言标签前端组件 src/widgets/apcups/component.jsx 通过useWidgetAPI拉取上述代理接口用四个Block组件分别渲染状态apcups.status负载apcups.load电池电量apcups.bcharge剩余时间apcups.timeleft数据加载期间会先显示占位块加载完成后替换为真实数值。这些apcups.*标签是 i18n 翻译键在 public/locales/en/common.json 中对应英文标签apcups: { status: Status, load: Load, bcharge: Battery Charge, timeleft: Time Left }项目自带 zh-Hans、zh-Hant、ja、ko 等多语言翻译文件界面语言跟随浏览器或全局设置自动切换。六、测试用例协议行为的可验证依据仓库为 apcups Widget 提供了完整的单元测试可作为理解协议行为的参考实现src/widgets/apcups/proxy.test.js 使用模拟的node:net.Socket按真实帧格式构造响应每条记录encodeLine写入长度前缀结尾追加\x00\x00终止标记验证了STATUS : ONLINE、LOADPCT : 10.0、BCHARGE : 99.0、TIMELEFT : 12.3能被正确解析为 JSON 并返回200。该测试同时验证了响应结束判定逻辑当数据末尾的 2 字节为0时认为响应完整。src/widgets/apcups/component.test.jsx 验证了加载占位与数据渲染两种状态确保四个信息块正确展示。如果你想在接入前快速验证 apcupsd 是否可达可在 homepage 所在主机执行# 直接与 apcupsd 的 NIS 端口建立连接并发送 status 命令 printf \x00\x06status | timeout 5 nc your.acpupsd.host 3551若返回包含STATUS : ONLINE等键值行并以END APC结束则说明网络与守护进程配置正常。七、常见问题与排查要点现象可能原因处理建议页面显示错误/无数据homepage 容器访问不到 apcupsd确认NISIP已改为 LAN IP 而非127.0.0.1并重启 apcupsd代理返回socket timeout防火墙拦截或 apcupsd 未运行检查3551端口连通性确认NISPORT未被改动Unknown proxy service typetype拼写错误确保type: apcups完全一致数据为 0/空值设备非 APC 品牌或 apcupsd 未读到数据先在 apcupsd 本机运行apcaccess status确认数据源正常结语apcups Widget 是 homepage 中少有的“裸 TCP 直连”类监控组件通过内置代理将 apcupsd 的 NIS 协议透明地桥接为 JSON API。理解其配置三要素type、url、NISIP调整与协议帧格式即可在数分钟内为首页看板接入 APC UPS 的实时健康状态。更多服务型 Widget 的通用配置规范可参考 docs/widgets/services/index.md整体服务编排语法见 docs/configs/services.md。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考