qBittorrent 5.3.0 配置参数详解

‍‍‌> 本文是 qBittorrent 专栏的配置篇。以下内容于 2026-10-26 在一台真实的 Ubuntu 22.04 LTS 服务器上以 qbittorrent-nox v5.3.0 实测完成：参数查看与修改的三个通道、qBittorrent.conf 关键参数逐项「修改—验证」闭环（监听端口/保存路径/限速/队列/DHT-LSD/分类/RSS/WebUI 安全），以及配置文件迁移、多实例 profile 与运维踩坑实录。文中所有命令回显均为实测原文；组件画像见《qBittorrent 5.3.0 介绍与选型指南》，安装步骤见《Ubuntu 22.04 安装 qBittorrent 5.3.0 指南》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64，systemd 249
软件版本：qbittorrent-nox v5.3.0（静态二进制，内嵌 Qt 6.12.0 / libtorrent 2.1.2.0 / boost 1.92.0，app/buildInfo 实查）
服务形态：systemd 托管（qbittorrent-nox.service，用户 qb），Web UI 8080，BT 监听 6881
配置文件：/opt/qbittorrent/.config/qBittorrent/qBittorrent.conf
同机多实例：做种端第二实例 --profile=/opt/qb-seed --webui-port=8081（用于分类路径/限速对照实验）
实测时间：2026-10-26

二、前置条件

已按部署篇完成 qbittorrent-nox 5.3.0 安装与 systemd 托管，systemctl is-active qbittorrent-nox 返回 active；
具备服务器本地 shell（本文所有 conf 修改均为服务停机窗口内操作）；
Web API 可用（部署篇 7.2 节已设置正式账号，本文命令示例统一使用 admin/q1w2e3r4，生产环境请使用强密码）；
若按本文操作自己的服务器，注意 Session\Port 等值需与你规划的端口矩阵一致，避免照抄引发端口冲突。

三、参数的查看与修改通道

qBittorrent 的参数有三个等价操作通道，运行行为一致但单位与生效时机不同：

通道	入口	单位口径	生效时机
Web UI	浏览器「工具 → 选项」	界面显示 KiB/s	保存即生效，退出时落盘 conf
Web API v2	`/api/v2/app/preferences`（GET 读）与 `/api/v2/app/setPreferences`（POST 写）	速度为字节/秒（B/s）	写入即生效，退出时落盘 conf
配置文件	`qBittorrent.conf`	速度为KiB/s	服务启动时加载；停机修改才安全

⚠️ 单位踩坑（高频事故源）：API 的 dl_limit=16777216 表示 16 MiB/s；写进 conf 时对应 Session\GlobalDLSpeedLimit=16384（KiB/s）。本文后续参数表均标注双口径。

3.1 通道优先级

命令行参数 > 运行内存态 > 配置文件。部署篇的 systemd 单元里写了 --webui-port=8080，此时无论 conf 中 WebUI\Port 怎么改（或省略），Web UI 端口都以命令行为准。配置端口建议二选一：固定走命令行，或去掉命令行参数全部交给 conf 管理。

3.2 安全修改流程（实测对照）

错误姿势——运行中直接改 conf：

sed -i 's|^Session\\Port=18617|Session\\Port=6999|' /opt/qbittorrent/.config/qBittorrent/qBittorrent.conf
grep '^Session\\Port' /opt/qbittorrent/.config/qBittorrent/qBittorrent.conf
systemctl restart qbittorrent-nox && sleep 3
grep '^Session\\Port' /opt/qbittorrent/.config/qBittorrent/qBittorrent.conf

实测回显（修改被运行态写回覆盖）：

Session\Port=6999
Session\Port=18617

原因：qBittorrent 退出时将内存中全部参数整体写回 conf，覆盖你的手工编辑。

正确姿势——先停后改再启：

systemctl stop qbittorrent-nox
# <在停机窗口内修改 conf>
systemctl start qbittorrent-nox

四、当前配置文件全貌

本节为实测服务器的 qBittorrent.conf（已完成第五~八章全部「修改—验证」闭环后的终态），后续章节逐项解读：

[BitTorrent]
Session\DefaultSavePath=/srv/qbittorrent/downloads
Session\MaxActiveDownloads=3
Session\MaxActiveUploads=5
Session\MaxActiveTorrents=8
Session\GlobalDLSpeedLimit=16384
Session\GlobalUPSpeedLimit=8192
Session\Port=6881
Session\QueueingSystemEnabled=true
Session\SSL\Port=26037
Session\Tags=asciitag, pytag1, pytag2, 内网验证, 自建源
Session\UseAlternativeGlobalSpeedLimit=false

[LegalNotice]
Accepted=true

[Meta]
MigrationVersion=12

[Network]
Cookies=@Invalid()

[RSS]
AutoDownloader\EnableProcessing=true
Session\MaxArticlesPerFeed=100

[WebUI]
MaxAuthFailures=5
BanDuration=3600
Password_PBKDF2="@ByteArray(DDI06KIgEMK7r3QSj6qtDw==:1Homsbnae2Z+03ZC36htUX4z+AssmS3Ew2GJoaaK2A2UzrpWi+jYhIozCP4VZPZCxwN9bblfz84qpMH82m5xWg==)"

结构说明：conf 按 Qt INI 风格分节；[BitTorrent] 存会话类参数，[Preferences] 存 WebUI/下载/连接类参数（本机因多数项保持默认或由命令行接管而未显式落盘），[Meta] 的 MigrationVersion 是配置结构版本号（跨大版本升级自动迁移的依据），Password_PBKDF2 是 WebUI 口令的加盐 PBKDF2 摘要（不存明文，禁止手工伪造）。首启时未显式配置的键不写入文件——这就是为什么全新安装的 conf 里看不到 WebUI\Port。

五、BitTorrent 会话参数

5.1 BT 监听端口 `Session\Port`

conf 键：[BitTorrent] Session\Port
API 键：listen_port
默认值：随机（v5.x 首启行为，实测首启随机到 18617；HTTPS 备用端口 Session\SSL\Port 同样随机，实测 26037）
修改方法：停机窗口内 sed 修改后重启；或 API 写 {"listen_port":6881}（立即生效）

实测验证（改 6881 后 API 读回）：

listen_port: 6881

端口监听核实：

LISTEN 0      30        127.0.0.1%lo:6881        0.0.0.0:*
LISTEN 0      30     10.89.61.2%eth0:6881        0.0.0.0:*

💡 服务器有公网 IP 时，BT 端口必须在防火墙放行 TCP+UDP（DHT/uTP 依赖 UDP），并确认路由器/安全组映射，否则 transfer/info 的 connection_status 长期显示 firewalled，连接性差。

5.2 默认保存路径 `Session\DefaultSavePath`

conf 键：Session\DefaultSavePath
API 键：save_path
默认值：用户 HOME 下 Downloads
修改方法：conf（停机）或 API setPreferences {"save_path":"..."}（立即生效，仅影响之后新增任务）

实测验证：

save_path: /srv/qbittorrent/downloads

⚠️ 与分类保存路径的关系：任务未启用「自动 Torrent 管理（autoTMM）」时一律落 DefaultSavePath，分类的保存路径只在 autoTMM 生效或任务显式指定时使用。实测中通过 API torrents/add（未传 autoTMM=true）添加已挂 samples 分类（保存路径 /srv/qbittorrent/downloads）的种子，实际落盘在默认路径 /opt/qbittorrent/Downloads——分类路径不会自动套用。修正用 torrents/setSavePath（参数 id + path）后重启任务重新校验，或添加时显式带 savepath 表单字段。

5.3 全局限速 `Session\GlobalDLSpeedLimit` / `GlobalUPSpeedLimit`

conf 键：Session\GlobalDLSpeedLimit / Session\GlobalUPSpeedLimit（KiB/s）
API 键：dl_limit / up_limit（B/s）
默认值：0（不限）
修改方法：API setPreferences {"dl_limit":16777216,"up_limit":8388608}（16/8 MiB/s）

实测验证：

curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/transfer/info

{"connection_status":"firewalled","dht_nodes":73,"dl_info_data":0,"dl_info_speed":0,"dl_rate_limit":16777216,"last_external_address_v4":"182.54.113.29","last_external_address_v6":"","up_info_data":0,"up_info_speed":0,"up_rate_limit":8388608}

conf 落盘验证（退出后写回 KiB/s 口径）：

Session\GlobalDLSpeedLimit=16384
Session\GlobalUPSpeedLimit=8192

5.4 备速模式（Alt Speed）`Session\UseAlternativeGlobalSpeedLimit`

conf 键：Session\UseAlternativeGlobalSpeedLimit（bool，true=启用备速档）
API 键：alt_dl_limit / alt_up_limit（KiB/s 口径读回）+ /transfer/speedLimitsMode（0=全局档，1=备速档）
默认值：false；备速默认 alt_dl_limit=10240（10 MiB/s）、alt_up_limit=10240

实测验证（切换备速档并读回模式）：

curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/transfer/toggleSpeedLimitsMode
curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/transfer/speedLimitsMode -w " HTTP:%{http_code}\n"

 (mode HTTP:200)   ← 返回正文 1（备速档）

再次 toggle 切回 0 恢复。备速档适合「定时限速」场景：配合 cron 在工作时段切 1、夜间切 0，API 一次 toggle 即可。

5.5 任务队列 `Session\QueueingSystemEnabled` 等

conf 键：Session\QueueingSystemEnabled（bool）、Session\MaxActiveDownloads、Session\MaxActiveUploads、Session\MaxActiveTorrents
API 键：queueing_enabled、max_active_downloads、max_active_uploads、max_active_torrents
默认值：false / 3 / 3 / 5

实测修改（conf 停机改为 true/3/5/8）后 API 读回：

listen_port: 6881 | max_active_downloads: 3 | max_active_uploads: 5 | max_active_torrents: 8 | queueing_enabled: True | save_path: /srv/qbittorrent/downloads

队列语义：MaxActiveTorrents 是活动任务总数上限，MaxActiveDownloads 与 MaxActiveUploads 分别限下载/上传/做种活动数；超出者排队（状态 queuedDL/queuedUP），优先级可用 torrents/setPriority 调整。

5.6 DHT / PeX / LSD 会话开关

conf 键：Session\DHTEnabled / Session\PeXEnabled / Session\LSDEnabled（均为 bool，默认 true）
API 键：dht / pex / lsd

实测读回（首启默认态）：

dht: True | lsd: True | pex: True

排障实录（LSD 副作用）：同机双实例对照实验时，下载端未手动添加任何 peer，几秒内即完成 48 MB 下载——LSD（本地服务发现组播）让同网段实例互相发现了对方。该机制在生产同机多实例时同样生效，可能造成「测试流量混入生产实例」；内网压测/纯净对照场景建议关掉 DHT+LSD 或改用私有种子（mktorrent -p），私有种子会话会忽略 DHT/PeX/LSD。

⚠️ 实测还发现：联网环境下开启 DHT 时，sync/torrentPeers 中会出现来源为公网 DHT 的陌生 peer（flags 含 H）。做内网吞吐基准时务必用私有种子隔离，否则速度曲线会被公网流量污染。

六、分类与标签参数

分类与标签是 qBittorrent 的任务组织体系，规则如下（全部经 API 实测）：

概念	conf 键	API	能力
分类 Category	`Session\Categories\<名>\SavePath`	`torrents/createCategory` / `editCategory` / `removeCategories` / `categories`	名称 + 保存路径，任务单选
标签 Tag	`Session\Tags`（CSV 落盘）	`torrents/createTags` / `addTags` / `removeTags` / `tags`	仅名称，任务可多挂

6.1 创建分类（实测）

curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/torrents/createCategory \
  --data-urlencode "category=samples" --data-urlencode "savePath=/srv/qbittorrent/downloads" -w "HTTP:%{http_code}\n"
curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/torrents/categories

实测回显：

HTTP:200
{"samples":{"name":"samples","savePath":"/srv/qbittorrent/downloads"}}

⚠️ v5.3.0 API 形态变化（旧文档已失效）：createCategory/editCategory 收独立表单参数 category=<名称> 与 savePath=<路径>，不是 JSON 载荷。实测把 JSON 串（category={"name":"samples","savePath":"..."}）传给 v5.3.0 时，服务端会按 / 把参数值切分，产生若干名字破碎的垃圾分类（如名为 {"name":"samples","savePath":" 的分类），且返回 200——静默错误，事后需 removeCategories 清理。

6.2 标签实测

curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/torrents/createTags --data-urlencode "tags=内网验证,自建源" -w "HTTP:%{http_code}\n"
curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/torrents/tags
curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/torrents/addTags --data-urlencode "hashes=<任务hash>" --data-urlencode "tags=内网验证,自建源" -w "HTTP:%{http_code}\n"
curl -s -b /tmp/qb.cookie "http://localhost:8080/api/v2/torrents/info?hashes=<任务hash>" | python3 -m json.tool | grep tags

实测回显：

HTTP:200
["内网验证","自建源"]
HTTP:200
"tags": ["内网验证","自建源"]

标签随会话持久化在 conf 的 Session\Tags 键（逗号分隔，见第四章 conf 终态）。

⚠️ 查询过滤参数踩坑：torrents/info 的按任务过滤参数是 hashes（复数）；实测传 ?hash=<hash> 会被静默忽略、返回全量任务列表，脚本若取 [0] 极易误判。

七、RSS 参数

conf 键：[RSS] 节
API 键（preferences 内）：rss_processing_enabled、rss_auto_downloading_enabled、rss_refresh_interval、rss_max_articles_per_feed、rss_processing_interval、rss_smart_episode_filters

实测关键结论：

rss_auto_downloading_enabled 默认 false——这是「RSS 规则配好了却不自动下载」的第一嫌疑。开启实测：

curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/app/setPreferences \
  --data-urlencode "json={\"rss_auto_downloading_enabled\":true,\"rss_max_articles_per_feed\":100}" -w "HTTP:%{http_code}\n"

HTTP:200

规则引擎端点是 /rss/setRule（旧文档的 /rss/rules/createRule 在 5.3.0 为 404）：

curl -s -b /tmp/qb.cookie -X POST http://localhost:8080/api/v2/rss/setRule \
  --data-urlencode "ruleName=kernel-weekly" \
  --data-urlencode "ruleDef={\"enabled\":true,\"mustContain\":\"Kernel\",\"assignedCategory\":\"rss-auto\",\"affectedFeeds\":[\"http://127.0.0.1:8090/feed.xml\"]}" -w "HTTP:%{http_code}\n"

HTTP:200

affectedFeeds 必须填源的 URL 而非订阅名：实测填订阅名 本地样例源 时规则回读正常但 matchingArticles 始终为空；改为源 URL http://127.0.0.1:8090/feed.xml 后立刻匹配：

{"本地样例源": ["Linux Kernel Weekly Build 101"]}

文章去重：RSS 引擎按文章标识（link/id）记忆已处理文章，改标题不复用旧文章；实测在 feed 中新增 <item>（新 link）并 rss/refreshItem 后，规则命中并自动添加任务 mini-pack，分类/保存路径按 assignedCategory（rss-auto 的 /srv/qbittorrent/rss-dl）落位。
RSS 文章数据持久化在 ~/.local/share/qBittorrent/rss/（实测存在 articles 子目录），迁移服务器时与 BT_backup 一并带走。

八、Web UI 参数

8.1 端口/账号/密码

conf 键：[WebUI] WebUI\Port、WebUI\Username、WebUI\Password_PBKDF2
API 键：web_ui_port、web_ui_username、web_ui_password（写时明文，读回不回显）
默认值：8080 / admin / 未设置（v5.x 无固定默认密码，首启生成会话级临时密码，见部署篇 6.3 节）

改密实测（改后旧临时密码立即失效）：

旧临时密码登录 → HTTP:401
新密码登录 → HTTP:204

8.2 安全参数（全部默认值实测读回）

API 键	默认值	作用
`web_ui_csrf_protection_enabled`	true	拒绝跨站 Origin 的写请求
`web_ui_host_header_validation_enabled`	true	校验 Host 头
`web_ui_max_auth_fail_count`	5	连续失败次数阈值
`web_ui_ban_duration`	3600	封禁时长（秒）
`web_ui_session_timeout`	3600	会话超时（秒）
`banned_IPs`	空	手工封禁名单

实测闭环：

# 1) 伪造 Origin 的写请求
curl -s -b /tmp/qb.cookie -H "Origin: http://evil.example" -X POST http://localhost:8080/api/v2/app/setPreferences --data-urlencode "json={\"dl_limit\":0}" -w " HTTP:%{http_code}\n"
# 2) 未登录写请求
curl -s -X POST http://localhost:8080/api/v2/app/setPreferences --data-urlencode "json={\"dl_limit\":0}" -w " HTTP:%{http_code}\n"
# 3) 连续 5 次错密码后用正确密码登录

实测回显：

HTTP:401        ← CSRF 拦截（跨站 Origin）
HTTP:403        ← 未登录
|HTTP:403       ← 正确密码也被封禁（封禁在先）

第 3 项正文（实测原文）：

Your IP address has been banned after too many failed authentication attempts.

封禁自救：封禁名单在内存中，重启服务即清空（systemctl restart qbittorrent-nox）；长效方案是把信任网段写入 web_ui_ban_duration=0 + 反向代理层限流，或降低爆破面（改端口/上 HTTPS/收紧白名单 web_ui_address_whitelist_enabled）。

⚠️ 实测诚实记录：web_ui_host_header_validation_enabled 虽默认 true，但在本实测中携带伪造 Host: evil.example:8080 的请求未被拦截（正常返回 200）。Host 头校验对「Host 与监听地址不一致」的判定存在边界条件，公网暴露不要依赖该单项，应以反代白名单 + HTTPS + 修改默认端口为纵深防御。

8.3 反向代理要点

Web UI 默认无 base path，反代场景建议：proxy_pass http://127.0.0.1:8080/ 整根转发，并把 X-Forwarded-Proto/Host 传齐；WebUI 参数组里有 web_ui_reverse_proxy_enabled + web_ui_reverse_proxies_list 用于信任代理网段（信任后 API 的 CSRF 校验按转发头放行）。

九、生产配置模板

以下为按本文实测口径整理的服务器生产模板（速度单位 KiB/s，按 8 核 16G/千兆内网参考值调整）：

[BitTorrent]
Session\Port=6881
Session\DefaultSavePath=/srv/qbittorrent/downloads
Session\GlobalDLSpeedLimit=0
Session\GlobalUPSpeedLimit=16384
Session\UseAlternativeGlobalSpeedLimit=false
Session\AltGlobalDLSpeedLimit=10240
Session\AltGlobalUPSpeedLimit=10240
Session\QueueingSystemEnabled=true
Session\MaxActiveDownloads=3
Session\MaxActiveUploads=5
Session\MaxActiveTorrents=8
Session\DHTEnabled=true
Session\PeXEnabled=true
Session\LSDEnabled=true

[RSS]
AutoDownloader\EnableProcessing=true
Session\MaxArticlesPerFeed=100

[WebUI]
MaxAuthFailures=5
BanDuration=3600

应用流程：systemctl stop → 覆盖 conf 对应键 → systemctl start → 按 5.1/5.3/5.5 节命令逐项 API 读回验证。

十、配置文件迁移与多实例

10.1 目录结构

默认 profile（用户 HOME 内）：

/opt/qbittorrent/.config/qBittorrent/qBittorrent.conf   ← 参数
/opt/qbittorrent/.local/share/qBittorrent/BT_backup/    ← 任务状态（<infohash>.torrent + <infohash>.fastresume + queue）
/opt/qbittorrent/.local/share/qBittorrent/rss/          ← RSS 文章数据
/opt/qbittorrent/.local/share/qBittorrent/logs/         ← 日志

10.2 迁移服务器

停服务；2. 打包上述两棵目录 + 下载文件本体；3. 新机保持下载文件绝对路径一致（不一致则需逐任务 setSavePath）；4. 解包到同构路径、以同用户 systemctl start。实测确认每个任务在 BT_backup 中为 <infohash>.torrent + <infohash>.fastresume 成对存在，queue 文件记录任务顺序。

10.3 同机多实例（--profile）

第二实例启动参数 --profile=/opt/qb-seed --webui-port=8081，profile 目录实测结构：

/opt/qb-seed/qBittorrent/
├── cache/
├── data/            ← BT_backup / rss / logs
└── config/          ← qBittorrent.conf + lockfile + ipc-socket（另有 qBittorrent-data.conf）

多实例清单：各自独立 --profile、--webui-port 与 BT 端口（conf Session\Port 区分），systemd 单元各自一份；数据目录互不干扰。

十一、常见问题（排障实录）

改了 conf 不生效：先确认是否在运行中修改（见 3.2 节实测复现，会被运行态覆盖）；再确认是否有命令行参数覆盖（3.1 节优先级）。
速度限制不生效/数值对不上：核对单位口径（API B/s、conf 与 UI KiB/s）；确认当前生效档位（speedLimitsMode 0/1），备速档读的是 alt_*_limit。
分类保存路径不生效：未启 autoTMM 的任务不随分类路径（5.2 节实测），逐任务修正用 torrents/setSavePath（参数 id+path，注意与批量 hashes 参数形态不同）。
RSS 规则配了不下载：按序排查四开关——rss_auto_downloading_enabled（默认 false）→ affectedFeeds 填 URL → 文章是否已去重入库 → rss/refreshItem 手动触发（第七章实测全程）。
API 脚本登录失败：v5.x 登录成功 204/失败 401；会话 Cookie 名 QBT_SID_<端口>；连续失败 5 次触发 403 封禁（8.2 节实测文案），脚本重试逻辑必须带退避，避免把自己封掉。
createCategory 静默产生垃圾分类：v5.3.0 该端点只收独立参数（6.1 节实测），勿按旧文档传 JSON。

十二、参考链接

官方 Wiki（参数与 API 规范）：https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1+)
官方仓库源码（参数键名权威出处，src/base/bittorrent/session.cpp / src/webui/api/）：https://github.com/qbittorrent/qBittorrent
官方 FAQ（配置文件与常见行为）：https://github.com/qbittorrent/qBittorrent/wiki#frequently-asked-questions
本专栏选型篇：《qBittorrent 5.3.0 介绍与选型指南》（https://www.quzuo.net/document/9druyGP9Dj7s）
本专栏部署篇：《Ubuntu 22.04 安装 qBittorrent 5.3.0 指南》（https://www.quzuo.net/document/YAUO2LGURZtH）
本专栏命令篇：《qBittorrent 5.3.0 常用 CLI 命令详解》

qBittorrent 5.3.0 配置参数详解

qBittorrent 5.3.0 配置参数详解

一、环境信息

二、前置条件

三、参数的查看与修改通道

3.1 通道优先级

3.2 安全修改流程（实测对照）

四、当前配置文件全貌

五、BitTorrent 会话参数

5.1 BT 监听端口 Session\Port

5.2 默认保存路径 Session\DefaultSavePath

5.3 全局限速 Session\GlobalDLSpeedLimit / GlobalUPSpeedLimit

5.4 备速模式（Alt Speed）Session\UseAlternativeGlobalSpeedLimit

5.5 任务队列 Session\QueueingSystemEnabled 等

5.6 DHT / PeX / LSD 会话开关

六、分类与标签参数

6.1 创建分类（实测）

6.2 标签实测

七、RSS 参数

八、Web UI 参数

8.1 端口/账号/密码

8.2 安全参数（全部默认值实测读回）

8.3 反向代理要点

九、生产配置模板

十、配置文件迁移与多实例

10.1 目录结构

10.2 迁移服务器

10.3 同机多实例（--profile）

十一、常见问题（排障实录）

十二、参考链接

5.1 BT 监听端口 `Session\Port`

5.2 默认保存路径 `Session\DefaultSavePath`

5.3 全局限速 `Session\GlobalDLSpeedLimit` / `GlobalUPSpeedLimit`

5.4 备速模式（Alt Speed）`Session\UseAlternativeGlobalSpeedLimit`

5.5 任务队列 `Session\QueueingSystemEnabled` 等