qBittorrent / WebUI 与 API
WebUI 与 API：把 BT 客户端变成可远程操作的服务
qBittorrent 的远程能力不是外挂：Web UI（src/webui/www）与 WebAPI 是同一套后端，无界面版 qbittorrent-nox 就是靠它操作的。官方维护独立的 WebAPI_Changelog.md，当前 API 版本为 2.16.2，端点覆盖偏好设置、任务、传输会话、同步、搜索与 RSS。能力越强，暴露面越大——这一页把「怎么用」和「怎么别被扫到」放在一起讲。
src/webui/ 目录结构与 WebAPI_Changelog.md）；示意非官方架构图，端点与参数以你所装版本的 API 文档为准。什么情况下需要 Web UI / API
先把场景想清楚，再决定开不开——这是安全的第一步。
| 场景 | 用哪个能力 | 收益 | 代价 / 风险 |
|---|---|---|---|
| NAS 上没有桌面环境 | Web UI（配合 nox 构建） | 全部操作可视化 | Web UI 端口必须做访问控制 |
| 在公司/手机上添加任务 | Web UI 或 API | 不用回家也能加种子 | 意味着该服务在网络上可达 |
| 自动下载订阅内容 | RSS 自动下载规则 | 新内容出现即下载 | 规则里放什么源完全由你负责 |
| 批量脚本、面板集成 | WebAPI | 可接入自己的工具链 | API 凭据泄露等于把客户端交出去 |
| 把搜索能力接进自己的流程 | search 相关端点 + 搜索插件 | 可程序化发起搜索 | 搜索结果怎么用与合法性由你判断 |
WebAPI 端点有哪些（基于 2.16.2）
端点很多，但按前缀只有几类。下表按用途归类，并标出写脚本时最容易踩的点。
| 前缀 / 端点 | 用途 | 写脚本时的注意点 | 近期变化（来自官方 changelog） |
|---|---|---|---|
app/preferences、app/setPreferences | 读取/写入客户端全部偏好 | 选项会随版本增减，硬编码字段名容易失效 | 新增 I2P 相关选项、Web UI 会话数上限等 |
torrents/add 等任务端点 | 添加、暂停、删除、查询任务 | 参数随版本变化：seedMode 新增、skip_checking 移除 | 2.16.0 明确调整了这两个参数 |
transfer/pauseSession、transfer/resumeSession | 整会话暂停/恢复 | 与「暂停单个任务」不是一回事 | 2.16.2 新增 |
sync/maindata | 增量同步主数据（做面板必备） | 适合轮询，但要注意频率 | 新增 session_state 字段 |
search/status、search/downloadTorrent | 搜索任务状态与结果处理 | 部分端点只接受 POST | 2.16.0 起 search/downloadTorrent 仅接受 POST |
rss/*（含 exportRules/importRules） | RSS 订阅与自动下载规则管理 | importRules 只接受 POST | 2.16.2 新增规则导入导出 |
app/setPreferences 中的备份项 | .torrent 文件备份与完成后转移 | 适合长期保种的场景 | 2.16.0 重构了 .torrent 备份管理 |
WebAPI_Changelog.md，说明这门接口在持续演进。写脚本前先确认「你的客户端版本对应的 API 版本」，并给对方留出兼容余量——本站不复制官方 API 文档全文，请以仓库内该文件为准。开启远程访问的五个步骤
顺序很重要：先加固，再开放。
先决定「谁来访问」
只在局域网用？还是要从公网访问？前者可以简单些，后者必须配合反向代理与额外的鉴权层。不要直接把管理端口暴露到公网。
设置强口令并改默认凭据
Web UI 的账号口令是唯一屏障，设置为不可猜测的长口令，并避免在多个服务里复用。
限制来源与协议
能限制来源网段就限制；优先走 HTTPS（反向代理层提供证书），避免在明文 HTTP 上传输口令。
确认是否需要开 API
只用人机界面的，就把用不到的接口访问路径收窄；要接脚本的，给脚本单独凭据并限制其权限范围。
做一次自测
从未授权网络访问一次，确认拿到的是拒绝而不是登录页；同时检查客户端日志里是否出现大量异常登录尝试。
qBittorrent 暴露面怎么自检
下面每一条都能在几分钟内自查完，建议开启远程之前逐项过一遍。
| 检查项 | 不安全的样子 | 改法 | 最坏后果 |
|---|---|---|---|
| 默认凭据 | 仍用初始账号口令，或口令很短 | 改成强口令 | 被扫描到即可被接管 |
| 直接暴露管理端口 | 家用宽带上做端口映射到 Web UI | 走反向代理 + 额外鉴权；或只在局域网/VPN 内访问 | 端口扫描机器人几分钟内就会找到 |
| 明文 HTTP | 口令与 Cookie 在网络上明文传输 | 用 HTTPS | 同网络内可被截获 |
| 不限制来源 | 任何 IP 都能拿到登录页 | 限制来源网段或加访问控制层 | 持续被撞库 |
| API 凭据外泄 | 把含凭据的脚本/配置提交到公开仓库 | 凭据放环境变量或专用配置文件，并加入忽略清单 | 等同把客户端操作权交出去 |
| 日志不看 | 没有登录失败监控 | 定期看日志里的异常尝试 | 被持续尝试也毫无察觉 |
SECURITY.md 明确要求漏洞不要走公开 issue，而是用 GitHub 的私有漏洞报告功能或邮件 security@qbittorrent.org；CVE 也通过这个私有渠道申请与发布。并且安全策略只覆盖最新稳定分支——旧版本上的同类问题不会被修。这也是「及时升级」的直接理由。qBittorrent RSS 与搜索插件的自动化能力与边界说明
这两个功能常被当成「找资源」的入口，但它们本质上只是自动化工具，来源仍由你决定。
| 能力 | 它做什么 | 你需要自己负责的部分 | 注意点 |
|---|---|---|---|
| RSS 订阅 + 自动下载规则 | 按规则从订阅源里自动挑条目下载 | 订阅源的合法性、规则写得是否精准（避免下错一堆） | 规则可导出/导入，便于备份与迁移 |
| 内置搜索引擎 + 插件 | 通过插件到各来源检索 | 插件来源与你搜索用途的合法性 | 构建时 Python ≥3.13.0 是可选依赖，仅搜索用 |
| 任务完成后的动作 | 可与脚本/通知配合（如邮件通知） | 通知渠道的凭据与隐私 | 邮件通知相关修复在 5.2.x 发布说明里出现过 |
| .torrent 备份 | 自动保存任务清单副本，完成时可移动到别处 | 备份目录的容量与清理策略 | 长期保种场景很实用，2.16.0 起相关设置被重构 |
qBittorrent WebUI 与 API 常见问题
端点与参数以仓库 WebAPI_Changelog.md 与你所装版本为准；本站未实机调用 API。
Web UI 和 API 是两套东西吗？
不是。它们在同一个后端之上：Web UI 是浏览器界面，WebAPI 是给脚本和第三方客户端用的接口，仓库里 src/webui/api 与 src/webui/www 并存就是这个结构的体现。所以「Web UI 能做的事，API 基本也能做」——反过来也一样，这意味着加固 Web UI 时不能忽略 API。
能不能把 Web UI 直接暴露到公网？
技术上可以，但风险很高：管理端口一旦被扫到，攻击者只需要口令就能用你的带宽和 IP 下载任意内容。稳妥做法是走反向代理加一层鉴权、或用 VPN 访问、或只在局域网内使用。qBittorrent 自身提供了账号口令与来源限制，但这不是让人把端口毫无防护地放上公网的许可。
API 版本号在哪里看？
官方仓库根目录有独立的 WebAPI_Changelog.md，按版本列出端点的增删改；当前版本为 2.16.2。写脚本时建议先对照该文件确认「你目标版本支持哪些字段」，因为这套接口在持续演进（例如 2.16.0 就改动了 torrents/add 的参数）。
RSS 自动下载会不会下到一堆不想下的东西？
会——规则的宽窄直接决定后果。建议先用很窄的规则试跑，确认匹配结果符合预期，再逐步放宽。规则支持导出/导入，方便你把验证过的配置备份下来。至于订阅什么源，本站不提供也不评价。
搜索插件需要额外装什么吗？
官方构建文档里写明 Python ≥3.13.0 是可选、仅运行期的依赖，用途就是内置搜索引擎。也就是说不用搜索引擎的话可以不装 Python。插件本身的来源与可用性请自行判断，本站不提供插件清单。
远程访问时怎么确认自己没被扫？
看两方面：①客户端日志里是否出现大量失败登录；②你的反向代理/防火墙日志里是否有来自陌生 IP 的高频请求。这两处任一出现异常，就说明你的端口已经在被扫描，应立刻收紧访问控制。这个自检属于「安全检查清单」的一部分。
发现安全问题该往哪报？
按官方 SECURITY.md：不要走公开 issue，用 GitHub 的私有漏洞报告功能，或邮件 security@qbittorrent.org，并附上问题类型、复现步骤、PoC 与影响评估。CVE 的申请与发布也通过这条私有渠道完成。另外官方只维护最新稳定分支——所以先确认你的版本是否还在维护范围内。