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

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 行为最可靠的方式。