名称： unraid
版本： 1.0.1
描述： "通过 GraphQL API 查询和监控 Unraid 服务器。当用户提及 '检查 Unraid'、'监控 Unraid'、'Unraid API'、'获取 Unraid 状态'、'检查磁盘温度'、'读取 Unraid 日志'、'列出 Unraid 共享'、'Unraid 阵列状态'、'Unraid 容器'、'Unraid 虚拟机'，或涉及 Unraid 系统监控、磁盘健康、奇偶校验、服务器状态时使用此技能。"

Unraid API 技能

通过 GraphQL API 查询和监控 Unraid 服务器。可访问全部 27 个只读端点，涵盖系统监控、磁盘健康、日志、容器、虚拟机等功能。

快速开始

设置您的 Unraid 服务器凭据：

export UNRAID_URL="https://your-unraid-server/graphql"
export UNRAID_API_KEY="your-api-key"

获取 API 密钥： 设置 → 管理访问 → API 密钥 → 创建（选择 "查看者" 角色）

使用辅助脚本执行任意查询：

./scripts/unraid-query.sh -q "{ online }"

或运行示例脚本：

./scripts/dashboard.sh              # 完整的多服务器仪表盘
./examples/disk-health.sh           # 磁盘温度与健康状态
./examples/read-logs.sh syslog 20   # 读取系统日志

核心概念

GraphQL API 结构

Unraid 7.2+ 使用 GraphQL（非 REST）。主要区别：
- 单一端点： 所有查询均通过 /graphql 进行
- 按需请求： 在查询中指定所需字段
- 强类型： 使用自省功能发现可用字段
- 无容器日志： 无法通过 API 访问 Docker 容器的输出日志

两种统计资源

• info - 静态硬件规格（CPU 型号、核心数、操作系统版本）
• metrics - 实时使用情况（CPU 百分比、内存百分比、当前负载）

监控时始终使用 metrics，查询规格时使用 info。

常见任务

系统监控

检查服务器是否在线：

./scripts/unraid-query.sh -q "{ online }"

获取 CPU 和内存使用率：

./scripts/unraid-query.sh -q "{ metrics { cpu { percentTotal } memory { used total percentTotal } } }"

完整仪表盘：

./scripts/dashboard.sh

磁盘管理

检查磁盘健康状态与温度：

./examples/disk-health.sh

获取阵列状态：

./scripts/unraid-query.sh -q "{ array { state parityCheckStatus { status progress errors } } }"

列出所有物理磁盘（包括缓存/USB）：

./scripts/unraid-query.sh -q "{ disks { name } }"

存储共享

列出网络共享：

./scripts/unraid-query.sh -q "{ shares { name comment } }"

日志

列出可用日志：

./scripts/unraid-query.sh -q "{ logFiles { name size modifiedAt } }"

读取日志内容：

./examples/read-logs.sh syslog 20

容器与虚拟机

列出 Docker 容器：

./scripts/unraid-query.sh -q "{ docker { containers { names image state status } } }"

列出虚拟机：

./scripts/unraid-query.sh -q "{ vms { name state cpus memory } } }"

注意： 无法通过 API 访问容器输出日志。请通过 SSH 使用 docker logs 命令。

通知

获取通知计数：

./scripts/unraid-query.sh -q "{ notifications { overview { unread { info warning alert total } } } }"

辅助脚本使用说明

scripts/unraid-query.sh 辅助脚本支持以下功能：

# 基本用法
./scripts/unraid-query.sh -u URL -k API_KEY -q "QUERY"

# 使用环境变量
export UNRAID_URL="https://unraid.local/graphql"
export UNRAID_API_KEY="your-key"
./scripts/unraid-query.sh -q "{ online }"

# 格式选项
-f json    # 原始 JSON（默认）
-f pretty  # 格式化 JSON
-f raw     # 仅数据（无包装）

附加资源

参考文件

详细文档请查阅：
- references/endpoints.md - 全部 27 个 API 端点的完整列表
- references/troubleshooting.md - 常见错误与解决方案
- references/api-reference.md - 详细的字段文档

辅助脚本

• scripts/unraid-query.sh - 主要的 GraphQL 查询工具
• scripts/dashboard.sh - 自动化的多服务器清单报告工具

快速命令参考

# 系统状态
./scripts/unraid-query.sh -q "{ online metrics { cpu { percentTotal } } }"

# 磁盘健康
./examples/disk-health.sh

# 阵列状态
./scripts/unraid-query.sh -q "{ array { state } }"

# 读取日志
./examples/read-logs.sh syslog 20

# 完整仪表盘
./scripts/dashboard.sh

# 列出共享
./scripts/unraid-query.sh -q "{ shares { name } }"

# 列出容器
./scripts/unraid-query.sh -q "{ docker { containers { names state } } }"