qBittorrent：开源全平台 BitTorrent 客户端完全指南

目标读者：有网络基础、了解 P2P 概念，想搭建私有种子下载环境的开发者或高级用户 前置知识：命令行基础；Docker 或 CMake 二选一（按安装路线） GitHub：https://github.com/qbittorrent/qBittorrent | Stars：约 39.6K 当前版本：5.2.x（撰写时最新 5.2.3）

读完本文你能

• 在桌面（Linux / Windows / macOS）或服务器上装好 qBittorrent，并验证它正常运行
• 用 Docker 或 qbittorrent-nox 搭一个无图形界面的下载服务器，开机自启、远程管理
• 配置搜索、RSS 自动下载、限速与分享率、IP 过滤、代理与加密
• 弄清 Web UI 首次登录的临时密码机制，以及忘记密码后的恢复流程
• 对下载服务器做基本加固：改密码、反向代理 + HTTPS、绑定 VPN 防泄漏

一句话定义

qBittorrent 是一款开源、跨平台、无广告的 BitTorrent 客户端，用 C++ / Qt 编写，下载引擎是 Arvid Norberg 的 libtorrent（libtorrent-rasterbar）。它在功能上对标 uTorrent，但代码完全开放，没有捆绑广告与挖矿行为。

为什么值得了解

BitTorrent 仍是分发大文件最有效的去中心化协议之一，而开源生态里能同时做到下面几点的客户端不多：

• 从 2006 年发布至今维护约 20 年，GitHub 上约 39.6K Star、4.8K Fork，社区活跃
• 功能完整：内置搜索、RSS 自动下载、分类标签、限速调度、IP 过滤、加密传输
• 跨平台：Linux、Windows、macOS、FreeBSD 均有构建；macOS 版由社区维护，官方坦言支持力度有限
• 两种运行形态：桌面 GUI（qbittorrent）与无界面守护进程（qbittorrent-nox），后者适合 NAS 与服务器
• 许可证为 GPLv2+（部分文件为 GPLv3），可审计、可自由修改

核心架构

qBittorrent 本身是 libtorrent 的图形化包装，不修改协议层。分层关系：

应用层  qBittorrent（C++/Qt）—— 桌面 GUI 或 Web UI
          │ 界面、RSS、搜索、限速、分类等业务逻辑
引擎层  libtorrent-rasterbar —— 对等连接、Piece 选择、DHT、Tracker 通信
          │
依赖层  Boost ≥ 1.76 | OpenSSL ≥ 3.0.2 | Qt 6.6+
        zlib ≥ 1.2.11 | CMake ≥ 3.16（仅编译期）
        Python ≥ 3.13（仅搜索插件，运行时）

libtorrent 负责 BitTorrent 协议的全部底层细节；qBittorrent 在它之上提供界面、Web UI、RSS 与搜索。5.x 系列起 Qt6 成为唯一支持的图形框架，同时移除了 Qt5、qmake 与 32 位 Windows 的支持。

安装

路线一：桌面（发行版官方包或官方 PPA）

Debian / Ubuntu 优先用官方 PPA 获取最新稳定版：

sudo add-apt-repository ppa:qbittorrent-team/qbittorrent-stable
sudo apt update
sudo apt install qbittorrent        # 桌面版
# 或只装无界面版
sudo apt install qbittorrent-nox    # 无图形界面，仅 Web UI

Arch 系直接 sudo pacman -S qbittorrent（或 qbittorrent-nox）。Windows 与 macOS 从官网下载页拿安装包；macOS 构建由社区维护，版本与质量波动较大。

路线二：服务器（Docker，官方镜像）

官方提供无界面镜像 qbittorrentofficial/qbittorrent-nox：

docker run -d \
  --name qbittorrent \
  -e QBT_LEGAL_NOTICE=confirm \
  -e QBT_WEBUI_PORT=8080 \
  -e QBT_TORRENTING_PORT=6881 \
  -p 8080:8080 \
  -p 6881:6881 -p 6881:6881/udp \
  -v /data/qbittorrent/config:/config \
  -v /data/qbittorrent/downloads:/downloads \
  qbittorrentofficial/qbittorrent-nox

• QBT_LEGAL_NOTICE=confirm 是官方镜像的必填项，表示已阅读并接受法律声明
• QBT_WEBUI_PORT 与 QBT_TORRENTING_PORT 分别控制 Web UI 与传输端口，默认 8080 / 6881
• 配置与下载目录分别挂载，升级容器不丢数据

社区常用的 linuxserver/qbittorrent 镜像同样可用，二者选一即可。

路线三：从源码编译（进阶）

发行版包过旧、又不想用 Docker 时才值得自己编译。依赖要求以官方 INSTALL 为准：

Ubuntu / Debian 上的编译流程（包名以你的发行版为准）：

# 1. 安装依赖
sudo apt install build-essential cmake qt6-base-dev libqt6svg6-dev \
    libtorrent-rasterbar-dev libboost-dev libssl-dev zlib1g-dev python3

# 2. 编译并安装（带 GUI）
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cmake --install build

# 3. 编译无 GUI 版本（服务器场景）
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGUI=OFF
cmake --build build
sudo cmake --install build

两个构建产物分别是 qbittorrent（GUI）与 qbittorrent-nox（无界面）。

验证安装

qbittorrent-nox --version    # 应输出类似 qBittorrent 5.2.3

GUI 版首次启动会弹出法律声明与配置向导；nox 版在终端接受声明后即可通过 Web UI 使用。装好后加一个测试种子（比如 Ubuntu 官方镜像种子），能下载到文件即算验证通过。

Web UI 首次登录

Web UI 默认监听 http://<主机>:8080，用户名固定为 admin，密码规则随版本变化：

• v4.6.1 及以上：首次启动不设固定密码，而是在启动日志里打印一次性临时密码，形如 The WebUI administrator password was not set. A temporary password is provided for this session: PBNZSfyPm 用 admin + 该临时密码登录后，到「选项 → Web UI → 认证」里改成自己的密码
• v4.6.1 以下：默认密码为 adminadmin

以 systemd 运行无界面版时，临时密码在 journalctl -u qbittorrent-nox 的日志里。无论哪种方式，首次登录后立刻改密，这是最重要的安全动作。

核心功能

种子搜索

内置搜索插件系统，入口在「工具 → 搜索引擎」。搜索由 Python 解释器执行，因此系统必须装有 Python（版本要求见上文依赖表）。插件以 .py 文件存放，可在搜索引擎界面打开插件文件夹管理或增删索引站。

RSS 订阅

「工具 → RSS 阅读器」可订阅 RSS 2.0 源并设置自动下载规则：按关键词、正则或智能剧集过滤（Smart Episode Filter）匹配新条目，命中即自动加入下载队列。订阅列表与规则保存在 Linux 的 ~/.config/qBittorrent/rss/ 下。

分类与标签

用分类（Category）把不同来源的种子分流到不同保存目录，比如「电影」「软件」「剧集」，配合自动管理模式（Automatic Torrent Management）在类别目录间自动整理。标签（Tag）是跨分类的轻量标记，适合做「待清理」「保种」这类横切标注。

下载策略

• 限速：全局与单个种子的上传 / 下载速度上限
• 队列：同时活动的任务数上限、种子优先级
• 分享率 / 保种时间：达到设定分享率或保种时长后自动停做种；v5.2 起可按分类分别设置
• 带宽调度：按时间段设定限速规则，避开上网高峰
• 顺序下载：按文件顺序取 Piece，边下边看视频时可用

IP 过滤

「选项 → 高级 → IP 过滤」支持 eMule / PeerGuardian 格式的 DAT 黑名单，可屏蔽已知恶意或长期占带宽的节点。列表需手动维护，可配合第三方规则更新。

创建种子

「工具 → 制作 Torrent」可从本地文件生成 .torrent，并支持标记为私有种子（private），配合自己的 Tracker 使用。

无界面服务器：qbittorrent-nox

服务器 / NAS 上推荐用 qbittorrent-nox，通过 Web UI 管理。

首次运行

qbittorrent-nox    # 接受法律声明后，打印 Web UI 地址与临时密码

systemd 常驻

官方包通常会安装 qbittorrent-nox@.service 模板，以指定用户运行并开机自启：

sudo systemctl enable --now qbittorrent-nox@qbittorrent
journalctl -u qbittorrent-nox@qbittorrent -f    # 查看日志，含临时密码

需要改监听端口或配置目录时，追加命令行参数：

qbittorrent-nox --webui-port=8081 --configuration=/data/qbittorrent/config

远程管理与 API

Web UI 之外，qBittorrent 还提供 HTTP API（/api/v2/）：登录、添加种子、查状态、控制限速都能走接口。它是各类下载管理脚本与第三方遥控 App 的基础，接口细节见项目 Wiki 的 WebUI API 页面。

高级配置

端口与 UPnP

BitTorrent 需要开放监听端口（默认 TCP + UDP 6881）：

家用路由器可用 UPnP / NAT-PMP 自动映射端口，映射失败或连接性差时再改手动端口转发，并在「选项 → 连接 → 测试端口」验证。

加密与隐私

• 强制加密：「选项 → BitTorrent → 加密」设为 Require（强制），只与加密对等方通信，可降低被运营商限流的概率，但可用节点会变少
• 代理：支持 SOCKS5 / HTTP 代理，把下载流量走代理出口
• 绑定网卡防泄漏：在「选项 → 高级 → 网络接口」选择 VPN / WireGuard 虚拟网卡，物理网卡断线时 qBittorrent 不会用真实 IP 直连。这是下载服务器最重要的隐私设置
• 匿名模式（Anonymous Mode）：对 Tracker 与 Peer 隐藏客户端指纹，但会禁用 HTTP Tracker 的部分功能

数据与备份

下载进度与种子状态存放在 BT_backup 目录下的 .torrent 与 .fastresume 文件里：

• Linux：~/.local/share/data/qBittorrent/BT_backup/
• Windows：%LOCALAPPDATA%\qBittorrent\BT_backup\
• macOS：~/Library/Application Support/qBittorrent/BT_backup/

.fastresume 由进程在内存维护、退出时写回。用 kill -9 强杀会丢失最近进度，重启后需要重新校验。备份时先正常退出 qBittorrent，再整体复制 BT_backup 与 qBittorrent.conf，即可完整迁移。

忘记 Web UI 密码

官方恢复流程，不需要任何命令行参数：

1. 停止 qbittorrent 进程
2. 编辑 ~/.config/qBittorrent/qBittorrent.conf
3. 删除以 WebUI\Password_PBKDF2 开头的那一行
4. 保存并重启：v4.6.1+ 会打印新的临时密码，旧版本回到默认 adminadmin
5. 登录后立即重设密码

安全加固

1. 首次登录后立刻修改默认凭据，不要用临时密码长期运行
2. Web UI 不要直接暴露公网。用 Caddy / Nginx 做反向代理并启用 HTTPS；qBittorrent 侧「选项 → Web UI → 启用 HTTPS」也可以，但反向代理更省事
3. 保持默认的 CSRF 与 Host Header 校验开启；只有必须用 IP 直连访问时才考虑关闭这两项
4. 只从官网与 GitHub Releases 下载安装包。所有产物均带 GPG 签名，公钥为 4096R/5B7CC9A2（指纹 D8F3DA77AAC6741053599C136E4A2D025B7CC9A2），可从仓库根目录的 5B7CC9A2.asc 获取
5. 下载与做种目录分离，避免把做种文件堆在系统盘

与替代方案对比

常见问题排查

下载一直「连接中」、没有速度

• 检查传输端口是否可达：路由器是否做了端口转发、防火墙是否放行，用「选项 → 连接 → 测试端口」验证
• 检查 Tracker 状态：DHT 与 PeX 是否启用，Tracker 是否被墙
• 强制加密开启时会筛掉不少节点，可临时改回「允许」对比观察

Web UI 打不开

• 确认监听端口与防火墙放行（如 sudo ufw allow 8080）
• 确认「选项 → Web UI → 启用 Web 用户界面」已勾选
• 登录返回 401：密码错误或临时密码已失效，按上文「忘记 Web UI 密码」处理

速度被限得很低

• 检查是否启用了带宽调度器且正处于限速时段
• 检查全局上传限速——上传被限死会拖累下载（BitTorrent 的速率反馈机制）

维护指引

• 配置主文件：Linux 为 ~/.config/qBittorrent/qBittorrent.conf，Windows 在 %APPDATA%\qBittorrent\ 下
• 迁移 / 备份：先退出进程，再整体复制 BT_backup/ 与 qBittorrent.conf
• 升级：Docker 方式换镜像 tag；apt 方式保持 PPA 更新即可；源码方式重新编译
• 关注安全公告：项目在 GitHub Issues 与官网新闻页发布，涉及 Web UI 的 CVE 出现时及时升级

总结

qBittorrent 用约 20 年的持续维护换来了开源 BitTorrent 客户端里最完整的体验：桌面与无界面两种形态、内置搜索与 RSS 自动下载、加密与代理等隐私手段齐全。多数场景下 apt / PPA 或官方 Docker 镜像就够用，源码编译只在需要定制构建时才值得。部署后先改密码，再考虑反向代理与绑定 VPN，一个可靠的下载服务器就成型了。

延伸工具

• rTorrent — 更轻量的 CLI 选择
• libtorrent — 自行开发 torrent 应用时的底层库
• Jackett — 统一多索引站搜索
• qBittorrent Wiki — WebUI API 与运维细节