unraid

Unraid API Skill 是一款专为 Unraid NAS 系统设计的监控工具，通过 GraphQL 接口提供对服务器的全方位只读访问能力。该技能包含 27 个 API 端点，覆盖系统状态、硬件监控、存储管理、虚拟化环境等核心运维场景，适合家庭服务器管理员和小型企业运维人员使用。

核心用法方面，用户通过配置 UNRAID_URL 和 UNRAID_API_KEY 环境变量即可建立连接，利用提供的 Bash 辅助脚本执行 GraphQL 查询。工具支持多种输出格式（JSON、格式化、原始数据），并内置了磁盘健康检查、系统日志读取、阵列状态监控等现成示例脚本。对于多服务器环境，dashboard.sh 脚本可实现批量状态汇总，大幅提升多节点管理效率。

显著优点体现在其纯粹的只读设计上，从根本上杜绝了误操作导致系统损坏的风险。相比传统 SSH 监控方式，GraphQL 接口允许精确请求所需字段，减少带宽占用并提升查询效率。技能提供了完整的字段内省支持，用户可动态发现可用数据点。同时，环境变量管理凭证的方式避免了敏感信息硬编码，符合安全最佳实践。无需在服务器端安装代理，仅需 API 密钥即可工作，部署极为轻量。

潜在局限包括来源等级为 T3 社区项目，非 Unraid 官方维护，长期支持存在不确定性。功能上仅限于 Unraid 7.2 及以上版本，且无法获取 Docker 容器输出日志（需通过 SSH 使用 docker logs 命令）。此外，工具依赖系统预装的 curl 和 jq 命令，在精简环境中可能需要手动安装依赖。对于需要修改系统配置的写操作（如启停容器、修改阵列状态）则无能为力。

适用人群主要包括 Unraid NAS 用户、家庭实验室（Homelab）爱好者、以及需要监控私有云基础设施的运维人员。对于需要定期检查磁盘健康、监控阵列校验状态、或集中管理多台 Unraid 服务器的场景尤为适用。也适合作为自动化监控体系的数据采集端，与 Prometheus、Grafana 等工具配合使用。

使用风险方面，脚本默认使用 curl 的 -k 参数接受自签名证书，在内网环境虽便利但存在潜在中间人攻击风险，建议在生产环境中配置可信证书。频繁的 API 轮询（低于 5 秒间隔）可能对服务器造成不必要的负载。此外，作为社区项目，建议在使用前审查代码并在隔离环境中测试，确认符合自身安全策略后再部署到生产环境。

Unraid API Skill 综合评估

核心用法

Unraid API Skill 是一款专为 Unraid NAS 系统设计的监控工具，通过 GraphQL API 实现全功能只读查询。该 Skill 覆盖 27 个 API 端点，支持以下核心场景：

系统监控：实时查询 CPU/内存使用率（metrics 资源）、在线状态检测、硬件规格信息（info 资源）。存储管理：阵列状态检查、奇偶校验进度追踪、磁盘温度与健康度监控、SMB/NFS 共享列表获取。虚拟化与容器：Docker 容器运行状态枚举、KVM 虚拟机清单及资源配置查看。日志审计：系统日志（syslog、docker、system 等）读取与行数过滤。多服务器仪表板：通过 dashboard.sh 实现多台 Unraid 服务器的统一监控报告生成。

使用方法上，用户需配置 UNRAID_URL 和 UNRAID_API_KEY 环境变量（支持 Viewer 角色最小权限密钥），随后可通过 ./scripts/unraid-query.sh -q "{ QUERY }" 执行任意 GraphQL 查询，或调用预设脚本完成特定任务。

显著优点

1. 功能覆盖全面：从硬件层（磁盘温度、SMART 数据）到应用层（容器、VM），再到日志审计，形成完整监控闭环。
2. 只读安全设计：所有 27 个端点均为读取操作，无写权限风险，即使 API 密钥泄露也无法修改服务器配置。
3. 零第三方依赖：仅依赖系统预装的 curl 和 jq，彻底规避 npm/pip 供应链攻击风险。
4. 多服务器支持：原生支持通过 dashboard.sh 生成跨服务器的 Markdown 格式库存报告，适合运维团队使用。
5. 来源可信：代码托管于 GitHub 组织账号 clawdbot/skills，经认证属 T2 级可信来源。

潜在缺点与局限性

1. GraphQL 学习成本：不同于传统 REST API，用户需理解 GraphQL 的字段嵌套语法，入门门槛略高。
2. 容器日志不可见：API 本身不提供 Docker 容器 stdout/stderr 日志，需通过 SSH 执行 docker logs 补充。
3. SSL 验证放宽：脚本默认使用 curl -k 跳过证书验证，在公网访问场景存在中间人攻击风险（本地内网使用自签名证书属合理权衡）。
4. 无持久化告警：纯查询工具，不具备阈值告警、邮件/Webhook 通知等主动监控能力。
5. 输入验证薄弱：GraphQL 查询字符串直接拼接进 JSON 载荷，虽风险极低，但缺乏引号转义等防护。

适合人群

• Unraid 家庭用户：需要快速检查服务器健康状态、磁盘温度、备份进度，但不想登录 Web UI。
• 小型运维团队：管理 2-10 台 Unraid 服务器，需要定期生成标准化状态报告。
• 自动化集成开发者：将 Unraid 监控数据接入现有 Prometheus/Grafana 或自建 Dashboard。
• 安全审计人员：需要对 Unraid 服务器进行配置基线核查与日志取证。

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 中间人攻击 | `curl -k` 跳过 SSL 验证 | 内网使用或配置受信任证书；避免公网明文暴露 |

| 密钥泄露 | API 密钥存储于环境变量 | 使用 Viewer 角色最小权限密钥；定期轮换 |

| 查询注入 | GraphQL 字符串拼接 | 仅使用 Skill 提供的受控查询模板 |

| 配置覆盖 | `dashboard.sh` 写入上下文文件 | 确认写入路径 `$HOME/.clawdbot/` 和 `$HOME/clawd/memory/` 符合预期 |

安全等级结论：该 Skill 经 CLS-Certify v2.1.0 扫描获 A 级评分（82/100），功能与声明完全一致，无恶意代码、无数据外泄、无提权行为，适用于生产环境监控场景。