企业官网建设流程全解析

qBittorrent WebAPI 变更日志详解：从 2.11 到 2.16 的 API 演进、破坏性变更与源码级实现剖析

【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent

qBittorrent 的 WebAPI 是集成第三方面板、脚本与自动化工具（如下载器同步器、NAS 脚本）的核心接口。本文以仓库根目录下的 WebAPI_Changelog.md 为骨架，完整梳理 2.11.x 至 2.16.0 各版本新增、修改与移除的端点、参数和字段，并结合 src/webui/ 目录中的控制器源码印证每一项变更的真实实现，帮助你在升级版本前准确评估兼容性影响，并掌握每个新端点的调用方式与返回结构。

变更日志的阅读方式与总体演进脉络

WebAPI_Changelog.md 按版本倒序组织，从最新的 2.16.0 一直回溯到 2.11.6，每条变更对应一个上游 PR 编号。纵观全部条目，可以归纳出五条主线：

1. 安全与认证强化：2.15.0 引入 Basic auth、2.14.1 引入 API Key 轮换与删除端点、2.16.0 将部分危险端点限定为仅接受 POST；
2. 元数据能力补全：2.11.9 起新增fetchMetadata/parseMetadata/saveMetadata三件套，2.16.0 又为这些端点补充了文件priority字段；
3. 同步数据扩充：sync/maindata与sync/torrentPeers持续增加指标与字段（request_latency、queued_tracker_announces、contribution、host_name、i2p_dest等）；
4. 速度限制管理独立化：2.16.0 新增transfer/getSpeedLimits与transfer/setSpeedLimits，一次性读写全局与备选限速值；
5. 破坏性变更：包括移除export_dir、skip_checking、mail_notification_ssl_enabled、use_subcategories等旧选项，以及torrents/parseMetadata返回结构由对象改为数组。

阅读本文时，建议优先定位你当前使用的 qBittorrent 版本所在章节，核对你依赖的端点是否存在参数或返回值的破坏性修改。

2.16.0：POST 化、种子模式与 .torrent 文件备份选项

这是变更日志中条目最多的一个版本，几乎覆盖了 WebAPI 的每个控制器。以下按功能域逐条说明。

仅接受 POST 的端点收紧

search/downloadTorrent与rss/setFeedRefreshInterval现在只接受POST请求。这一约束并非由控制器自身实现，而是由 Web 应用层统一强制的：webapplication.h 中的m_allowedMethod表以「控制器名 + 动作名」为键声明了全部强制 POST 的端点，其中就包括：

• {{u"rss"_s, u"setFeedRefreshInterval"_s}, Http::HEADER_REQUEST_METHOD_POST}
• {{u"search"_s, u"downloadTorrent"_s}, Http::HEADER_REQUEST_METHOD_POST}

这意味着此前若用 GET 携带查询参数调用这两个端点的脚本，在 2.16.0 上会被拒绝。事实上该表还列出了大量其他强制 POST 的动作（auth/login、torrents/add、app/setPreferences、torrentcreator/addTask等），是排查「方法不允许」类 4xx 错误的权威清单。

torrents/add：seedMode 与 skip_checking 的取舍

torrents/add新增布尔参数seedMode（仅做种子、不先下载），同时不再接受skip_checking参数。这是典型的「新语义参数替换旧参数」式破坏性变更：如果你的自动化流程依赖skip_checking跳过文件校验，需要改为在添加后通过其他端点组合实现等价行为，或改用seedMode控制初始行为。

app/preferences：新增 WebUI 会话数限制

app/preferences与app/setPreferences均包含web_ui_sessions_count_limit（int）选项，用于限制并发 WebUI 会话数量。该配置项最终会作用于 webapplication.h 中的m_sessionsCountLimit成员，配合会话超时共同控制登录态数量。

.torrent 文件备份选项取代 export_dir

本版本对偏好接口做了一次结构性调整：

• export_dir与export_dir_fin两个选项被移除，因为核心已不再支持该功能；
• 取而代之的是五个新选项：
  • torrent_files_backup_enabled（bool）：是否保存 .torrent 文件备份副本；
  • torrent_files_backup_dir（string）：备份副本所在目录；
  • torrent_files_finished_backup_dir_enabled（bool）：种子完成后是否将备份移动到其他目录；
  • torrent_files_finished_backup_dir（string）：完成后备份的目标目录；
  • remove_torrent_file_backup（bool）：删除种子时是否同时删除其 .torrent 文件备份。

其他新增偏好与同步指标

• enable_multi_connections_from_same_peer_id：允许来自同一 peer ID 的多连接；
• seeding_outgoing_connections：种子阶段是否建立出站连接；
• max_outstanding_block_requests：最大未完成块请求数；
• mail_notification_ssl_enabled被移除，由mail_notification_encryption_type取代，用于描述更细粒度的 SMTP 加密类型（对应仓库中的 smtpencryptiontype.h）；
• sync/maindata新增request_latency（请求延迟）与queued_tracker_announces（排队中的 tracker 通告数）两项全局指标；
• sync/torrentPeers的每个 peer 新增计算字段contribution，表示该 peer 对进度条增长的贡献。

torrentcreator：ignoreDotfiles 与 Unix 时间戳

torrentcreator/addTask新增布尔选项ignoreDotfiles，控制创建种子任务时是否忽略点文件，默认值为true。从源码可以确认这一点：torrentcreatorcontroller.cpp 中addTaskAction()以parseBool(params()[KEY_IGNORE_DOTFILES]).value_or(true)解析该参数；而torrentcreator/status端点会回传ignoreDotfiles字段，且timeAdded、timeStarted、timeFinished三个字段统一改为 Unix 时间戳（秒）——源码中对应Utils::DateTime::toSecsSinceEpoch(task->timeAdded())的序列化逻辑，旧客户端若按人类可读时间字符串解析该端点会出问题。

元数据端点：排除文件时的 priority 字段

torrents/fetchMetadata与torrents/parseMetadata在应用排除文件规则（excluded file names）时，会在文件条目中附带priority字段，方便调用方在添加前预先知道哪些文件会被降为跳过。

transfer/getSpeedLimits 与 setSpeedLimits 双端点

2.16.0 新增一对端点，一次性处理全局与备选（alternative）四组限速值：

• transfer/getSpeedLimits：返回up_limit、dl_limit、alt_up_limit、alt_dl_limit；
• transfer/setSpeedLimits：以同样四个参数批量设置。

其实现见 transfercontroller.cpp：getSpeedLimitsAction()直接从BitTorrent::Session::instance()读取四组全局限速值组装 JSON 对象；setSpeedLimitsAction()则要求四个参数同时存在（requireParams），并分别调用会话的setGlobalUploadSpeedLimit/setGlobalDownloadSpeedLimit/setAltGlobalUploadSpeedLimit/setAltGlobalDownloadSpeedLimit。注意与之相邻的setUploadLimit/setDownloadLimit端点会把0归一化为-1（不限速）后再写回会话，调用方应知悉这一约定。

torrents/downloadFile：直接下载已完成的文件

新增torrents/downloadFile端点，参数为hash与file，允许直接从种子内容中下载已下载完成的单个文件。file既可以传文件索引，也可以传相对于内容根目录的路径。

源码 torrentscontroller.cpp 中downloadFileAction()展示了完整的校验链：

1. 按hash查找种子，找不到抛NotFound（404）；
2. 种子元数据不可用时抛Conflict（409）；
3. file参数按整型解析成功时作为文件索引，越界抛 409；否则按路径遍历torrent->filePath(i)匹配，匹配不到同样抛 409；
4. 通过filesProgress()检查该文件下载进度，未达 1 时抛「File not fully downloaded」的 409 错误。

这一端点让「只下载种子中某个文件」的 Web 工作流得以闭环，无需先把文件拷到本地。

2.15.x 系列：RSS 克隆、磁盘空间与可用性端点

2.15.4：rss/cloneRule

新增rss/cloneRule端点，参数sourceName与cloneName，用于克隆一个已存在的 RSS 自动下载规则。该动作同样位于 webapplication.h 的强制 POST 表中（{{u"rss"_s, u"cloneRule"_s}, Http::HEADER_REQUEST_METHOD_POST}）。

2.15.3：share_limits_mode 三处打通

sync/maindata端点为每个种子包含share_limits_mode字段，同时app/preferences/app/setPreferences支持同名的全局选项。三者打通后，面板可以完整展示并修改「种子分享限制策略模式」，而不必猜测行为。

2.15.2：app/getFreeSpaceAtPathAction

新增app/getFreeSpaceAtPathAction端点，参数path，返回指定路径所在位置的剩余磁盘空间。这对在选择下载目录前做容量预检的集成场景非常实用，底层对应仓库中的磁盘空间检查组件 freediskspacechecker.cpp。

2.15.1：进程信息与件可用性

• app/processInfo：返回launch_time，即进程启动时间（UTC epoch 秒），便于外部监控判断实例存活时长与是否需要重启；
• sync/torrentPeers：在启用 peer 主机名解析时，额外包含 peer 的host_name字段；
• 新增torrents/pieceAvailability端点，返回种子每个 piece 的可用副本数；torrents/properties也新增availability字段，表示所选文件已分发副本数；
• torrents/editCategory行为修正：对未改动的分类不再报错；编辑不存在的分类时抛出 404「Not Found」，使错误语义更精确。

2.15.0：Basic auth 与 use_subcategories 移除

两个重要变更：

• WebAPI 凭据现可通过 Basic auth 提供（auth/login之外的第二种认证入口），适合不便处理 Cookie 的脚本客户端；
• sync/maindata不再包含use_subcategories键——子分类功能已始终启用，该配置失去意义。依赖该字段做兼容判断的客户端需要移除相应逻辑。

2.14.x 系列：API Key 生命周期管理与 404 语义

2.14.1：rotateAPIKey 与 deleteAPIKey

新增两个端点管理 API Key 的完整生命周期：

• app/rotateAPIKey：生成并轮换 WebAPI 的 API Key；
• app/deleteAPIKey：删除现有 API Key。

源码中 appcontroller.cpp 提供了rotateAPIKeyAction()实现，且两个动作都登记在强制 POST 表中。配合 2.13.1 的clientdata端点，管理员可以完成「轮换密钥 → 分发新密钥 → 删除旧密钥」的标准运维流程。

2.14.0：错误响应语义精细化

• 端点不存在时，WebAPI 返回明确的错误消息「Endpoint does not exist」，以区别于普通 404（资源不存在）；
• auth/login凭据无效时返回 401（此前语义不一致）；
• torrents/add响应改为携带success_count、pending_count、failure_count与added_torrent_ids四个字段，并按结果细分状态码：pending_count非零时返回202（已接受、异步处理中），全部失败时返回409。批量添加的种子应按此三态逻辑编写重试与告警。

2.13.x 系列：搜索插件下载、clientdata 与 tracker 细节

2.13.1：downloader 参数与 clientdata 端点

• torrents/add与torrents/fetchMetadata支持通过downloader参数从搜索插件（search plugin）拉取种子。源码印证见 torrentscontroller.cpp：处理逻辑通过SearchPluginManager::instance()->downloadTorrent(downloaderParam, url)委托给 searchpluginmanager.cpp 执行异步下载；
• 新增clientdata/load与clientdata/store端点，用于管理 WebUI 特有的客户端设置与其他共享数据，实现位于 clientdatacontroller.cpp，其底层存储见 clientdatastorage.cpp。

2.13.0：torrents/trackers 的 endpoints 数组与 i2p 支持

• torrents/trackers新增next_announce、min_announce与endpoints三个字段。endpoints是 tracker 端点数组，每项含name、updating、status、msg、bt_version、num_seeds、num_leeches、num_downloaded、next_announce、min_announce等子字段（原文档列出的字段列表中num_peers重复出现，实际以两个不同维度的同伴计数字段为准）；
• status字段新增可能取值5（Tracker error）与6（Unreachable）；
• torrents/editTracker支持通过tier参数设置 tracker 层级；成功时统一返回 204；origUrl参数重命名为url——这是对调用方最直接的破坏性改名；
• sync/torrentPeers对来自 I2P 网络的 peer 返回i2p_dest字段，且此时不再返回ip与port；
• torrents/parseMetadata的响应结构从「以提交文件名为键的对象」改为与请求文件顺序一致的数组，解析代码若按下标无关的方式取键会静默取错数据。

2.12.x：注释编辑与分享限制动作

• 2.12.1 新增torrents/setComment端点，参数hashes与comment，用于批量设置种子注释；
• 2.12.0 中sync/maindata返回新字段share_limit_action，且torrents/setShareLimits改为必须携带shareLimitAction参数，可选值为Default、Stop、Remove、RemoveWithContent、EnableSuperSeeding，与仓库中的 sharelimits.h 定义的枚举语义一致。

2.11.x：序列化修正、元数据三件套与响应规范化

2.11.10 与 2.11.9：序列化与批量 tracker 操作

• torrents/categories与sync/maindata将分类的downloadPath序列化为null而非undefined，消除 JSON 层面「键存在但值缺失」的歧义；
• torrents/reannounce支持通过trackers字段指定单个 tracker 重新通告；
• 2.11.9 是元数据能力的里程碑：新增torrents/fetchMetadata（从 URL 获取元数据）、torrents/parseMetadata（从 .torrent 文件解析元数据）、torrents/saveMetadata（把元数据保存为 .torrent 文件）三个端点；torrents/add支持直接使用此前获取的元数据添加种子，并支持指定文件优先级；
• torrents/addTrackers与torrents/removeTrackers接受hash=all，把 tracker 应用到全部种子；为兼容旧客户端，removeTrackers仍接受hash=*（内部转换为all）；两个端点还支持以竖线|分隔的多个 hash。

2.11.8：204 No Content 与元数据参数

• 空响应体开始返回204 No Content；为平滑过渡，部分端点此版本仍返回200 OK，客户端不应假设 204 已全面生效；
• torrents/info新增可选参数includeFiles（默认false），为真时每个种子附带与torrents/files相同的files键，减少面板往返；
• app/getDirectoryContent新增可选参数withMetadata，为目录项附带name、type、size、creation_date、last_access_date、last_modification_date字段。

2.11.7 与 2.11.6：状态位与偏好互斥约束

• 2.11.7：sync/maindata为每个种子新增has_tracker_warning、has_tracker_error、has_other_announce_error三个布尔状态位，方便列表页快速着色告警；
• 2.11.6：app/setPreferences引入互斥约束——max_ratio_enabled与max_ratio、max_seeding_time_enabled与max_seeding_time、max_inactive_seeding_time_enabled与max_inactive_seeding_time这三组开关/数值对，每次请求只允许出现其中一个，避免「开关与数值不一致」的半更新状态。

升级检查清单

结合上述变更日志，从任意旧版本升级到 2.16.0 前，建议按以下清单核对集成代码：

1. 请求方法：所有写操作端点（包括search/downloadTorrent、rss/setFeedRefreshInterval）确认使用 POST，权威清单见 webapplication.h 的m_allowedMethod；
2. 被移除的参数/选项：skip_checking、export_dir、export_dir_fin、mail_notification_ssl_enabled、use_subcategories、editTracker的origUrl——逐一替换为seedMode、备份目录四选项、mail_notification_encryption_type、url；
3. 响应结构：torrents/parseMetadata改为数组、torrents/add改为三态计数字段 + 202/409 状态码、torrents/editTracker统一 204；
4. 时间格式：torrentcreator/status的时间字段均为 Unix 秒；
5. 认证：若使用 API Key，规划rotateAPIKey/deleteAPIKey的轮换流程；
6. 新增机会：利用torrents/downloadFile、transfer/getSpeedLimits/setSpeedLimits、torrents/pieceAvailability、app/getFreeSpaceAtPathAction等端点补齐旧流程中依赖本地文件系统的缺口。

变更日志本身位于仓库根目录的 WebAPI_Changelog.md，端点实现集中于 src/webui/api/ 下的各控制器（torrentscontroller.cpp、transfercontroller.cpp、torrentcreatorcontroller.cpp、clientdatacontroller.cpp、rsscontroller.cpp 等），对照阅读日志条目与控制器源码，是验证某一版本 WebAPI 行为最可靠的方式。

【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent