使用 Docker Compose 部署 qBittorrent（qbittorrentee）完整教程

前言#

在 NAS 或 Linux 服务器上部署一个稳定、可管理的 BT 下载工具是很多人的刚需。本文将介绍如何使用 Docker Compose 快速部署一个基于镜像 superng6/qbittorrentee 的 qBittorrent 容器服务。本教程适用于 Ubuntu / Debian / 群晖 / OpenMediaVault 等支持 Docker 的系统。

一、环境准备#

1️⃣ 安装 Docker#

如果你的系统尚未安装 Docker，可参考官方文档安装：

官网： https://www.docker.com/ Ubuntu 示例：

1
    sudo apt update
2
    sudo apt install docker.io -y
3
    sudo systemctl enable docker
4
    sudo systemctl start docker

2️⃣ 安装 Docker Compose#

新版 Docker 已自带 compose 插件，可通过以下命令确认：

1
    docker compose version

如果没有，可安装：

1
    sudo apt install docker-compose-plugin -y

二、创建项目目录#

建议为 qBittorrent 创建独立目录：

1
    mkdir -p ~/docker/qbittorrentee
2
    cd ~/docker/qbittorrentee

三、编写 docker-compose.yml 文件#

在当前目录创建文件：

1
    nano docker-compose.yml

写入以下内容：

1
    version: "3"
2
    services:
3
      qbittorrentee:
4
        image: superng6/qbittorrentee
5
        container_name: qbittorrentee
6
        environment:
7
          - PUID=1026
8
          - PGID=100
9
          - TZ=Asia/Shanghai
10
          - WEBUIPORT=8080
11
          - ENABLE_DOWNLOADS_PERM_FIX=true
12
        volumes:
13
          - ./qbittorrentee/config:/config
14
          - ./qbittorrentee/downloads:/downloads
15
        ports:
16
          - 6881:6881
17
          - 6881:6881/udp
18
          - 8080:8080
19
        restart: unless-stopped

保存并退出。

四、参数说明#

🔹 镜像说明#

superng6/qbittorrentee 是一个封装好的 qBittorrent WebUI 版本镜像。

🔹 关键环境变量说明#


端口	用途
6881 TCP	BT 下载
6881 UDP	DHT 网络
8080	Web 管理界面

🔹 数据目录说明#


宿主机路径	容器路径	作用
./qbittorrentee/config	/config	配置文件
./qbittorrentee/downloads	/downloads	下载目录

建议确保目录权限正确：

1
    mkdir -p qbittorrentee/config
2
    mkdir -p qbittorrentee/downloads
3
    chmod -R 775 qbittorrentee

五、启动服务#

在 docker-compose.yml 所在目录执行：

1
    docker compose up -d

查看运行状态：

1
    docker ps

六、访问 Web 管理界面#

浏览器访问：

1
    http://服务器IP:8080

默认用户名：admin

默认密码为随机生成，首次启动容器请查看日志。

七、常用管理命令#

查看日志#

1
    docker compose logs -f

重启服务#

1
    docker compose restart

停止服务#

1
    docker compose down

八、升级容器#

1
    docker compose pull
2
    docker compose up -d

九、进阶建议#

✅ 1. 开放端口到公网（如有需要）#

需在路由器上做端口转发。

✅ 2. 配合反向代理#

可结合 Nginx 或 Traefik 实现 HTTPS 访问。

✅ 3. 搭配自动更新工具#

可使用 Watchtower 实现自动更新容器。

十、常见问题排查#

❓ 无法下载 / 无速度#

检查 6881 端口是否开放
检查防火墙规则
检查 ISP 是否封锁 BT

❓ 权限错误#

确认 PUID/PGID 是否与下载目录用户一致。

总结#

使用 Docker Compose 部署 qBittorrent 的优势：

配置清晰
易于备份
一条命令即可恢复
升级简单

如果你是 NAS 用户或家庭服务器爱好者，这种部署方式非常推荐 👍

前言#