前言
在 NAS 或 Linux 服务器上部署一个稳定、可管理的 BT 下载工具是很多人的刚需。本文将介绍如何使用 Docker Compose 快速部署一个基于镜像 superng6/qbittorrentee 的 qBittorrent 容器服务。
本教程适用于 Ubuntu / Debian / 群晖 / OpenMediaVault 等支持 Docker 的系统。
一、环境准备
1️⃣ 安装 Docker
如果你的系统尚未安装 Docker，可参考官方文档安装：
- 官网： https://www.docker.com/ Ubuntu 示例：
sudo apt update
sudo apt install docker.io -y
sudo systemctl enable docker
sudo systemctl start docker
2️⃣ 安装 Docker Compose
新版 Docker 已自带 compose 插件，可通过以下命令确认：
docker compose version
如果没有，可安装：
sudo apt install docker-compose-plugin -y
二、创建项目目录
建议为 qBittorrent 创建独立目录：
mkdir -p ~/docker/qbittorrentee
cd ~/docker/qbittorrentee
三、编写 docker-compose.yml 文件
在当前目录创建文件：
nano docker-compose.yml
写入以下内容：
version: "3"
services:
qbittorrentee:
image: superng6/qbittorrentee
container_name: qbittorrentee
environment:
- PUID=1026
- PGID=100
- TZ=Asia/Shanghai
- WEBUIPORT=8080
- ENABLE_DOWNLOADS_PERM_FIX=true
volumes:
- ./qbittorrentee/config:/config
- ./qbittorrentee/downloads:/downloads
ports:
- 6881:6881
- 6881:6881/udp
- 8080:8080
restart: unless-stopped
保存并退出。
四、参数说明
🔹 镜像说明
superng6/qbittorrentee 是一个封装好的 qBittorrent WebUI 版本镜像。
🔹 关键环境变量说明
| 端口 | 用途 |
| 6881 TCP | BT 下载 |
| 6881 UDP | DHT 网络 |
| 8080 | Web 管理界面 |
🔹 数据目录说明
| 宿主机路径 | 容器路径 | 作用 |
| ./qbittorrentee/config | /config | 配置文件 |
| ./qbittorrentee/downloads | /downloads | 下载目录 |
建议确保目录权限正确：
mkdir -p qbittorrentee/config
mkdir -p qbittorrentee/downloads
chmod -R 775 qbittorrentee
五、启动服务
在 docker-compose.yml 所在目录执行：
docker compose up -d
查看运行状态：
docker ps
六、访问 Web 管理界面
浏览器访问：
http://服务器IP:8080
默认用户名：admin
默认密码为随机生成，首次启动容器请查看日志。
七、常用管理命令
查看日志
docker compose logs -f
重启服务
docker compose restart
停止服务
docker compose down
八、升级容器
docker compose pull
docker compose up -d
九、进阶建议
✅ 1. 开放端口到公网（如有需要）
需在路由器上做端口转发。
✅ 2. 配合反向代理
可结合 Nginx 或 Traefik 实现 HTTPS 访问。
✅ 3. 搭配自动更新工具
可使用 Watchtower 实现自动更新容器。
十、常见问题排查
❓ 无法下载 / 无速度
- 检查 6881 端口是否开放
- 检查防火墙规则
- 检查 ISP 是否封锁 BT
❓ 权限错误
确认 PUID/PGID 是否与下载目录用户一致。
总结
使用 Docker Compose 部署 qBittorrent 的优势：
- 配置清晰
- 易于备份
- 一条命令即可恢复
- 升级简单
如果你是 NAS 用户或家庭服务器爱好者，这种部署方式非常推荐 👍