Homepage 接入 QNAP NASQNAP 监控 Widget 配置详解与实现原理【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读本文以 QNAP Widget 文档 为主体讲解如何在 Homepage 首页仪表盘中接入 QNAP NAS实时展示 CPU 使用率、内存使用率、系统温度和存储池/卷空间占用。文章不仅覆盖完整配置示例与参数说明还结合仓库中src/widgets/qnap/目录下的代理层、前端组件与测试用例剖析登录鉴权、会话令牌缓存、多卷聚合等底层实现帮助你不仅会配更知道它为什么这样工作。QNAP Widget 能展示什么QNAP Widget 属于 Homepage 的服务类 Widget以widget.type: qnap声明后会在服务卡片内渲染 4 个指标块对应文档中声明的允许字段字段含义前端标签public/locales/en/common.json#L252-L259cpuUsageCPU 使用率百分比CPU UsagememUsage内存使用率百分比MEM UsagesystemTempC系统温度摄氏度System TemppoolUsage存储池使用率所有卷合计Pool UsagevolumeUsage指定单个卷的使用率Volume Usage注意poolUsage与volumeUsage是二选一的关系不配置volume字段时显示poolUsage全部卷聚合配置了volume字段后则改为volumeUsage单卷跟踪。这些标签在 public/locales/en/common.json 中统一定义并通过 i18n 的common命名空间渲染因此其他语言包同样包含对应翻译。最小配置直接可用在服务的widget段写入以下内容即可接入 QNAP NAS原文档示例widget: type: qnap url: http://qnap.host.or.ip:port username: user password: pass参数说明type固定为qnap用于匹配src/widgets/qnap/widget.js导出的 Widget 定义urlQNAP 设备的管理地址需包含端口默认 Web 管理端口 8080可按实际填写username/passwordQNAP 登录凭据用于调用 NAS 的 CGI 管理接口见下文鉴权流程。单卷跟踪配置文档明确指出如果 QNAP 设备有多个卷默认的poolUsage会是所有卷的合计值。若只想跟踪某一个卷在 Widget 配置中追加volume字段即可volume: Volume Name From QNAPvolume的值必须是 QNAP 中实际的卷标签Volume Label例如DataVol1。该字段的解析在 src/utils/config/service-helpers.js#L562-L564 中与diskstation共用一段逻辑当类型为[diskstation, qnap]时若存在volume配置项则写入widget.volume随后由前端组件消费。工作原理会话令牌 两个数据接口Widget 前端通过useWidgetAPI(widget, status)见 src/widgets/qnap/component.jsx向代理层请求/status端点该端点由 src/widgets/qnap/widget.js 中的allowedEndpoints: /status/声明为唯一允许的接口。真正的数据获取全部发生在服务端代理qnapProxyHandler中src/widgets/qnap/proxy.jsQNAP 密码不会暴露给浏览器。1. 登录与令牌缓存QNAP 的 CGI 接口使用基于会话 IDsid的鉴权方式。代理层首先向{url}/cgi-bin/authLogin.cgi发送POST请求proxy.js 的 login 函数请求头为Content-Type: application/x-www-form-urlencoded表单携带user明文与pwdBase64 编码后的密码两个字段响应是 XML 格式通过xml-js的xml2json转换为 JSON 后取出QDocRoot.authSid作为会话令牌。获取到的令牌以qnapProxyHandler__sessionToken.service为键存入memory-cachesessionTokenCacheKey常量按服务维度隔离缓存。后续所有数据请求都会携带sidtoken参数。令牌无需在每次请求时重复登录这也是代理层减少对 NAS 负担的关键设计。2. 两个数据接口登录成功后代理层并行发起两个请求见 proxy.js 的 qnapProxyHandler数据接口路径用途系统信息{url}/cgi-bin/management/manaRequest.cgi?subfuncsysinfohdnomulticpu1CPU、内存、温度卷用量{url}/cgi-bin/management/chartReq.cgi?chart_funcdisk_usagedisk_selectallincludeall各卷总大小与剩余空间响应同样为 XML转 JSON 后提取QDocRoot.func.ownContent.root作为system、QDocRoot作为volume返回给前端。3. 令牌失效自动重登QNAP 会话令牌会过期。代理层对两种失效场景做了兜底请求返回HTTP 404响应中QDocRoot.authPassed._cdata 0鉴权未通过。出现以上情况时代理层会重新执行login()获取新令牌并用新令牌重试一次该请求若重试仍非 200则记录错误日志并返回data: null。整个重登重试逻辑在 proxy.js 的 apiCall 函数 中实现前端收到错误后会在容器内展示错误状态component.jsx中的statusError分支。前端指标计算逻辑src/widgets/qnap/component.jsx 将代理返回的原始 XML-JSON 数据转换为 4 个展示块CPU 使用率读取system.cpu_usage._cdata并剥离尾部的 %字符串后以百分比渲染内存使用率由total_memory与free_memory计算(total - free) / total × 100结果取整toFixed(0)系统温度读取system.sys_tempc._text按celsius单位格式化保留 1 位小数卷/池使用率优先按volumeUseList.volumeUse是否为数组区分单卷与多卷场景单卷非数组直接使用total_size与free_size多卷 未配置volume遍历volumeUse数组累加所有卷的total_size与free_size对应文档“poolUsage 是所有卷之和”的说明再计算使用率多卷 已配置volume在volumeList.volume中按volumeLabel._cdata精确匹配配置的卷名命中后取该卷的total_size/free_size计算volumeUsage若未命中例如卷名拼写错误validVolume置为false该块显示翻译键qnap.invalid即 “Invalid”避免渲染出误导性的 0%。这些计算逻辑均有测试用例覆盖例如 src/widgets/qnap/component.test.jsx 中构造total_memory 100、free_memory 25的载荷断言内存使用率渲染为75构造total_size 100、free_size 50的单卷数组断言池使用率为50。加载期间data未返回组件渲染 4 个占位 Block标签同样区分qnap.poolUsage与qnap.volumeUsage。服务端代理验证src/widgets/qnap/proxy.test.js 验证了端到端的代理流程通过 mock 依次返回“登录 → 系统信息 → 卷用量”三段 XML 响应断言代理返回 HTTP 200res.body.system为系统信息解析结果res.body.volume包含authPassed字段即完整QDocRoot对象。此外代理入口会校验req.query中的group与service参数缺失时返回 400Invalid proxy service typegetServiceWidget找不到对应 Widget 时同样返回 400。这与 Homepage 通用的服务代理模式一致可参考 docs/widgets/services/index.md 与 docs/configs/services.md 了解服务定义规范。使用前提与注意事项需要能访问管理接口代理层通过 QNAP 的/cgi-bin/管理 CGI 接口取数Widget 所在环境Homepage 容器必须能通过网络访问该地址且需在 QNAP 上开启相应管理访问权限凭据安全密码只在服务端代理层使用前端与浏览器不会接触到密码但由于登录接口按文档要求使用 Base64 编码传输建议仅在可信的内网环境使用卷名精确匹配volume字段必须与 QNAP 卷标签完全一致区分大小写否则对应指标块显示Invalid令牌生命周期会话令牌按 service 维度缓存在内存中并支持失效自动重登一般无需人工干预长时间不访问后首次请求可能因重登多一次往返属正常现象。小结QNAP Widget 是 Homepage 服务类 Widget 中典型的“登录鉴权 多接口聚合 前端计算展示”型组件widget.js定义接口与白名单proxy.js负责令牌管理与数据拉取component.jsx负责指标计算与多卷逻辑配套测试覆盖了核心路径。按本文配置type: qnap并视需要指定volume字段即可把 NAS 的关键运行指标直接钉在个人首页上。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考