qui的API高级文档：高级端点和参数详解

【免费下载链接】qui Modern alternative webUI for qBittorrent, with multi-instance support. Written in Go/React. 项目地址: https://gitcode.com/GitHub_Trending/qui3/qui

qui作为一款现代化的qBittorrent WebUI替代方案，不仅提供了直观的用户界面，还通过强大的API系统支持高级自动化与集成。本文将深入解析qui的核心API端点、请求参数及最佳实践，帮助开发者快速构建自定义功能与第三方集成。

核心API架构概览

qui的API系统基于RESTful设计原则，采用Go语言开发的后端服务与React前端分离架构。所有API端点均位于internal/api/handlers/目录下，通过模块化处理不同功能域的请求。

图1：qui的高级仪表盘界面，展示了API驱动的实时数据交互

认证与授权端点

1. 用户认证流程

• 登录请求
  POST /api/auth/login
  请求体：

  {
    "username": "string",
    "password": "string"
  }
  

  响应包含JWT令牌，需在后续请求的Authorization: Bearer <token>头中使用。

• API密钥管理
  通过POST /api/auth/api-keys创建长期访问令牌，支持细粒度权限控制：

  // 源码位置：internal/api/handlers/auth.go
  type CreateAPIKeyRequest struct {
      Name        string   `json:"name" validate:"required"`
      Permissions []string `json:"permissions" validate:"required"`
  }
  

种子管理高级操作

1. 批量种子添加

POST /api/torrents/add支持多源批量添加，通过indexer_id参数关联Jackett索引器：

// 测试示例：internal/api/handlers/torrents_add_test.go
func TestAddTorrentHandler_SuccessfulIndexerDownload_Returns201(t *testing.T) {
    // 验证通过索引器ID下载种子的完整流程
}

2. 种子状态过滤

GET /api/torrents支持复杂查询参数：

• status: 支持多个状态筛选（如downloading,seeding）
• category: 按分类过滤
• sort: 支持size,ratio,added_on等排序字段

高级配置端点

1. 跨种配置管理

通过PATCH /api/crossseed/settings调整高级跨种参数：

// 源码位置：internal/api/handlers/crossseed.go
type searchSettingsPatchRequest struct {
    MaxResults       *int  `json:"max_results"`
    IntervalMinutes  *int  `json:"interval_minutes"`
    SkipSameCategory *bool `json:"skip_same_category"`
}

2. 日志排除规则

PUT /api/log-exclusions允许自定义日志过滤规则：

// 源码位置：internal/api/handlers/log_exclusions.go
func (h *LogExclusionsHandler) Update(w http.ResponseWriter, r *http.Request) {
    // 处理日志排除规则的更新逻辑
}

许可证与主题管理

1. 许可证激活

POST /api/licenses/activate用于商业主题授权：

// 源码位置：internal/api/handlers/licenses.go
func (h *LicenseHandler) ActivateLicense(w http.ResponseWriter, r *http.Request) {
    // 许可证验证与激活逻辑
}

2. 主题切换

GET /api/licenses/themes返回已授权主题列表，前端可通过POST /api/settings/theme应用主题。

API最佳实践

1. 请求限流：所有API端点默认限制每分钟60次请求，通过X-RateLimit响应头查看限额状态
2. 错误处理：使用标准HTTP状态码，详细错误信息在error响应字段中提供
3. 版本控制：API路径包含版本前缀（如/api/v1/），确保兼容性
4. 批量操作：优先使用批量端点（如/api/torrents/delete）减少请求次数

接口测试与调试

推荐使用项目内置的Swagger文档进行API调试：

• 访问路径：/web/swagger/index.html
• 源码位置：internal/web/swagger/

通过本文档介绍的API端点与参数，开发者可以实现从简单状态查询到复杂自动化任务的各类需求。完整的端点列表与参数定义可查阅项目internal/api/handlers/目录下的源代码文件。

【免费下载链接】qui Modern alternative webUI for qBittorrent, with multi-instance support. Written in Go/React. 项目地址: https://gitcode.com/GitHub_Trending/qui3/qui