Homepage 集成 Unraid资源监控 Widget 配置与源码级原理解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageUnraid 是自建 NAS 领域常用的操作系统Homepage 为其提供了开箱即用的监控 Widget可实时展示 CPU、内存、阵列Array与缓存池Pool的运行状态。本文将基于当前仓库中 Unraid Widget 官方文档 为主线结合src/widgets/unraid/下的代理、组件与测试实现完整讲解前置条件、配置方法、全部可用字段以及数据从前端到 GraphQL 接口的完整链路帮助你在一份services.yaml中快速落地 Unraid 监控面板。一、前置条件最低版本要求与 API Key在开始配置之前需要确认你的 Unraid 服务器满足以下两个硬性条件Unraid 版本要求Unraid 7.2 及以上版本或已安装不低于2025.08.19.1850版本的Unraid Connect 插件。这是因为本 Widget 依赖新版 Unraid 提供的 GraphQL API旧版本不提供对应接口。API Key 权限要求需要一枚具有ADMIN角色的 API Key。普通角色的 Key 无法读取阵列状态、资源指标等敏感数据会导致请求被拒绝。API Key 的创建与管理可在 Unraid 官方文档的 Managing API Keys 章节中完成。小贴士如果页面加载后 Widget 一直处于无数据状态或直接报错请优先检查 API Key 的角色是否为 ADMIN以及 Unraid 版本是否满足上述门槛。二、快速配置一分钟接入 Unraid Widget在 Homepage 的services.yaml对应骨架模板见 src/skeleton/services.yaml中为 Unraid 添加一个widget块即可。最小配置如下widget: type: unraid url: https://unraid.host.or.ip key: api-key其中参数必填说明type是固定为unraid用于匹配 Widget 组件与代理处理器url是Unraid 服务器的地址主机名或 IP需带协议头。代理会在此地址后拼接/graphql端点key是具有 ADMIN 角色的 API Key通过X-API-Key请求头发送监控缓存池Pool如果希望同时监控 Unraid 的缓存池则需要额外指定池名称。Widget 支持最多 4 个池参数为pool1至pool4widget: type: unraid url: https://unraid.host.or.ip key: api-key pool1: pool1name # required only if using pool1 fields pool2: pool2name # required only if using pool2 fields pool3: pool3name # required only if using pool3 fields pool4: pool4name # required only if using pool4 fields需要注意的是只有当你打算使用对应poolN*字段时才需要填写对应的池名称。池名称必须与 Unraid 服务器中实际创建的缓存池名称完全一致否则对应的poolN*字段将显示为-详见后文源码分析。这一配置参数的解析逻辑位于 src/utils/config/service-helpers.js在服务配置清洗阶段会把pool1~pool4逐个写入 Widget 配置对象。三、可用字段详解字段名与数据来源原文档声明 Widget 的**允许字段Allowed fields**如下[cpu,memoryPercent,memoryAvailable,memoryUsed,notifications,arrayFree,arrayUsedSpace,arrayUsedPercent,status,pool1UsedSpace,pool1FreeSpace,pool1UsedPercent,pool2UsedSpace,pool2FreeSpace,pool2UsedPercent,pool3UsedSpace,pool3FreeSpace,pool3UsedPercent,pool4UsedSpace,pool4FreeSpace,pool4UsedPercent]这些字段可以在widget块的fields数组中按需选用。结合 src/widgets/unraid/proxy.js 的响应处理逻辑可以建立完整的字段名 → 含义 → 底层数据映射表字段含义底层数据来源GraphQL 响应字段status阵列状态array.statecpuCPU 使用率%metrics.cpu.percentTotalmemoryPercent内存使用率%metrics.memory.percentTotalmemoryUsed已用内存字节metrics.memory.activememoryAvailable可用内存字节metrics.memory.availablenotifications未读通知数notifications.overview.unread.totalarrayUsedSpace阵列已用容量字节array.capacity.kilobytes.used × 1000arrayFree阵列可用容量字节array.capacity.kilobytes.free × 1000arrayUsedPercent阵列已用百分比%used / total × 100poolNUsedSpace第 N 个缓存池已用容量caches[poolN].fsUsed × 1000poolNFreeSpace第 N 个缓存池可用容量caches[poolN].fsFree × 1000poolNUsedPercent第 N 个缓存池已用百分比fsUsed / fsSize × 100从源码可以看出几个值得注意的细节单位换算容量类数据阵列与缓存池来自 GraphQL 的kilobytes/fsSize等字段代理层统一乘以1000换算为字节后下发前端再按common.bytes本地化格式显示。缓存池过滤caches集合中只有fsType非空的条目才会被写入响应proxy.js即仅保留真实挂载的文件系统池。字段与数据并非同名例如字段arrayUsedSpace对应的内部数据键是arrayUsed字段memoryPercent对应memoryUsedPercent。这是组件层Block的field/label与数据键解耦设计配置时请以本文表格中的字段名为准。四、底层原理GraphQL 代理与数据加工链路Unraid Widget 并不直接从前端访问 Unraid而是由 Homepage 服务端代理统一转发。核心实现在 src/widgets/unraid/proxy.jswidget.js将其注册为proxyHandler见 src/widgets/unraid/widget.js。1. 请求构造代理处理器首先通过getServiceWidget(group, service, index)从用户配置中取出当前服务的widget配置url、key 等然后将请求 URL 拼接为{widget.url}/graphql使用POST方法、Content-Type: application/json通过X-API-Key请求头携带 API Key请求体为一段写死的 GraphQL 查询proxy.js一次性获取阵列状态、容量、缓存池、内存/CPU 指标与未读通知{ array { state capacity { kilobytes { free total used } } caches { name fsType fsSize fsFree fsUsed } } metrics { memory { active available percentTotal } cpu { percentTotal } } notifications { overview { unread { total } } } }这正是原文档要求 Unraid 7.2 / 新版 Unraid Connect 的原因——该 GraphQL schema 只在较新版本中提供。2. 响应扁平化拿到响应后processUnraidResponse把嵌套的 GraphQL 结构拍平为 Widget 前端易于消费的扁平对象memoryUsedPercent、cpuPercent、arrayState、caches等并做了两处防御对arrayUsedPercent的计算发生在try/catch内且大量使用可选链?.任一字段缺失时返回null而不是抛错若响应无法解析为 JSON返回{ error: error.message }随后代理以 HTTP 500 响应proxy.test.js 对该路径有专门测试。3. 错误处理缺少group/service或找不到对应 Widget 配置时返回 HTTP 400Unraid 返回非 200 状态码时代理会记录错误日志并原样透传状态码与错误信息HTTP 204 / 304 直接结束响应不解析内容。整个链路可以通过测试用例验证httpProxy被调用且 URL 精确为{url}/graphql响应体被正确扁平化见 proxy.test.js。五、前端渲染字段过滤、默认值与加载占位1. 默认字段与数量上限前端组件实现位于 src/widgets/unraid/component.jsx其中定义了两个关键常量const UNRAID_DEFAULT_FIELDS [status, cpu, memoryPercent, notifications]; const MAX_ALLOWED_FIELDS 4;如果配置中未指定fields组件会回退到上述 4 个默认字段状态、CPU、内存使用率、未读通知如果fields数量超过 4 个会被截断为前 4 个fields.slice(0, MAX_ALLOWED_FIELDS)。也就是说即使你在fields中填入了全部 21 个字段同一时刻面板上也只会展示前 4 个。这一点在 component.test.jsx 中有明确验证默认情况下容器只渲染 4 个.service-block且memoryAvailable块不会出现。2. 字段如何决定可见性数据到达后组件渲染出全部候选Block由 src/components/services/widget/container.jsx 依据fields数组做可见性过滤每个字段若不含.会被自动补全为unraid.{field}前缀再与Block的field/label属性匹配。这意味着字段名区分大小写必须严格使用上表所列名称容器级过滤对所有类型 Widget 生效属于 Homepage 的通用机制。3. 加载占位与数值高亮数据未返回时组件渲染加载占位块同样只显示被选中的字段见 component.jsx数据就绪后各Block通过highlightValue接入 Homepage 的高亮系统由 utils/highlights.js 的buildHighlightConfig驱动见 container.jsx可在settings.yaml中针对该 Widget 配置阈值高亮告警阵列状态文案通过国际化 key 渲染arrayState的值如STARTED、STOPPED会被翻译成可读文本。4. 状态文本国际化status字段展示的阵列状态取值与翻译定义在 public/locales/en/common.json 中覆盖了STARTED、STOPPED、NEW_ARRAY、RECON_DISK磁盘重建中、DISABLE_DISK磁盘被禁用、SWAP_DSBL、INVALID_EXPANSION、PARITY_NOT_BIGGEST、TOO_MANY_MISSING_DISKS、NEW_DISK_TOO_SMALL、NO_DATA_DISKS等常见阵列异常状态可帮助你在首页一眼识别阵列健康问题。六、配置与验证建议版本先行升级到 Unraid 7.2 或安装新版 Unraid Connect 插件并创建 ADMIN 角色 API Key。最小化起步先用默认 4 字段跑通确认数据出现后再按需添加arrayUsedSpace、pool1*等字段注意总数不超过 4 个。池名称对齐使用poolN字段前先核对 Unraid 界面中的实际池名名称不匹配时对应块显示-而不是报错容易误判。高亮告警结合blockHighlights为unraid类型配置阈值如 CPU 80% 高亮实现首页资源异常可视化。七、小结Homepage 的 Unraid Widget 是一个典型的配置驱动 服务端代理实现用户在services.yaml中声明type: unraid、地址、API Key 与目标字段代理层负责拼接 GraphQL 查询、携带鉴权头、扁平化响应前端组件则依据fields做精准渲染并支持状态翻译与阈值高亮。掌握字段映射与 4 字段上限这两个关键约束即可在首页稳定、高效地呈现 Unraid 服务器的运行状态。如需了解 Widget 的通用开发规范可参考 docs/widgets/authoring/getting-started.md 与 docs/widgets/authoring/api.md。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考