🚀 使用 Docker Compose 部署 qBittorrent

qBittorrent 是一个由 Christophe Dumez 于2006年开发的开源、跨平台 BitTorrent 客户端。它基于 Qt 框架和 libtorrent 库构建，提供了一个轻量级、高效且无广告的文件共享平台。通过 Docker Compose 部署，可以简化安装过程，确保环境一致性，并便于后续维护。

📦 项目简介

qBittorrent 的核心目标是提供一个 “干净、简洁、高性能” 的下载工具。它支持所有主要的 BitTorrent 扩展，并集成了丰富的功能。

主要功能亮点： * 智能资源管理：内置可编程带宽调度器，支持分时段限速规则设置；提供队列和优先级管理，可以设置下载和上传任务的优先级。 * 强大的搜索与订阅：内置搜索引擎，支持从客户端内直接搜索 torrent 文件；支持 RSS 订阅与自动下载，自动下载符合条件的 torrent 文件，节省用户时间。 * 全面的协议支持：完整兼容 BitTorrent V2 协议规范，集成 DHT 分布式哈希表、PeerExchange、加密连接等扩展协议，并支持 Magnet URI 磁力链接直接下载。 * 便捷的远程控制：通过 WebUI 实现远程控制，允许用户从其他设备管理下载任务。 * 增强的隐私与安全：提供 IP 过滤器（可自动加载P2P黑名单数据库）帮助用户屏蔽不必要的连接，增强隐私保护。

⚙️ 部署前准备

环境要求
- 已安装 Docker 和 Docker Compose。
- 系统内存：建议 512MB 以上。
- 磁盘空间：确保有足够空间存储下载文件和配置。
环境检查 在终端中执行以下命令，确认 Docker 环境正常： bash docker --version docker-compose --version
创建项目目录 建议创建一个独立的目录来管理 qBittorrent 的所有文件。 bash mkdir -p /opt/docker/qbittorrent cd /opt/docker/qbittorrent

🛠️ 配置 Docker Compose

基于你提供的配置，这里是对 docker-compose.yml 文件的解读和优化说明。

networks:
  videos:
    external: true  # 使用已创建的外部网络（需提前执行 docker network create videos）

#version: '3.8'
services:
  qbittorrent:
    container_name: qbittorrent # 容器名称，便于管理
    hostname: qbittorrent # 容器主机名（默认即可）
    #image: johngong/qbittorrent #:4.6.0-4.6.0.10
    image: linuxserver/qbittorrent  # LinuxServer 维护版镜像（稳定、更新及时）
    environment:
      #- QB_WEBUI_PORT=5005 #8989
      #- QB_EE_BIN=false
      - WEBUI_PORT=5005  # WebUI 端口（容器内端口，需与 ports 映射一致）
      - TORRENTING_PORT=50000  # BT 下载端口（容器内端口，需与 ports 映射一致）
      #- PUID=1000
      #- PGID=1000
      - PUID=0  # 运行用户 ID（0 为 root 权限，避免下载目录权限问题，新手推荐默认）
      - PGID=0  # 运行用户组 ID（与 PUID 一致）
      - PERMS=true  # 自动修复下载目录权限（防止因权限不足无法写入，建议开启）
      - UMASK=022  # 权限掩码（控制新下载文件的默认权限，默认即可）
      - TZ=Asia/Shanghai   # 时区（确保日志时间与本地一致）
    #expose:  # 仅内部暴露端口
      #- 8080
      #- 6881
      #- 6881/udp
    ports:
      #- "8989:8989"
      #- "6881:6881"
      #- "6881:6881/udp"
      - "5005:5005"  # WebUI 端口映射：主机 5005 → 容器 5005
      - "50000:50000"  # BT 下载端口（TCP）：主机 50000 → 容器 50000
      - "50000:50000/udp"  # BT 下载端口（UDP）：主机 50000 → 容器 50000
      #- 50000:6881
      #- 50000:6881/udp
      #- "28103:28103"
      #- "28103:28103/udp"
    volumes:
      - ./config:/config  # 配置目录：主机 ./config → 容器 /config（保存设置、种子）
      - /mnt/10t/videos/downloads:/downloads  # 下载目录：主机影视下载路径 → 容器 /downloads
      - "./alist/qb-downloads:/opt/alist/data/temp/qBittorrent"  # 挂载到Alist临时目录（不用可删除此行）
      #- ./media/video:/media/video
      #- ./downloads:/downloads

      #- ./Video:/Video
      #- ./video:/media
      #- ./video/Movie:/media/video1   #电影
      #- ./video/TV-Play:/media/video2 #电视剧
      #- ./video/Anime:/media/video3   #动漫缩写
    #restart: unless-stopped
    restart: always  # 容器退出后自动重启（开机自启，确保下载任务不中断）

#我们先来打开qbittorrent容器的Web界面，账号密码分别为：admin/adminadmin。（注意：最新4.6.1版本有BUG，这里会显示“无效的用户名或密码”，所以我在上篇搭建的时候使用的是指定4.6.0版本，我在上篇搭建的时候提到过）。


    privileged: true  # 授予特权模式（解决部分目录权限问题，新手建议开启）
    #特权:真
    #restart: 'unless-stopped'


    networks:
      videos:
        ipv4_address: 10.1.1.7  # 容器在 videos 网络中的固定 IP（默认即可，无需修改）
        #ipv6_address: 2001:3984:3989::10

#默认用户名是 admin
#密码需要查看容器标准输出
#docker logs -f qbittorrent

关键配置说明：

配置项	说明与建议
`image`	使用 `linuxserver/qbittorrent` 镜像，这是一个维护良好且稳定的选择。
`ports`	`"5005:5005"` 将容器内的 5005 端口（Web UI）映射到主机的 5005 端口。`50000:50000` 用于 BT 下载端口映射，请确保该端口在您的路由器/防火墙中已正确转发，这对下载速度至关重要。
`volumes`	`./config:/config` 用于持久化存储qBittorrent 的所有配置、种子状态等，务必确保此配置，防止容器重启后数据丢失。`/mnt/10t/videos/downloads:/downloads` 将你的下载目录映射到容器内。
`environment`	`PUID`/`PGID`：设置为 `0` 即以 root 权限运行，可避免很多权限问题。`WEBUI_PORT=5005`：设置容器内 Web 界面的监听端口，必须与 `ports` 中映射的容器端口一致。
`privileged: true`	授予容器特权模式，有助于解决一些可能的权限或设备访问问题。

注意：关于下载目录的映射，请确保容器内进程（由 PUID/PGID 指定）对宿主机上映射的目录有读写权限。如果遇到 "Permission denied" 错误，可尝试将 PUID/PGID 设置为 0（root），或者调整宿主机上目录的权限和所有者。

🚀 启动与验证

启动服务 在 docker-compose.yml 文件所在目录执行： bash docker-compose up -d 此命令会拉取镜像并在后台启动容器。
检查服务状态 bash docker-compose ps 如果看到 qbittorrent 容器的状态为 Up，说明服务已成功启动。
查看实时日志（可选） 如果遇到问题，可以通过以下命令查看容器日志来排查： bash docker-compose logs -f qbittorrent 日志中可能会显示 WebUI 的临时密码，请留意。
访问 Web 界面 打开浏览器，访问 http://你的服务器IP:5005。
- 如果一切正常，你将看到 qBittorrent 的登录界面。
- 默认用户名是 admin。
- 默认密码通常是 adminadmin。注意：在某些最新版本中，首次启动可能会在日志中生成一个随机临时密码，请根据您的镜像和版本尝试。

⚙️ 基础配置与使用

成功登录后，建议进行一些基础配置以优化 qBittorrent 的使用体验。

设置中文界面
- 点击界面左上角的 "Tools" (工具) 菜单。
- 选择 "Preferences" (首选项)。
- 在打开的窗口左侧，点击 "Behavior" (行为)。
- 在右侧的 "Language" (语言) 下拉框中，选择 "简体中文"。
- 滚动到页面底部，点击 "Save" (保存)。界面将自动刷新为中文。
配置连接设置（提升连接性关键）
- 进入 "工具" -> "选项" -> "连接"。
- 监听端口：确认与您在 docker-compose.yml 中设置的 TORRENTING_PORT (例如 50000) 一致。建议在路由器中为此端口设置转发。
- 勾选 "使用UPnP / NAT-PMP" (如果路由器支持)。
- 在 "连接限制" 部分，根据您的网络情况调整全局和每个 Torrent 的最大连接数。
调整下载设置
- 进入 "工具" -> "选项" -> "下载"。
- 确认 "默认保存路径" 为容器内的路径 (例如 /downloads)。请务必使用容器内路径，而非宿主机路径。
- 建议勾选 "自动管理模式" 以简化种子管理。
- 可配置 "移动已完成的任务到..." 以实现下载完成后的自动文件整理。
配置带宽调度（优化网络使用）
- 进入 "工具" -> "选项" -> "速度"。
- 您可以设置 "全局速率限制" 的上传和下载速度。
- 更强大的是 "计划模式" (基于时间的调度)，您可以设置特定时间段内的速度限制，例如在白天限制速度，在夜间全速下载。

🔒 维护与管理

服务管理：
- 停止服务：docker-compose down
- 重启服务：docker-compose restart
- 查看服务状态：docker-compose ps
数据备份：
- 定期备份 docker-compose.yml 文件以及映射的 ./config 目录。./config 目录包含了 qBittorrent 的所有配置、种子状态和恢复数据，至关重要。
版本更新： qBittorrent 活跃更新，建议定期升级以获取新功能和安全性更新。 bash # 进入 docker-compose.yml 所在目录 docker-compose down docker-compose pull # 拉取最新镜像 docker-compose up -d # 可选：清理无用镜像 docker image prune 注意：更新前，特别是大版本更新时，建议备份 ./config 目录。您也可以参考一些社区提供的平滑升级方法。

🐛 常见问题排查 (FAQ)

问题现象	可能原因与解决方法
无法访问 Web 界面	1. 检查防火墙/安全组是否放行 5005 端口。 2. 确认容器是否正常运行：`docker-compose ps`。 3. 查看容器日志：`docker-compose logs qbittorrent`。
下载速度慢或为 0	1. 检查端口映射与转发：确保 `TORRENTING_PORT` (如 50000) 已在路由器中正确转发。 2. 检查 Tracker 状态：在种子详情中查看 Tracker 反馈信息。 3. 尝试强制重新校验：右键种子 -> "强制重新校验"。 4. 尝试启用 IPv6：在连接设置中启用 IPv6 (如果您的网络支持)。
文件权限错误	1. 检查 `volumes` 映射的宿主机目录是否存在且有读写权限。 2. 检查 `PUID`/`PGID` 设置：确保与宿主机上目录的所有者匹配。可尝试设置为 `0` (root)。 3. 检查 `UMASK` 值，它决定了新创建文件的默认权限。
种子状态异常或文件丢失	1. 检查文件路径：如果您在宿主机上移动或重命名了文件，可能导致 qBittorrent 找不到文件。 2. 使用 "强制重新校验" 功能让 qBittorrent 重新关联文件。 3. 对于已完成种子的移动，建议使用 qBittorrent 内置的移动功能，而非直接在文件系统中操作，以避免问题。
CPU 占用率过高	1. 可能是由于活跃种子数量过多或磁盘读写负载大。 2. 尝试在 qBittorrent 的设置中降低全局连接数。 3. 确保使用的是稳定版本的镜像，某些测试版可能存在性能问题。

希望这份详细的教程能帮助你顺利完成 qBittorrent 的部署，享受高效、便捷的下载体验！