企业官网建设流程全解析

qBittorrent 如何用 WebUI API 创建种子任务并跟踪制作状态

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

如果你想在脚本或自动化流程里"把服务器上的某个文件夹打包成 .torrent 文件"，而不是打开 WebUI 点按钮，qBittorrent 的 WebUI API 提供了torrentcreator这一组接口：提交一个制作任务、轮询任务状态、最后把生成好的 .torrent 文件下载下来。整个过程只需要 HTTP 请求，适用于 headless 部署和批处理场景。

本文的操作对象是 qBittorrent WebUI 的 REST API，所有接口都挂在/api/v2/前缀下（见 webapplication.cpp 中的API_PATH定义）。前提是你的 qBittorrent 实例已经开启了 WebUI（GUI 版在选项里启用 WebUI，或运行带 WebUI 的 nox 版本），并且你知道 WebUI 的用户名、密码以及监听的端口。下文中http://<host>:<port>请替换为你实际的 WebUI 地址和端口。

四个 torrentcreator 端点与参数

torrentcreator控制器注册了 4 个 action（torrentcreatorcontroller.cpp）：

addTask参数的几个要点（均取自控制器源码的解析逻辑）：

• sourcePath是唯一必填参数，必须能被 qBittorrent 进程访问到（本地文件系统路径）。
• torrentFilePath指定 .torrent 文件的保存位置。注意startSeeding参数的行为：未提供torrentFilePath时默认值为true，制作完成后会直接把内容加入会话开始做种；提供了torrentFilePath时默认为false，即只生成文件、不做种。
• trackers和urlSeeds都是多个 URL 的列表，传输时用管道符|分隔，每个 URL 需做百分号编码（如https%3A%2F%2F...），空行表示 tracker 分层。
• ignoreDotfiles默认true（忽略点文件），private默认false。
• 使用 libtorrent 2 构建的版本用format参数选择种子格式，可选v1、v2或不传（默认hybrid）；旧构建则使用optimizeAlignment和paddedFileSizeLimit参数，二者不会同时存在。

第一步：登录取得会话

auth/login是唯一公开（无需鉴权）的端点，其余 API 都需要有效会话。两种方式任选其一：

方式一：Cookie 会话。POST 请求带上 Basic 认证，成功后响应里会返回SIDcookie，后续请求携带它即可：

curl -c cookies.txt -X POST 'http://<host>:<port>/api/v2/auth/login' \ --user '<username>:<password>'

把 WebUI 用户名密码替换进--user。-c把会话 cookie 存到cookies.txt，后续请求加-b cookies.txt复用。

方式二：API Key 会话（可选分支）。先生成一个 API key：

curl -b cookies.txt -X POST 'http://<host>:<port>/api/v2/app/rotateAPIKey'

响应是 JSON，形如{"apiKey": "..."}，取出apiKey字段后，之后的请求改用Authorization: Bearer <apiKey>头即可，不再依赖 cookie。注意使用 API key 会话时调用任何auth/*端点都会被拒绝（返回 403），登录只能靠 cookie 完成。

第二步：提交种子制作任务

向addTask发送POST表单请求。以"把/data/releases/ubuntu-24.04打包成私有种子、保存为/data/out/ubuntu.torrent"为例：

curl -b cookies.txt -X POST 'http://<host>:<port>/api/v2/torrentcreator/addTask' \ -d 'sourcePath=/data/releases/ubuntu-24.04' \ -d 'torrentFilePath=/data/out/ubuntu.torrent' \ -d 'private=true' \ -d 'format=v1' \ -d 'trackers=https%3A%2F%2Ftracker.example.com%2Fannounce'

成功时响应是 JSON：

{"taskID": 1}

记下taskID，后续轮询和下载都靠它。如果服务端提示任务数过多（Too many active tasks），请求会返回 409 冲突错误，此时需要先等待已有任务完成或先deleteTask清理再重试。

第三步：轮询任务状态

status端点接受taskID查询单个任务，不带参数则返回全部任务：

curl -b cookies.txt 'http://<host>:<port>/api/v2/torrentcreator/status?taskID=1'

响应是任务对象数组，每个对象的核心字段：

• status：Queued（排队中）、Running（制作中）或Finished（已结束）；
• progress：仅Running时出现，表示制作进度；
• timeAdded/timeStarted/timeFinished：Unix 时间戳，timeFinished仅在任务结束时出现；
• errorMessage：任务失败时出现，包含失败原因。

判断逻辑：status为Finished且没有errorMessage字段，说明制作成功，可以进入下载步骤；有errorMessage说明失败，根据消息内容排查（常见诱因是sourcePath不可读或torrentFilePath所在目录不可写）；仍是Queued/Running则继续轮询。

第四步：下载 .torrent 文件并清理任务

任务成功后，用torrentFile端点取出文件内容。它返回Content-Type: application/x-bittorrent，文件名为<taskID>.torrent：

curl -b cookies.txt -o ubuntu.torrent \ 'http://<host>:<port>/api/v2/torrentcreator/torrentFile?taskID=1'

两个失败模式要注意：任务还没做完就调用会返回 409（"Torrent creation is still unfinished."），任务失败时同样返回 409（"Torrent creation failed."）。下载完成后，如果不再需要保留这条任务记录，可以删除它（仅移除 qBittorrent 里的任务条目，不影响已生成的 .torrent 文件）：

curl -b cookies.txt -X DELETE 'http://<host>:<port>/api/v2/torrentcreator/deleteTask?taskID=1'

taskID不存在时该端点返回 404。

限制与边界

• 整条链路的前提是 qBittorrent 进程本身能读到sourcePath并能在torrentFilePath处写文件；API 不接收远程主机上的文件，sourcePath只能是服务端的本地路径。
• 认证方式二选一：cookie 会话和 API key 会话不能混用，API key 会话下auth/*端点一律 403。
• 任务并发数受服务端限制，addTask在超限时返回 409，需要轮询等待或清理旧任务。
• 生成 .torrent 之后是否做种由startSeeding/torrentFilePath的默认关系决定，自动化"仅生成文件"的流程应保持默认行为（提供torrentFilePath且显式不做种）；若希望生成后立即做种，显式传startSeeding=true。
• 各版本间addTask的参数有差异（libtorrent 2 构建用format，旧构建用optimizeAlignment/paddedFileSizeLimit），status的时间字段自 2.16.0 起返回 Unix 时间戳（见 WebAPI_Changelog.md），对接旧客户端时注意兼容。

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