跳到主要内容

使用 Unraid API

Unraid API 提供了一个 GraphQL 接口，允许您与您的 Unraid 服务器进行交互。本指南涵盖身份验证、常见查询和使用模式。

启用 GraphQL 沙盒​

WebGUI 方法（推荐）​

📖 实时文档

查看完整的 API 架构和文档：

在 Apollo GraphQL Studio 中查看实时文档 →

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

WebGUI 方法（推荐）​

使用 WebGUI 是启用 GraphQL 沙盒最简单的方法：

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

  2. 启用 GraphQL 沙盒 开关

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

    http://YOUR_SERVER_IP/graphql

CLI 方法​

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

unraid-api developer --sandbox true

或使用交互模式：

unraid-api developer

身份验证​

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

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

管理 API 密钥​

导航到 Unraid WebGUI 中的 设置 → 管理访问 → API 密钥：

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

API 密钥管理​

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

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

可用架构​

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

  • 系统信息：查询系统详情，包括 CPU、内存和 OS 信息；监控系统状态和健康状况；访问主板和硬件信息。
  • Array 管理：查询 array 状态和配置；管理 array 操作（启动/停止）；监控磁盘状态和健康状况；执行 parity checks。有关阵列操作的更多信息，请参阅 阵列概览。
  • 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（array 和磁盘管理）、Docker（容器和网络管理）、Info（系统信息）、Config（服务器配置）和 Connect（远程访问设置）。可用角色有 admin（完全访问）、connect（远程访问功能）和 guest（受限读取访问）。

检查系统状态​

Pro 提示
  1. 使用 Apollo GraphQL Studio 查看并浏览完整的 API 架构和文档
  2. 从小查询开始，逐渐按需添加字段
  3. 监控您的查询复杂度以保持性能
  4. 对于您的 API 密钥，使用适当的角色和权限
  5. 保持您的 API 密钥安全并定期更换

列出 Docker 容器​

Rate 限制

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

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

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

资源类型​

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

有关具体命令和配置选项的更多信息，请参阅 CLI 文档 或运行 unraid-api --help。如果遇到问题，请访问 Unraid 论坛 获取社区支持。