Homepage TrueNAS 存储监控 Widget 完整指南REST 与 WebSocket 双协议接入、认证与存储池容量监控【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageHomepage 的 TrueNAS Widget 可以在个人首页中直接展示 TrueNAS 服务器的系统负载、运行时长与未处理告警并可选展示存储池ZFS Pool的健康状态与容量使用情况。本文以仓库文档 docs/widgets/services/truenas.md 为核心结合 src/widgets/truenas 目录下的源码与测试完整讲解版本与协议选择、认证方式、YAML 配置参数、展示字段含义以及底层代理实现原理帮助你一步到位地在自己的配置文件中接入 TrueNAS 监控。TrueNAS Widget 能做什么TrueNAS Widget 是 Homepage 众多服务型 Widget 之一完整清单见 src/widgets/widgets.js 与 src/widgets/components.js它将 TrueNAS 的 REST/WebSocket API 数据转化为首页上的一组紧凑信息块load系统负载取自system/infoREST或system.infoWebSocket返回的loadavg字段uptime运行时长取自同一接口的uptime_seconds字段alerts未处理告警取自alert/listREST或alert.listWebSocket仅统计未被 dismissed 的告警数量pools存储池列表可选开启enablePools后展示每个 ZFS 池的名称、健康状态healthy 布尔值以及已用/可用容量和占用百分比。从 UI 组件 src/widgets/truenas/component.jsx 的调用可以看到Widget 默认并发请求alerts与status两个端点只有当enablePools为真时才额外请求pools与dataset两个端点。也就是说池容量监控是默认关闭的可选能力这一点与文档中“A detailed pool listing is disabled by default”的描述完全一致。版本与协议选择v1REST与 v2WebSocket文档给出了 Homepage Widget 版本与 TrueNAS 版本/协议的对应关系这是配置时最先要确认的一件事TrueNAS 版本Homepage widget version 26.04REST API1默认 25.04WebSocket API2version 1默认值走 REST API请求格式为{url}/api/v2.0/{endpoint}。该模板定义在 src/widgets/truenas/widget.js 的api字段中最终由通用的 credentialed 代理处理器执行version 2走 WebSocket API连接地址为{url}/api/current见 src/widgets/truenas/widget.js 的wsAPI字段。在代理层版本号决定走哪条链路。见 src/widgets/truenas/proxy.jsNumber(widget.version ?? 1)小于 2 时直接转交给通用的credentialedProxyHandler走 REST等于或大于 2 时则进入 WebSocket 专用处理逻辑。也就是说只要在配置里写version: 2Homepage 就会自动改用 WebSocket 通道获取数据。从源码结构看v2 的每个端点都同时保留了 REST 端点与 WebSocket 方法名的映射关系展示用途REST endpointWebSocket 方法说明statussystem/infosystem.info返回loadavg与uptime_secondsalertsalert/listalert.list过滤出未被 dismissed 的告警并计数poolspoolpool.query返回池的id、name、healthydatasetpool/datasetpool.dataset.query提供池容量used.parsed/available.parsed这些映射全部定义在 src/widgets/truenas/widget.js 的mappings对象中。v1 模式下仅api模板与endpoint拼接生效v2 模式下代理会通过mappings反向查找endpoint对应的wsMethod见 src/widgets/truenas/proxy.js。认证方式API Key 与用户名/密码文档明确说明创建 API Key 的入口在 TrueNAS 官方文档的 “Managing API Keys” 章节。在 Homepage 侧两种认证方式对应的配置字段为keyTrueNAS API Keyusername/passwordTrueNAS 登录账号与密码未提供 API Key 时使用。两种认证方式在两条协议链路中都有实现RESTv1链路见 src/utils/proxy/handlers/credentialed.js。对truenas类型若配置了key请求头使用Authorization: Bearer key否则回退为 Basic Authusername:password的 Base64 编码。这一点也被 src/utils/proxy/handlers/credentialed.test.js 的测试用例覆盖。WebSocketv2链路见 src/widgets/truenas/proxy.js 的authenticate函数。连接建立后优先调用auth.login_with_api_key方法传入 API Key若返回true则通过否则降级尝试auth.login用户名/密码两者都失败则抛出 “TrueNAS authentication failed”。需要特别注意的是源码中的一个安全细节v2 WebSocket 链路中只要配置了 API Key连接就会被强制升级为wss:安全协议见 src/widgets/truenas/proxy.js 的useSecure wsUrl.protocol https: || Boolean(widget.key)。因此如果你使用 API Key 且 TrueNAS 未开启 HTTPS/WSS连接可能无法建立——这属于 v2 API Key 组合下的隐含前提配置时应一并确认。完整 YAML 配置示例在services.yaml的某个服务项下按如下方式挂载 Widget完整配置骨架可参考 src/skeleton/services.yamlwidget: type: truenas url: http://truenas.host.or.ip version: 2 # optional, defaults to 1 username: user # not required if using api key password: pass # not required if using api key key: yourtruenasapikey # not required if using username / password enablePools: true # optional, defaults to false nasType: scale # defaults to scale, must be set to core if using enablePools with TrueNAS Core参数速查表参数类型默认值是否必填说明typestring-是固定为truenasurlstring-是TrueNAS 主机地址如http://truenas.host.or.ipversionnumber1否1走 REST API2走 WebSocket APIusernamestring-二选一用户名与password配合未填key时使用passwordstring-二选一密码keystring-二选一TrueNAS API Key优先于用户名/密码enablePoolsbooleanfalse否是否展示存储池列表与容量nasTypestringscale视情况scale或coreTrueNAS Core 开启enablePools时必填core这些布尔/字符串参数在配置解析阶段会被规范化enablePools通过JSON.parse转为布尔值nasType原样透传见 src/utils/config/service-helpers.js确保后续组件与代理层拿到的是类型正确的值。最小可用配置默认版只关心负载、运行时长和告警数量时用默认 version 1 用户名/密码即可widget: type: truenas url: http://192.168.1.10 username: admin password: yourpassword存储池监控配置TrueNAS Scalewidget: type: truenas url: http://192.168.1.10 version: 2 key: 1-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX enablePools: true nasType: scale展示内容与 UI 细节Widget 的主容器固定渲染三个信息块见 src/widgets/truenas/component.jsxtruenas.load系统负载显示loadavg[0]1 分钟平均负载truenas.uptime以common.duration格式化uptime_secondstruenas.alerts显示未处理pending告警数量。这三个标签的中文文案可在 public/locales/zh-Hans/common.json 中找到系统负载/Uptime/Alerts其余语言同理。开启enablePools后每个存储池会渲染为独立的进度条组件见 src/widgets/truenas/pool.jsx池名左侧有一个状态色块healthy为绿色bg-green-500异常为黄色bg-yellow-500右侧显示已用 / 总量二进制单位保留 1 位小数以及括号内的使用百分比使用百分比由allocated / (free allocated)计算并取整。数据组装逻辑在 src/widgets/truenas/component.jsxpools 与 dataset 都非空数组时才渲染池列表每个池通过dataset.name pool.name匹配顶层数据集取used.parsed与available.parsed作为容量数据最后按池名排序输出。也就是说enablePools展示的是池的健康状态 顶层数据集容量两者缺一不可。源码级原理v2 WebSocket 代理调用链当配置version: 2时数据获取由专用的truenasProxyHandler完成入口 src/widgets/truenas/proxy.js整个调用链如下参数校验从请求中取出group、service、endpoint、index通过getServiceWidget读取该服务的 Widget 配置版本分流version 2直接交给 REST 版credentialedProxyHandler映射查找按endpoint在mappings中找到对应的wsMethod找不到则返回 500建立连接将wsAPI模板格式化为目标地址根据协议https或是否存在key决定使用wss:或ws:认证依次尝试auth.login_with_api_key、auth.login发起 RPC 调用以 JSON-RPC 2.0 格式发送{ jsonrpc: 2.0, id, method, params }见 src/widgets/truenas/proxy.js按id匹配响应出错时抛出服务端 error 信息超时与健壮性每次等待响应都有 10 秒超时见 src/widgets/truenas/proxy.js连接异常关闭或报错都会以 Error 形式 reject数据校验与映射返回数据先经validateWidgetData校验再应用mappings中定义的map函数例如 alerts 只统计dismissed false的数量pools 精简为id/name/healthy最终以 JSON 形式响应前端。这套流程在 src/widgets/truenas/proxy.test.js 中有对应测试模拟配置了version: 2与key的 Widget验证最终返回 JSON 结果且状态码为 200。UI 侧的加载占位、错误处理与池渲染行为则由 src/widgets/truenas/component.test.jsx 覆盖无数据时显示 3 个占位块enablePools且数据完整时正确渲染池名、健康状态与容量数值。常见问题与排查建议Alerts 计数为 0 但 TrueNAS 上明明有告警计数逻辑只统计dismissed false的条目见 src/widgets/truenas/widget.js已被手动忽略dismissed的告警不会计入配置了 API Key 但 v2 连不上如前文所述v2 API Key 会强制使用wss:请确认 TrueNAS 地址可提供 HTTPS/WSS 服务或改用http:// 用户名/密码组合enablePools不显示池列表pools 与 dataset 两个端点都必须返回非空数组才会渲染见 src/widgets/truenas/component.jsx可检查 TrueNAS 侧数据集查询权限TrueNAS Core 使用enablePools无数据文档明确要求为nasType显式传入core默认值是scale这是 Scale 与 Core 在数据集接口返回结构上的差异所致始终走 RESTv1未写version时默认值为1如需 WebSocket 通道务必显式设置version: 2。小结TrueNAS Widget 是 Homepage 中接入 NAS 监控最典型的示例之一它以一份简洁的 YAML 配置同时封装了 REST 与 WebSocket 两种协议、API Key 与账号密码两套认证并提供了可选的存储池容量可视化。理解 docs/widgets/services/truenas.md 中的版本对照表、认证字段与enablePools/nasType语义再对照 src/widgets/truenas 下的实现与测试你不仅能顺利接入自己的 TrueNAS也能举一反三地掌握 Homepage 服务型 Widget 的通用配置与扩展模式。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考