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              # Complete multi-server dashboard
./examples/disk-health.sh           # Disk temperatures & health
./examples/read-logs.sh syslog 20   # Read system logs

核心概念

GraphQL API 结构

Unraid 7.2+ 使用 GraphQL（非 REST）。主要区别：

• 单一端点： /graphql用于所有查询
• 精确请求您需要的内容：在查询中指定字段
• 强类型：使用内省来发现字段
• 无容器日志：Docker 容器输出日志不可访问

用于统计的两个资源

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

始终使用指标进行监控，信息用于规格说明。

常见任务

系统监控

检查服务器是否在线：

./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辅助工具支持：

# Basic usage
./scripts/unraid-query.sh -u URL -k API_KEY -q "QUERY"

# Use environment variables
export UNRAID_URL="https://unraid.local/graphql"
export UNRAID_API_KEY="your-key"
./scripts/unraid-query.sh -q "{ online }"

# Format options
-f json    # Raw JSON (default)
-f pretty  # Pretty-printed JSON
-f raw     # Just the data (no wrapper)

其他资源

参考文件

如需详细文档，请查阅：

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

辅助脚本

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

快速命令参考

# System status
./scripts/unraid-query.sh -q "{ online metrics { cpu { percentTotal } } }"

# Disk health
./examples/disk-health.sh

# Array status
./scripts/unraid-query.sh -q "{ array { state } }"

# Read logs
./examples/read-logs.sh syslog 20

# Complete dashboard
./scripts/dashboard.sh

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

# List containers
./scripts/unraid-query.sh -q "{ docker { containers { names state } } }"