在NAS上，aria2因其轻量而备受推崇，但在BT/PT下载场景下，专业的qBittorrent客户端凭借其强大的连接管理和性能优化，通常能提供远超aria2的下载速度。本文将指导你如何使用 docker-compose 快速、稳定地部署qBittorrent，并解决首次登录的密码问题。

为什么选择 Docker Compose？

  • 配置清晰：所有配置（端口、文件夹映射、环境变量）都集中在一个 docker-compose.yml 文件中，一目了然。
  • 一键部署：只需一条命令即可启动、停止或重建服务。
  • 轻松迁移：备份docker-compose.yml和映射的文件夹，即可在任何支持Docker的设备上恢复你的下载服务。

准备工作

  1. 一台已经安装好 Docker 和 Docker Compose 的NAS或服务器。
  2. 通过SSH连接到你的设备终端。
  3. 规划好用于存放qBittorrent配置文件和下载文件的文件夹。

第一步：创建并编辑 docker-compose.yml 文件

首先，创建一个专门的目录来存放我们的项目。

# 创建一个名为 docker 的文件夹（如果已有则跳过）
mkdir -p ~/docker
# 进入文件夹
cd ~/docker
# 创建一个 qbittorrent 的子文件夹
mkdir qbittorrent
cd qbittorrent

# 创建并编辑 docker-compose.yml 文件
nano docker-compose.yml

然后，将以下内容复制并粘贴到 docker-compose.yml 文件中：

version: "3.8"
services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=0# 关键：你的root用户ID，省得后面出现文件写入权限问题
      - PGID=0# 关键：你的用户组ID
      - TZ=Asia/Shanghai # 设置你的时区
      - WEBUI_PORT=8080 # WebUI的访问端口
    volumes:
      - ./config:/config   # 配置文件目录
      - /path/to/your/downloads:/downloads       # 下载文件目录
    ports:
      - 8080:8080       # WebUI 端口
      - 6881:6881       # BT 传入连接端口
      - 6881:6881/udp   # BT 传入连接端口 (UDP)
    restart: unless-stopped

配置详解（请务必根据你的情况修改）：

  • PUID 和 PGID: 这是确保容器内程序有权限读写你NAS上文件夹的关键。
    • 如何获取？ 在你的NAS终端中输入命令 id <你的用户名> (例如 id yys)，你将看到类似 uid=1026(yys) gid=100(users) 的输出。uid 就是你的 PUID，gid 就是你的 PGID。请务必替换成你自己的值。
  • volumes: 文件夹映射。
    • ./config:/config: 将当前目录下的 config 文件夹映射到容器的 /config 目录。容器会自动创建这个 config 文件夹，用于存放所有设置。
    • /path/to/your/downloads:/downloads: 请务必修改 /path/to/your/downloads 为你NAS上实际用于存放下载文件的路径，例如 /volume1/downloads。

第二步：启动 qBittorrent 容器

保存并关闭 docker-compose.yml 文件后，在当前目录下（与文件同级），运行以下命令启动容器：

docker-compose up -d

-d 参数表示在后台（detached mode）运行。Docker会开始拉取镜像并根据你的配置创建容器。

第三步：查找首次登录的用户名和临时密码

这是最关键的一步！新版的镜像不再使用固定的 adminadmin 密码。我们需要从容器的启动日志中找到它。

运行以下命令查看日志：

docker logs qbittorrent

你会看到类似你之前分享的日志信息，其中包含了宝贵的登录凭据：

******** Information ********
To control qBittorrent, access the WebUI at: http://localhost:8080
The WebUI administrator username is: admin
The WebUI administrator password was not set. A temporary password is provided for this session: xkCufsZwm
You should set your own password in program preferences.

从日志中我们清晰地看到：

  • 用户名 (Username): admin
  • 临时密码 (Password): xkCufsZwm （注意：你的密码会是另一个随机字符串！）

第四步：登录并完成设置

  1. 打开浏览器，访问 http://<你的NAS_IP>:8080。
  2. 使用从日志中找到的 admin 和那个随机的临时密码进行登录。
  3. 立即修改密码：登录成功后，立即进入 工具 (Tools) -> 选项 (Options...) -> Web UI，设置一个你自己的强密码，然后保存。
  4. 配置端口转发：为了获得最佳下载速度，请登录你的路由器管理界面，将外部网络的 6881 端口（TCP和UDP协议）转发到你NAS的IP地址。
  5. 检查下载路径：在qBittorrent的选项 -> 下载 (Downloads) 中，确保默认保存路径是 /downloads，这对应着你映射到NAS的物理文件夹。

第五步：自动化与性能优化配置

初次登录并修改密码后，qBittorrent 已经可以正常工作了。但为了让它更智能、更高效，并且能自动管理做种任务，我们需要进行一些关键配置。

进入 工具 (Tools) -> 选项 (Options...)，然后按照下图和说明进行设置。

1. BT下载 (BitTorrent) 选项卡 - 自动化核心

这是我们将重点配置的区域，你的截图正是这个界面。

做种限制 (Seeding Limits)

这是实现“下载完后自动停止上传”功能的地方，也是BT“品德”的体现。

  • ☑️ 当分享率达到 (When ratio is reached): 勾选此项。
    • 输入框: 设置为 1 到 2 之间。
      • 1 的含义: 上传量达到下载量的1倍（例如，下载了一个1GB的文件，上传满1GB后）。
      • 推荐: 对于公共资源，设置 1 或 1.5 是一个非常健康的值，既能回馈社区，又不会永久占用你的上传带宽。对于有严格分享率要求的PT站，请根据站点规则设置。
  • 然后 (Then): （这个选项在你截图的下一行）默认是 “暂停 torrent (Pause torrent)”。保持这个设置即可。当达到你设定的分享率后，任务会自动暂停，不再上传。
Torrent 排队 (Torrent Queuing)

这个功能可以防止同时下载和上传的任务过多，导致你的路由器、NAS硬盘或网络不堪重负。

  • 最大活动的下载数: 3 (推荐默认) - 同时进行下载的任务数量。
  • 最大活动的上传数: 3 (推荐默认) - 同时进行上传（做种）的任务数量。
  • 最大活动的 torrent 数: 5 (推荐默认) - 上面两者相加的总和。

建议: 对于普通家用NAS和百兆带宽，默认的 3 / 3 / 5 组合非常均衡。如果你的NAS性能强大且带宽充足（例如千兆光纤），可以适当调高，比如 5 / 5 / 10。

隐私 (Privacy)
  • ☑️ 启用 DHT / PeX / 本地用户发现: 这三项默认都应勾选。它们是找到更多用户、提升下载速度（尤其是冷门资源）的关键技术。
  • 加密模式: 保持 “允许加密 (Allow encryption)”。这是一个兼容性最好的选项，它会优先使用加密连接，如果对方不支持，则回退到普通连接。

2. 速度 (Speed) 选项卡 - 带宽管理

为了防止 qBittorrent 下载时占满你所有带宽，导致家人无法上网，设置速度限制是很有必要的。

  • 全局速率限制 (Global Rate Limits):
    • 上传 (Upload): 建议设置为你总上传带宽的 80%。例如，如果你的上传带宽是 30 Mbps，可以设置为 2.5 MiB/s (约等于 20 Mbps)。保留一些上传带宽可以改善网络响应和下载速度。
    • 下载 (Download): 通常可以不限制 (0 或 ∞ 表示无限制)。但如果你希望在下载时也能流畅地进行其他网络活动，可以同样设置为总带宽的 80%-90%。

3. 下载 (Downloads) 选项卡 - 文件管理

  • 保存文件到: 确保这个路径是 /downloads/ 或者你在 docker-compose.yml 中映射的下载目录的子目录，例如 /downloads/completed/。
  • ☑️ 为未完成的文件添加 .!qB 扩展名: 强烈建议勾选。这样可以让你一眼就看出哪些文件还没下载完。
  • ☑️ 当下载中时，保存在: 可以设置一个临时文件夹，例如 /downloads/incomplete/。下载完成后，文件会自动从 incomplete 移动到最终的保存路径。这有助于你整理文件。