📥 qBittorrent Docker部署教程 | 开源下载服务完整指南
qBittorrent 是一款跨平台的开源 BitTorrent 客户端，界面简洁、功能强大，并支持 Web UI 管理，非常适合在服务器上长期运行。与传统客户端相比，它不仅轻量，而且内置广告拦截功能，使下载体验更加纯净。通过 Docker Compose 部署，你可以轻松实现远程下载和集中管理，无需在本地电脑长时间运行客户端。无论是家庭服务器、NAS 还是 VPS，通过 qBittorrent 都能实现自动化、远程化的下载管理，同时方便在局域网或互联网上进行访问。
通过 Docker 部署 qBittorrent 的最大优势是环境独立、配置统一、易于迁移。即使更换服务器，只需迁移 /opt/docker-stack/qbittorrent/ 目录，就能保证配置和下载任务不丢失。这种方式可以与反向代理（如 Caddy 或 Nginx）结合，提供统一的 HTTPS 访问，从而保证 Web UI 的访问安全。合理配置端口映射和文件权限，可以确保下载文件安全，同时方便多用户共享和管理。
📂 目录结构规划
为了便于管理和备份，建议将 qBittorrent 放在 /opt/docker-stack/qbittorrent/ 目录下。典型目录结构如下：
/opt/docker-stack/qbittorrent/
├─ compose.yaml # Docker Compose 配置文件
└─ data/ # 存放环境变量和文档
├─ .env # 环境变量文件
└─ README.md # 部署文档说明
data/ 文件夹用于存放环境变量和 README 文档，同时还可以保存下载记录和配置文件。清晰的目录结构方便后续管理、迁移和备份，也方便团队协作和自动化脚本管理。
⚙️ 环境变量配置（data/.env）
在 .env 文件中可以自定义 BT 下载端口、Web UI 管理端口以及下载文件保存目录：
QBITTORRENT_PORT=8081 QBITTORRENT_WEBUI_PORT=8080 QBITTORRENT_DOWNLOAD_DIR=/opt/docker-stack/qbittorrent/downloads
使用 .env 文件有助于集中管理配置，当需要修改端口或下载目录时，只需修改 .env 文件而无需触碰 Docker Compose 配置文件。这种方式降低人为错误风险，提高系统维护的便捷性。
🐳 Docker Compose 配置（compose.yaml）
下面是一个完整示例，使用 LinuxServer 官方 qBittorrent 镜像，并配置了端口、挂载目录和 Docker 网络：
name: qbittorrent
networks:
web_net:
external: true
services:
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
restart: unless-stopped
env_file:
- ./data/.env
environment:
PUID: 1000
PGID: 1000
TZ: Asia/Shanghai
WEBUI_PORT: ${QBITTORRENT_WEBUI_PORT}
volumes:
- ./data:/config
- ${QBITTORRENT_DOWNLOAD_DIR}:/downloads
ports:
- "${QBITTORRENT_PORT}:6881"
- "${QBITTORRENT_PORT}:6881/udp"
- "${QBITTORRENT_WEBUI_PORT}:8080"
networks:
- web_net
通过该配置，容器内的配置文件和下载目录会挂载到宿主机指定路径，保证配置和下载数据的持久化。重启策略 unless-stopped 能在容器异常停止时自动恢复，提高服务稳定性。端口映射保证容器内 BT 服务和 Web UI 可以被正常访问，同时支持反代和 HTTPS 加密。
🔑 Service Name vs Container Name
- Service Name (qbittorrent)
Service name 用于容器间互通。例如其他容器（Caddy、Nginx 或自动化脚本）可以通过qbittorrent:8080访问 Web UI。在反代配置或容器间调用时使用 service name，可以保证网络内 DNS 解析稳定。 - Container Name (qbittorrent)
Container name 用于宿主机管理，例如通过docker ps查看容器状态，或者使用docker logs qbittorrent查看日志。container name 不建议用于跨容器访问，以避免 DNS 或网络隔离问题。
📑 README.md（data/目录示例）
# qBittorrent 部署文档
## 目录结构
/opt/docker-stack/qbittorrent/
├─ compose.yaml
└─ data/
├─ .env
└─ README.md
## 环境变量 (.env)
- `QBITTORRENT_PORT`：BT 下载端口（默认 8081）
- `QBITTORRENT_WEBUI_PORT`：Web UI 管理端口（默认 8080）
- `QBITTORRENT_DOWNLOAD_DIR`：下载文件保存目录
## 网络配置
- 使用自定义网络 `web_net`，需提前创建：
```bash
docker network create web_net
```
可与其他容器互通，如 Caddy 或 Nginx：
```text
qbittorrent.example.xyz {
reverse_proxy qbittorrent:8080
}
```
## 启动与停止
```bash
cd /opt/docker-stack/qbittorrent
docker compose up -d
docker compose down
docker compose restart
```
## 升级与回滚
升级：
```bash
docker compose pull && docker compose up -d
```
回滚：修改镜像标签为上一个版本或 digest，然后：
```bash
docker compose up -d
```
## 验证
浏览器访问 `http://服务器IP:8080` → 打开 Web UI
默认用户名：admin
默认密码：adminadmin（首次登录后请修改）
## 注意事项
- 确保 PUID 和 PGID 正确，否则下载文件可能无法访问
- 建议通过反代启用 HTTPS，保证 Web UI 安全
- Service name 用于容器间互通，Container name 用于宿主机管理
- 下载目录建议使用独立磁盘分区，提高数据安全性
- 结合 RSS 自动下载和限速功能，可以实现长期无人值守下载
🚀 总结
qBittorrent 是一款轻量、开源且跨平台的 BT 下载客户端。通过 Docker Compose 部署，你可以实现远程管理、自动化下载，并可结合反向代理提供 HTTPS 访问。通过 Web UI，可以直接管理下载任务，包括添加种子、设置限速、启用 RSS 自动下载等功能。文章详细介绍了目录结构、环境变量配置、Docker Compose 设置以及 Service Name 和 Container Name 的区别，为部署和运维提供完整指南。
引用：
https://docs.linuxserver.io/images/docker-qbittorrent/#version-tags