跳到主要内容

使用 Unraid API

Quick 开始

Unraid API 提供了一个强大的 GraphQL 接口，用于管理您的服务器。本指南涵盖认证、常见查询和最佳实践。

Unraid API 提供了一个 GraphQL 接口，允许您与您的 Unraid 服务器进行交互。本指南将帮助您开始探索和使用该 API。

🎮 启用 GraphQL 沙箱​

Web GUI方法（推荐）​

Preferred 方法

使用Web GUI是启用GraphQL沙盒最简单的方式。

  1. 导航到 设置 → 管理访问 → 开发者选项

  2. 启用 GraphQL 沙箱 切换

  3. 通过导航到以下位置访问 GraphQL playground：

    http://YOUR_SERVER_IP/graphql

CLI 方法​

或者，您可以使用 CLI 启用开发者模式：

unraid-api developer --sandbox true

或使用交互模式：

unraid-api developer

🔑 身份验证​

Required 大多数操作需要

大多数查询和变更需要认证。请务必在请求中包含适当的凭据。

您可以使用以下方式进行身份验证：

  1. API 密钥 - 对编程访问来说
  2. Cookies - 当登录到 WebGUI 时自动
  3. SSO/OIDC - 配置为与外部提供商一起使用时

API 密钥管理​

导航到 Unraid web 界面的 设置 → 管理访问 → API 密钥 来：

  • 查看现有 API 密钥
  • 创建新的 API 密钥
  • 管理权限和角色
  • 撤销或重新生成密钥

使用 API 密钥​

生成的 API 密钥应作为标头包含在您的 GraphQL 请求中：

{
    "x-api-key": "YOUR_API_KEY"
}

📊 可用模式​

API 提供对 Unraid 服务器各个方面的访问：

系统信息​

  • 查询系统详细信息，包括 CPU、内存和操作系统信息
  • 监控系统状态和健康
  • 访问主板和硬件信息

阵列管理​

  • 查询阵列状态和配置
  • 管理阵列操作（启动/停止）
  • 监控磁盘状态和健康
  • 执行校验检查

Docker 管理​

  • 列出和管理 Docker 容器
  • 监控容器状态
  • 管理 Docker 网络

远程访问​

  • 配置和管理远程访问设置
  • 处理 SSO 配置
  • 管理允许的来源

💻 示例查询​

检查系统状态​

query {
    info {
        os {
            platform
            distro
            release
            uptime
        }
        cpu {
            manufacturer
            brand
            cores
            threads
        }
    }
}

监控阵列状态​

query {
    array {
        state
        capacity {
            disks {
                free
                used
                total
            }
        }
        disks {
            name
            size
            status
            temp
        }
    }
}

列出 Docker 容器​

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

🏗️ 模式类型​

API 包括几个核心类型：

基本类型​

  • Node：适用于具有唯一 ID 的对象的接口 - 请参阅对象识别
  • JSON：用于复杂的 JSON 数据
  • DateTime：用于时间戳值
  • Long：用于 64 位整数

资源类型​

  • Array: 阵列和磁盘管理
  • Docker: 容器和网络管理
  • Info: 系统信息
  • Config: 服务器配置
  • Connect: 远程访问设置

基于角色的访问​

可用角色：

  • admin：完全访问
  • connect：远程访问功能
  • guest：有限读取访问

✨ 最佳实践​

Pro 提示
  1. 使用 Apollo Sandbox 探索模式和测试查询
  2. 从小查询开始，逐渐按需添加字段
  3. 监控您的查询复杂度以保持性能
  4. 对于您的 API 密钥，使用适当的角色和权限
  5. 保持您的 API 密钥安全并定期更换

⏱️ 速率限制​

Rate 限制

API 实施了速率限制以防止滥用。确保您的应用程序适当地处理速率限制响应。

🚨错误处理​

API 以以下格式返回标准的 GraphQL 错误：

{
  "errors": [
    {
      "message": "Error description",
      "locations": [...],
      "path": [...]
    }
  ]
}

📚 额外资源​

Learn 更多
  • 使用 Apollo Sandbox 的模式浏览器浏览所有可用类型和字段
  • 查看 Apollo Sandbox 中的文档选项卡以获取详细的字段描述
  • 使用 unraid-api status 监控 API 的健康状况
  • 使用 unraid-api report 生成报告以进行故障排除

有关特定命令和配置选项的更多信息，请参阅 CLI 文档 或运行 unraid-api --help。