📖 前言

qBittorrent 是一款开源、轻量级的 BitTorrent 客户端，具有以下特点：

  • 🆓 完全免费 - 无广告、无捆绑软件
  • 🌐 Web 界面 - 远程管理方便
  • 🎯 功能强大 - 支持 BT/PT、RSS 订阅
  • 🔍 内置搜索 - 多个 BT 站点搜索
  • 📊 速度控制 - 上传/下载限速
  • ⚡ 资源占用低 - 适合 NAS 和服务器

本文将详细介绍如何使用 Docker 部署 qBittorrent，实现 7x24 小时稳定下载。

💡 为什么选择 qBittorrent？

qBittorrent vs 其他下载器

特性 qBittorrent Transmission Deluge μTorrent
开源 ✅ 开源 ✅ 开源 ✅ 开源 ❌ 闭源
广告 ✅ 无广告 ✅ 无广告 ✅ 无广告 ❌ 有广告
Web UI ✅ 内置 ✅ 内置 ⚠️ 需插件 ⚠️ 简陋
PT 支持 ✅ 优秀 ✅ 良好 ✅ 良好 ⚠️ 一般
RSS 订阅 ✅ 支持 ❌ 不支持 ✅ 支持 ✅ 支持
搜索引擎 ✅ 内置 ❌ 不支持 ❌ 不支持 ❌ 不支持

qBittorrent 优势

✅ 跨平台支持 - Windows / Linux / macOS
✅ 轻量高效 - 资源占用低
✅ PT 友好 - 完美支持私有 Tracker
✅ 自动化 - RSS 订阅、自动分类
✅ 活跃社区 - 持续更新维护
✅ 中文支持 - 完善的中文界面

📦 准备工作

1. 环境要求

  • ✅ Docker 已安装（版本 20.10+）
  • ✅ Docker Compose 已安装（版本 2.0+）
  • ✅ 足够的存储空间（建议 500GB+）
  • ✅ 稳定的网络连接

2. 端口说明

端口 用途 说明
6800 Web UI Web 管理界面
6801 传入连接 BT/PT 监听端口

⚠️ 端口 6801 需要在路由器做端口映射，以获得更好的下载速度

3. 目录规划

1
2
3
4
5
6
7
8
9
10
11
/vol1/1000/docker/qbittorrent/  # 配置目录
├── qBittorrent/
│   └── config/                 # 配置文件
└── logs/                       # 日志文件

/vol2/1000/media/              # 下载目录
├── downloads/                 # 下载文件
│   ├── movies/               # 电影
│   ├── tv/                   # 电视剧
│   └── other/                # 其他
└── completed/                # 完成的种子

4. 创建目录

1
2
3
4
5
6
7
8
9
10
# 创建配置目录
mkdir -p /vol1/1000/docker/qbittorrent

# 创建下载目录
mkdir -p /vol2/1000/media/downloads/{movies,tv,other}
mkdir -p /vol2/1000/media/completed

# 设置权限
chmod -R 755 /vol1/1000/docker/qbittorrent
chmod -R 755 /vol2/1000/media

🚀 部署步骤

Step 1: 创建 Docker Compose 文件

创建配置文件：

1
2
cd /vol1/1000/docker/qbittorrent
nano docker-compose.yml

Step 2: 粘贴配置

将以下配置粘贴到文件中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
services:
  qbittorrent:
    image: linuxserver/qbittorrent
    container_name: qbittorrent
    environment:
      - PUID=0       # 你服务器的用户ID
      - PGID=0       # 你服务器的组ID
      - TZ=Asia/Shanghai
      - WEBUI_PORT=6800
    volumes:
      - /vol1/1000/docker/qbittorrent:/config
      - /vol2/1000/media:/downloads
    ports:
      - 6800:6800       # Web UI 端口
      - 6801:6801       # Web UI 端口
    restart: always

保存文件（Ctrl+O，Enter，Ctrl+X）。

Step 3: 启动容器

1
2
3
4
5
6
7
8
# 拉取镜像
docker-compose pull

# 启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f qbittorrent

Step 4: 获取初始密码

qBittorrent 首次启动会生成临时密码：

1
2
3
4
5
# 查看日志获取密码
docker-compose logs qbittorrent | grep "temporary password"

# 或查看配置文件
docker exec qbittorrent cat /config/qBittorrent/qBittorrent.conf | grep WebUI

输出示例：

1
2
******** The WebUI administrator username is: admin
******** The WebUI administrator password was not set. A temporary password is provided for this session: Ab1234Cd

Step 5: 访问 Web 界面

浏览器访问：

1
http://服务器IP:6800

登录信息：

  • 用户名: admin
  • 密码: 日志中的临时密码

⚠️ 首次登录后请立即修改密码！

📖 配置详解

环境变量说明

变量 说明 默认值
PUID 运行用户 UID 0 (root)
PGID 运行用户 GID 0 (root)
TZ 时区设置 Asia/Shanghai
WEBUI_PORT Web UI 端口 6800

获取 PUID 和 PGID

1
2
3
4
5
# 查看当前用户的 UID 和 GID
id

# 输出示例
uid=1000(user) gid=1000(user)

建议使用普通用户运行：

1
2
3
environment:
  - PUID=1000
  - PGID=1000

目录挂载

容器路径 宿主机路径 用途
/config /vol1/1000/docker/qbittorrent 配置文件
/downloads /vol2/1000/media 下载目录

端口映射

1
2
3
ports:
  - 6800:6800  # Web UI 访问端口
  - 6801:6801  # BT/PT 监听端口

端口映射说明：

  • 6800 - Web 管理界面（可改为其他端口）
  • 6801 - 传入连接端口（建议在路由器做端口映射）

⚙️ 初始配置

1. 修改密码

登录后立即修改密码：

工具 > 选项 > Web UI > 身份验证

1
2
用户名: admin
密码: ******** （设置强密码）

点击 保存 应用更改。

2. 下载设置

下载 选项卡：

1
2
3
默认保存路径: /downloads
保持未完成的种子在: /downloads/incomplete
监视文件夹: /downloads/watch

自动管理：

  • ✅ 种子完成时自动移动
  • ✅ 排除种子和用户的文件名
  • 保存路径: /downloads/completed

3. 连接设置

连接 选项卡：

1
2
3
4
监听端口: 6801
使用 UPnP / NAT-PMP: ✅ 启用
传入连接最大连接数: 500
全局最大连接数: 1000

代理服务器：（如需使用）

1
2
3
类型: SOCKS5
主机: 代理地址
端口: 代理端口

4. 速度限制

速度 选项卡：

1
2
3
全局上传速度限制: 0 (无限制)
全局下载速度限制: 0 (无限制)
备用速度限制: 可选设置

计划任务：

  • 设置特定时间段的速度限制
  • 适合避开高峰时段

5. BitTorrent 设置

BitTorrent 选项卡：

隐私：

  • ✅ 启用 DHT
  • ✅ 启用 PeX
  • ✅ 启用本地 Peer 发现
  • ⚠️ PT 下载时需关闭 DHT 和 PeX

做种限制：

1
2
当分享率达到: 2.0 时暂停种子
当做种时间达到: 0 分钟 (不限制)

6. Web UI 设置

Web UI 选项卡：

1
2
3
4
语言: 简体中文
IP 地址: * (所有地址)
端口: 6800
启用 HTTPS: ❌ (可选，需要证书)

安全：

  • ✅ 启用跨站请求伪造 (CSRF) 保护
  • ✅ 启用 Host header 验证
  • ⚠️ 绕过本地主机验证（本地访问建议启用）

🎯 高级功能

1. RSS 自动下载

RSS > 新建订阅

1
2
URL: https://example.com/rss.xml
名称: 自定义名称

下载规则：

1
2
3
4
必须包含: 关键词1|关键词2
不能包含: 广告|垃圾
集数过滤: 1-12
保存到: /downloads/tv/剧集名称

2. 分类管理

右键侧边栏 > 添加分类

1
2
分类名称: 电影
保存路径: /downloads/movies

创建常用分类：

  • 电影 → /downloads/movies
  • 电视剧 → /downloads/tv
  • 动漫 → /downloads/anime
  • 音乐 → /downloads/music

3. 搜索插件

搜索 > 搜索插件

安装搜索插件：

  1. 点击 搜索插件
  2. 点击 检查更新
  3. 选择需要的站点插件
  4. 点击 安装

推荐插件：

  • The Pirate Bay
  • 1337x
  • RARBG
  • Nyaa（动漫）

4. 标签管理

为种子添加标签，便于管理：

1
2
3
电影 → 标签: movie
电视剧 → 标签: tv
PT → 标签: pt

5. Tracker 管理

添加公共 Tracker 提升速度：

选项 > BitTorrent > 自动添加以下 Tracker

1
https://trackerslist.com/best.txt

定期更新 Tracker 列表。

🔧 常用操作

查看日志

1
2
3
4
5
6
7
8
# 实时日志
docker-compose logs -f qbittorrent

# 最近 100 行
docker-compose logs --tail 100 qbittorrent

# 容器内日志
docker exec qbittorrent cat /config/qBittorrent/logs/qbittorrent.log

重启服务

1
2
3
4
5
# 重启容器
docker-compose restart

# 或在 Web 界面
文件 > 退出 qBittorrent

然后重新启动容器。

更新版本

1
2
3
4
5
6
7
8
# 拉取最新镜像
docker-compose pull

# 重新创建容器
docker-compose up -d

# 清理旧镜像
docker image prune -f

备份配置

1
2
3
4
5
# 备份配置目录
tar -czf qbittorrent-backup-$(date +%Y%m%d).tar.gz /vol1/1000/docker/qbittorrent

# 恢复配置
tar -xzf qbittorrent-backup-20251116.tar.gz -C /

导入种子

方式一：Web 界面上传

  • 点击 添加种子
  • 选择种子文件

方式二：监视文件夹

1
2
# 复制种子到监视文件夹
cp /path/to/torrent.torrent /vol2/1000/media/watch/

qBittorrent 会自动加载并开始下载。

🚨 常见问题

Q1: 无法访问 Web 界面？

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 检查容器状态
docker ps | grep qbittorrent

# 2. 检查端口
netstat -tulpn | grep 6800

# 3. 查看日志
docker-compose logs qbittorrent

# 4. 检查防火墙
firewall-cmd --zone=public --add-port=6800/tcp --permanent
firewall-cmd --reload

Q2: 下载速度慢？

优化建议：

  1. 端口映射 - 在路由器映射 6801 端口
  2. 添加 Tracker - 使用公共 Tracker 列表
  3. 调整连接数 - 增加最大连接数
  4. 关闭限速 - 取消速度限制
  5. 检查网络 - 确保网络稳定

Q3: 权限问题？

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 检查目录权限
ls -la /vol1/1000/docker/qbittorrent
ls -la /vol2/1000/media

# 2. 修改权限
chown -R 1000:1000 /vol1/1000/docker/qbittorrent
chown -R 1000:1000 /vol2/1000/media

# 3. 修改 PUID 和 PGID
environment:
  - PUID=1000
  - PGID=1000

Q4: PT 下载无法保种？

检查设置：

  1. 关闭 DHT 和 PeX
  2. 禁用 “种子完成时自动移动”
  3. 设置合适的分享率限制
  4. 确保上传速度不限制

Q5: 忘记密码？

重置密码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 停止容器
docker-compose down

# 2. 编辑配置文件
nano /vol1/1000/docker/qbittorrent/qBittorrent/config/qBittorrent.conf

# 3. 删除或注释密码行
# WebUI\Password_PBKDF2=...

# 4. 重启容器
docker-compose up -d

# 5. 查看新的临时密码
docker-compose logs qbittorrent | grep password

⚡ 性能优化

1. 磁盘缓存

高级 > libtorrent 设置

1
2
磁盘缓存: 512 MB
磁盘缓存过期间隔: 60 秒

2. 资源限制

1
2
3
4
5
6
7
8
9
services:
  qbittorrent:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 512M

3. 异步 I/O

启用异步 I/O 提升性能：

高级 > libtorrent 设置

1
✅ 使用异步 I/O

4. 文件系统优化

使用 SSD 存储临时文件：

1
2
volumes:
  - /ssd/qbittorrent/temp:/downloads/incomplete

🔐 安全建议

1. 修改默认端口

1
2
ports:
  - 8888:6800  # 修改为其他端口

2. 启用 HTTPS

Web UI > 启用 HTTPS

需要准备证书文件：

1
2
/config/qBittorrent/server.key
/config/qBittorrent/server.crt

3. IP 白名单

Web UI > 身份验证 > 绕过来自白名单 IP 地址的客户端的身份验证

1
192.168.1.0/24

4. 反向代理

使用 Nginx 配置反向代理：

1
2
3
4
5
6
7
8
9
10
server {
    listen 443 ssl;
    server_name qb.yourdomain.com;
    
    location / {
        proxy_pass http://127.0.0.1:6800;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

5. 定期备份

1
2
3
4
5
# 添加定时任务
crontab -e

# 每天凌晨 4 点备份
0 4 * * * tar -czf /backup/qbt-$(date +\%Y\%m\%d).tar.gz /vol1/1000/docker/qbittorrent

📊 最佳实践

1. 目录结构

1
2
3
4
5
6
7
8
9
/vol1/1000/docker/qbittorrent/  # SSD - 配置
/vol2/1000/media/               # HDD - 数据
├── downloads/                  # 下载中
│   ├── incomplete/            # 未完成
│   ├── movies/                # 电影
│   ├── tv/                    # 电视剧
│   └── anime/                 # 动漫
├── completed/                  # 已完成
└── watch/                      # 监视文件夹

2. 配合 MoviePilot

qBittorrent + MoviePilot 完美组合：

  1. qBittorrent 负责下载
  2. MoviePilot 负责订阅和整理
  3. Emby 负责媒体管理

3. PT 站点设置

私有 Tracker 设置：

1
2
3
4
禁用 DHT: ✅
禁用 PeX: ✅
启用超级做种: ✅
分享率: 根据站点要求

4. 自动化管理

下载完成脚本：

1
2
3
4
#!/bin/bash
# 下载完成后执行
torrent_path="$1"
# 执行自定义操作

配置路径：

1
下载 > 种子完成时运行外部程序

📈 监控与统计

查看统计信息

工具 > 统计

  • 总下载量
  • 总上传量
  • 分享率
  • 活动时间

速度曲线

Web UI 底部显示：

  • 实时下载速度
  • 实时上传速度
  • 连接数

磁盘空间

定期检查磁盘空间：

1
2
3
4
5
# 查看磁盘使用情况
df -h /vol2/1000/media

# 查看目录大小
du -sh /vol2/1000/media/*

🎉 总结

通过本教程，你已经成功部署了 qBittorrent，实现了：

✅ Web 远程管理 - 随时随地控制下载
✅ 自动化下载 - RSS 订阅、自动分类
✅ 稳定运行 - Docker 容器化部署
✅ PT 友好 - 完美支持私有 Tracker
✅ 高效管理 - 分类、标签、搜索

下一步

  • 📝 配置 RSS 自动订阅
  • 🎬 结合 MoviePilot 自动整理
  • 📊 安装搜索插件
  • 🔔 配置下载完成通知
  • 🌐 设置远程访问

🔗 相关链接

📝 更新日志

  • 2025-11-16 - 初始版本发布

祝你下载愉快！如有问题欢迎在评论区讨论。