qBittorrent：下载工具

完成后，NAS 上跑着一个带网页界面的 BT 下载工具，文件直接下载到共享文件夹，局域网里的其他用户能正常读取。WebUI 只在局域网可用，不暴露到公网。

只下载你有权下载的内容，比如 Linux 发行版镜像。

适合谁

想让 NAS 自己下载，不用开着电脑。
需要 BT 下载，而不是 HTTP 下载。想下载网页上的普通文件，可以用别的工具。

应用信息

项	内容
示例清单	有 `qbittorrent`，示例文件日期 2025-06-01。清单里还有 `qbittorrent-vpn`、`binhex-qbittorrentvpn`、`gluetun` 这些带 VPN 的方案，配置因 VPN 服务商而异，本站不展开
镜像	LinuxServer 的 `lscr.io/linuxserver/qbittorrent:latest`。`latest` 用 libtorrent v2，`libtorrentv1` 标签用 libtorrent v1，没有特殊原因用默认的
示例里的端口	8080（WebUI）、6881 的 TCP 和 UDP（BT 连接）
数据	`/config` 是配置，`/downloads` 是下载目录
官方文档	LinuxServer.io：qBittorrent

WebUI 别暴露到公网，BT 端口转发也要想清楚

影响范围：WebUI 一旦被人访问，对方能控制你的下载，读到下载目录里的文件。BT 的连接端口对外开放后，其他下载者能看到你的公网 IP，这是 BT 协议本身的特点。
前置条件：先把 WebUI 的默认账号密码改掉（见下），并且只在局域网访问。要从外面管理，走 VPN，见远程访问：别把 NAS 直接暴露到公网。路由器端口转发，如果要做，只转发 BT 的连接端口（下面的 6881，TCP 和 UDP），绝不转发 8080。介意 IP 暴露，用带 VPN 的方案。
怎么回退：删掉路由器上的端口转发，在 qBittorrent 里关掉 UPnP，必要时停止容器。

部署

准备：一个放下载内容的共享文件夹，下文叫 downloads；专用用户 appuser，对它有读写权限，见容器权限：PUID、PGID 与共享文件夹。

服务 → Compose → 文件（Services → Compose → Files）→ 添加 → 从模板添加，选 qbittorrent，添加后编辑。示例原样是：

yaml

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=100
      - TZ=Etc/UTC
      - WEBUI_PORT=8080
    volumes:
      - CHANGE_TO_COMPOSE_DATA_PATH/qbittorrent/config:/config
      - CHANGE_TO_COMPOSE_DATA_PATH/qbittorrent/downloads:/downloads
    ports:
      - 8080:8080
      - 6881:6881
      - 6881:6881/udp
    restart: unless-stopped

改成这样：

yaml

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=${{ uid:"appuser" }}
      - PGID=${{ gid:"users" }}
      - UMASK=002
      - TZ=${{ tz }}
      - WEBUI_PORT=8080
      - TORRENTING_PORT=6881
    volumes:
      - ${{ sf:"appdata" }}/qbittorrent/config:/config
      - ${{ sf:"downloads" }}:/downloads
    ports:
      - "8080:8080"
      - "6881:6881"
      - "6881:6881/udp"
    stop_grace_period: 60s
    restart: unless-stopped

改动的原因：

用户和时区：用占位符读 OMV 里的真实值，不写死。
UMASK=002：让容器新建的文件是 664、目录是 775，同属 users 组的 SMB 用户才能修改和删除下载好的文件。
配置目录放进 appdata；下载目录直接挂你的共享文件夹，下载的内容直接出现在共享里，不用再搬。
TORRENTING_PORT：LinuxServer 说明，BT 连接端口要同时设 TORRENTING_PORT 环境变量和两个端口映射（TCP 和 UDP），示例里只有映射。
stop_grace_period：种子很多时，停止容器需要更久才能干净退出。Compose 插件的备份和更新都会停止容器，10 秒不够的话容易被强行杀掉，这里放宽到 60 秒。这是可选项，LinuxServer 的示例里是 10s。
端口 8080 的坑：WebUI 的端口，LinuxServer 说明要求两边一起改，既改映射，也改 WEBUI_PORT，否则 CSRF 校验会出问题。8080 同时也是 Traefik 示例、Nextcloud AIO 和 Kubernetes 插件的默认端口，会冲突，见写好 compose 文件。

点保存，检查，上线。

首次登录

在 OMV 的 shell 里（root）看日志找临时密码：omv-compose-run qbittorrent logs | grep -i password。也可以在文件列表的工具菜单里看日志。LinuxServer 的说明是：用户名 admin，临时密码在每次容器启动时打印到日志里。
浏览器打开 http://<NAS 的 IP>:8080，用 admin 和临时密码登录。
马上改密码：工具 → 选项 → Web UI（Tools → Options → Web UI）里设置用户名和密码。不改的话，每次容器重启都会生成一个新的临时密码，你会一直被锁在外面。界面文字以你的版本为准。
在连接设置里，用于传入连接的端口要和 TORRENTING_PORT 一致（6881），并且关掉 UPnP / NAT-PMP 自动端口映射。让软件自己去路由器上开端口，会增加暴露面，要不要转发应该由你自己决定。

检查结果

服务 → Compose → 文件 里状态灯是绿色，WebUI 能登录，密码改过了。
添加一个合法的测试种子，比如某个 Linux 发行版的种子，确认文件下载到了 downloads 共享文件夹里。
在 OMV 的 shell 里（root）运行 ls -ln 看下载目录，文件的属主 UID 是 appuser 的 UID，属组 100。
在另一台电脑上通过 SMB 打开 downloads 共享，能读取、能把下载好的文件移走。
确认没暴露：手机关掉 Wi-Fi 用流量，访问 http://你的公网IP:8080，应当打不开。

备份与维护

数据	位置	备份
配置、种子列表	`appdata/qbittorrent/config`	体积小，插件的计划备份会包含它。备份时容器会被停止，并且会等它干净退出
下载的内容	`downloads` 共享文件夹	通常很大。在卷行尾写 `# SKIP_BACKUP` 明确排除，内容是否值得备份，用文件备份工具单独决定

配置目录里有你的账号和种子状态，重装 NAS 前先备份，见更新与备份容器。
更新：拉取新镜像，重建容器。更新前看一眼 qBittorrent 的发布说明。
容器停止、更新和重启都会中断下载。下载中的任务重启后会继续。

常见问题

每次重启容器，登录密码都变了。 你没有在 WebUI 的选项里设置密码，临时密码每次启动重新生成。登录后改掉。

登录后提示 Unauthorized，或者操作报 CSRF 错误。 改了 WebUI 端口，却没有同时改 WEBUI_PORT 和映射。两边必须一致。

下载目录不可写。 目录属主和 PUID、PGID 对不上，见容器权限。

下载好的文件，别的用户改不了。 没设 UMASK=002，已经下载的文件在 SMB 客户端里重新保存，或者用小工具合集里的 resetperms 恢复标准权限，重置前先读它的警告。

下载速度很慢，连接状态不是绿色。 BT 的传入连接没通：端口没转发、没设置 TORRENTING_PORT，或者路由器有双重 NAT。要不要开放这个端口，回头看上面的警告。

8080 被占用。 同时改映射和 WEBUI_PORT，见上面的说明，排查见端口冲突。

qBittorrent：下载工具 ​

适合谁 ​

应用信息 ​

部署 ​

首次登录 ​

检查结果 ​

备份与维护 ​

常见问题 ​

参考资料 ​