qBittorrent Docker：完整安装与配置指南 – wiki大全

作者： /

我无法直接将文章写入文件，因为没有可用的 write_file 或 run_shell_command 工具来创建文件。但我可以直接输出文章内容给您。

qBittorrent Docker：完整安装与配置指南

简介

qBittorrent 是一款免费、开源且功能强大的 BitTorrent 客户端，它提供了直观的用户界面和丰富的特性，如 RSS 订阅、DHT、PEX、Magnet 链接支持、IP 过滤、Web UI 等。

Docker 则是一个开源的应用容器引擎，让开发者可以打包他们的应用以及依赖包到一个可移植的容器中，然后发布到任何流行的 Linux 机器或 Windows 机器上，也可以实现虚拟化。

将 qBittorrent 部署在 Docker 容器中，有以下显著优势：
1. 环境隔离：qBittorrent 及其所有依赖都运行在独立的容器中，不会污染宿主系统。
2. 易于部署：只需几行命令即可快速启动和停止服务，方便迁移和管理。
3. 资源管理：Docker 可以限制容器使用的 CPU、内存等资源。
4. 可移植性：配置一旦完成，可以轻松在不同服务器之间迁移。
5. 易于升级：更新 qBittorrent 只需要拉取最新的 Docker 镜像。

本指南将详细介绍如何使用 Docker Compose 完整安装和配置 qBittorrent。

前提条件

在开始之前，请确保您的系统已经安装了以下软件：

  1. Docker：Docker 引擎，用于运行容器。
  2. Docker Compose：用于定义和运行多容器 Docker 应用程序。
    • 通常在安装 Docker Desktop 时会自带，Linux 用户可能需要单独安装。安装教程可参考 Docker Compose 官方文档。

步骤一：创建项目目录

首先，创建一个用于存放 qBittorrent 配置和下载文件的目录。例如，在您的用户主目录下：

bash
mkdir -p ~/docker/qbittorrent
cd ~/docker/qbittorrent

在这个目录下，我们将创建 docker-compose.yml 文件以及用于存放 qBittorrent 配置和下载数据的子目录。

步骤二：创建 Docker Compose 文件

在 ~/docker/qbittorrent 目录下，创建一个名为 docker-compose.yml 的文件，并添加以下内容：

yaml
version: '3.8'
services:
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest # 使用 linuxserver 提供的镜像
container_name: qbittorrent
environment:
- PUID=1000 # 宿主用户的 ID，用于容器内文件权限管理
- PGID=1000 # 宿主用户组的 ID，用于容器内文件权限管理
- WEBUI_PORT=8080 # qBittorrent Web UI 端口
- TZ=Asia/Shanghai # 时区设置
volumes:
- ./config:/config # qBittorrent 的配置目录
- ./downloads:/downloads # 下载文件存放目录
# - /path/to/another/download/drive:/another_downloads # 如果有多个下载盘，可以添加
ports:
- 6881:6881 # qBittorrent P2P 端口 (TCP)
- 6881:6881/udp # qBittorrent P2P 端口 (UDP)
- 8080:8080 # Web UI 端口
restart: unless-stopped
labels:
- "com.centurylinklabs.watchtower.enable=true" # 如果使用 watchtower 自动更新容器

参数解释：

  • version: '3.8'：Docker Compose 文件的版本。
  • services：定义了一组服务（容器）。
  • qbittorrent：服务名称，可以自定义。
  • image: lscr.io/linuxserver/qbittorrent:latest：指定使用的 Docker 镜像。linuxserver/qbittorrent 是一个非常流行且维护良好的镜像，:latest 表示使用最新版本。
  • container_name: qbittorrent：容器的名称，方便识别和管理。
  • environment：环境变量设置。
    • PUID 和 PGID：非常重要！ 它们决定了容器内部进程操作宿主机挂载目录的权限。为了避免权限问题，强烈建议将其设置为您的宿主用户 ID 和用户组 ID。您可以通过在宿主机上运行 id -u 和 id -g 命令来获取。
    • WEBUI_PORT：qBittorrent Web UI 在容器内部监听的端口。与 ports 部分的宿主机端口对应。
    • TZ：设置容器的时区，例如 Asia/Shanghai。
  • volumes：卷挂载，用于持久化数据。
    • ./config:/config：将宿主机当前目录下的 config 子目录挂载到容器内部的 /config 目录。qBittorrent 的所有配置、缓存等都会存储在这里。
    • ./downloads:/downloads：将宿主机当前目录下的 downloads 子目录挂载到容器内部的 /downloads 目录。所有下载的 BT 文件都将保存在这里。
    • 您可以根据需要添加更多的下载目录，例如挂载一个独立的硬盘分区。
  • ports：端口映射，将容器内部的端口映射到宿主机端口。
    • 6881:6881：第一个 6881 是宿主机端口，第二个 6881 是容器内部端口。这是 BitTorrent 协议的 P2P 通信端口，需要同时映射 TCP 和 UDP。
    • 8080:8080：宿主机 8080 端口映射到容器内部 8080 端口，用于访问 qBittorrent Web UI。您可以将宿主机端口 8080 修改为其他未被占用的端口，例如 8081:8080。
  • restart: unless-stopped：设置容器的重启策略。除非手动停止，否则 Docker 守护进程启动时会自动重启容器。
  • labels：Docker 标签，这里添加了一个 watchtower.enable 标签，如果您安装了 Watchtower，它将自动检测并更新 qBittorrent 容器到最新镜像。

获取 PUID 和 PGID

在 Linux 或 macOS 宿主机上，打开终端并运行：

bash
id -u # 获取用户 ID (UID/PUID)
id -g # 获取用户组 ID (GID/PGID)

将获取到的数值替换 docker-compose.yml 文件中的 PUID 和 PGID。Windows 用户如果使用 WSL2 运行 Docker，则在 WSL2 终端中执行此命令。如果直接在 Windows 上使用 Docker Desktop，则通常可以使用默认的 1000，但可能需要注意共享驱动器的权限设置。

步骤三：启动 qBittorrent 容器

在 ~/docker/qbittorrent 目录下，打开终端并运行以下命令来启动容器：

bash
docker-compose up -d

  • up：根据 docker-compose.yml 文件创建并启动服务。
  • -d：在后台运行容器（detached mode）。

第一次运行会下载 qBittorrent 镜像，这可能需要一些时间。容器启动后，您可以使用以下命令检查容器状态：

bash
docker-compose ps

如果一切正常，您应该能看到 qbittorrent 容器的状态为 Up。

步骤四：访问 Web UI 并进行初始配置

现在，您可以通过浏览器访问 qBittorrent 的 Web UI。打开浏览器，输入您的宿主机 IP 地址和之前设置的 Web UI 端口（默认为 8080），例如：

http://your_server_ip:8080

默认登录凭据

首次登录时，Web UI 会要求输入用户名和密码：

  • 用户名：admin
  • 密码：adminadmin

登录后，强烈建议立即更改默认密码。在 Web UI 中，点击菜单栏的 工具(Tools) -> 选项(Options) -> Web UI，在 身份验证(Authentication) 部分修改用户名和密码。

下载目录配置

在 选项(Options) -> 下载(Downloads) 中，您可以确认下载路径。由于我们已经通过 Docker 卷挂载了 ./downloads 目录到容器的 /downloads 路径，这里通常无需修改，默认路径 downloads 即可将文件保存到宿主机的 ~/docker/qbittorrent/downloads 目录。

其他基本配置

  • 连接(Connection)：
    • 端口：确保“监听端口”设置为 6881 (TCP 和 UDP)，这与 docker-compose.yml 中映射的端口一致。
    • 启用 UPnP/NAT-PMP 端口转发：如果您希望路由器自动为您打开端口，可以勾选。但更推荐在路由器中手动设置端口转发（将外部 6881 端口转发到宿主机的 6881 端口），这样更稳定和安全。
    • 使用不同的端口监听传入连接：如果您在 docker-compose.yml 中将宿主机端口 6881 映射到了其他端口（例如 6882），则此处也应调整。
  • 速度(Speed)：根据您的网络带宽设置全局上传和下载限速。
  • RSS (如果需要)：在 RSS 选项卡中启用 RSS 订阅器，并添加您喜欢的 RSS 源。
  • 搜索引擎(Search Engine)：qBittorrent 自带搜索引擎。您可以通过点击 搜索 标签页下方的 搜索插件 按钮，然后点击 检查更新 或 安装新的 来安装更多的搜索插件。

步骤五：路由器端口转发（重要）

为了让 qBittorrent 能够获得更好的连接性（特别是对于上传和可发现性），您需要在家庭路由器上设置端口转发。

将 6881 端口（或您在 docker-compose.yml 中为 P2P 流量配置的宿主机端口）从路由器的外部接口转发到运行 qBittorrent Docker 容器的宿主机的内部 IP 地址。

操作步骤大致如下：

  1. 登录到您的路由器管理界面（通常是 192.168.1.1 或 192.168.0.1）。
  2. 找到“端口转发(Port Forwarding)”、“NAT”或“虚拟服务器(Virtual Servers)”等设置项。
  3. 添加一个新的转发规则：
    • 外部端口 (External Port): 6881
    • 内部端口 (Internal Port): 6881
    • 协议 (Protocol): TCP 和 UDP (或选择 Both)
    • 内部 IP 地址 (Internal IP Address): 您的宿主机局域网 IP 地址（例如 192.168.1.100）。确保您的宿主机有固定 IP 地址，或在路由器中为其分配静态租约。
    • 启用该规则。

完成设置后，您可以在 qBittorrent Web UI 的底部状态栏看到连接状态。如果端口转发成功，通常会显示一个绿色的对勾或“可连接”状态。

步骤六：管理和维护

更新 qBittorrent 容器

当 linuxserver/qbittorrent 镜像有新版本发布时，您可以轻松更新您的 qBittorrent 容器：

bash
cd ~/docker/qbittorrent
docker-compose pull # 拉取最新镜像
docker-compose up -d # 使用新镜像重建并启动容器

docker-compose up -d 命令会停止并删除旧容器，然后使用新拉取的镜像创建一个新容器，同时保留您的数据卷。

自动更新 (使用 Watchtower)

如果您希望自动更新，可以考虑安装 Watchtower。它会监控您的 Docker 容器，并在发现新镜像时自动更新它们。

在 ~/docker 目录下创建一个 watchtower-compose.yml：

yaml
version: "3.8"
services:
watchtower:
image: containrrr/watchtower
container_name: watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
# command: --interval 300 # 每 5 分钟检查一次更新
restart: unless-stopped

然后启动 Watchtower：

bash
cd ~/docker
docker-compose -f watchtower-compose.yml up -d

请注意，Watchtower 会更新所有带有 com.centurylinklabs.watchtower.enable=true 标签的容器（我们在 qbittorrent 的 docker-compose.yml 中添加了）。

查看日志

如果遇到问题，查看容器日志是很好的排查方法：

bash
docker-compose logs qbittorrent

停止和删除容器

停止 qBittorrent 容器：

bash
cd ~/docker/qbittorrent
docker-compose stop

停止并删除容器（保留数据卷）：

bash
cd ~/docker/qbittorrent
docker-compose down

停止并删除容器及所有数据卷（慎用，会删除下载数据和配置）：

bash
cd ~/docker/qbittorrent
docker-compose down -v

常见问题与排查

  1. Web UI 无法访问：
    • 检查宿主机防火墙是否开放了 8080 端口（或您配置的 Web UI 端口）。
    • 检查 qBittorrent 容器是否正在运行：docker-compose ps。
    • 查看容器日志：docker-compose logs qbittorrent。
    • 确保您的浏览器输入了正确的 IP 地址和端口。
  2. 下载速度慢或连接数少：
    • 最常见的原因是端口转发未正确设置。 仔细检查路由器设置。
    • 检查宿主机防火墙是否开放了 P2P 端口 (6881)。
    • 在 qBittorrent Web UI 中检查连接状态，看是否有黄色或红色警告。
    • 尝试更换 P2P 端口。
  3. 文件权限问题：
    • 确保 PUID 和 PGID 设置正确，与宿主机的用户 ID 和用户组 ID 一致。
    • 在宿主机上，确保 ./config 和 ./downloads 目录及其内容的用户和组权限与 PUID/PGID 匹配。您可以使用 sudo chown -R PUID:PGID ~/docker/qbittorrent/downloads 和 sudo chown -R PUID:PGID ~/docker/qbittorrent/config 来修复。
  4. RSS 订阅无法更新：
    • 检查容器的时区设置是否正确 (TZ 环境变量)。
    • 检查网络连接是否正常。
    • 尝试手动更新 RSS 源。

总结

通过本指南，您应该已经成功地使用 Docker Compose 部署和配置了 qBittorrent。Docker 的容器化优势使得 qBittorrent 的部署、管理和维护变得异常简单高效。记得定期更新容器，并关注端口转发和权限设置，以确保您的 qBittorrent 客户端能够稳定、高效地运行。享受您的下载体验吧！

滚动至顶部