项目介绍
qBittorrent 是支持 Web UI 的下载客户端,适合在 NAS 上持续运行。下面提供 Compose 与命令示例,并说明群晖目录准备、启动和首次登录。下载目录的宿主机路径与容器路径需要分别对应,后续媒体整理工具也要保持一致。
qbittorrent最新版本
services:
qbittorrent:
image: linuxserver/qbittorrent:latest
container_name: qbittorrent
volumes:
- /volume1/docker/qb/config:/config
- /volume1/docker/qb/downloads:/downloads
- /volume1/影视:/影视
privileged: true
network_mode: host
environment:
- UID=0
- GID=0
- GLIST=0
- GIDLIST=0,0
- WEBUI_PORT=8085
restart: unless-stoppedqbittorrent指定老版本
services: # 服务定义
qbittorrent: # 服务名称
image: linuxserver/qbittorrent:4.6.7 # 镜像来源和版本
container_name: qbittorrent # 容器名称
network_mode: host # 使用主机网络
environment: # 环境变量设置
- PUID=0 # 用户ID
- PGID=0 # 组ID
- TZ=Asia/Shanghai # 时区
- WEBUI_PORT=8085 # 网页用户界面端口
- TORRENTING_PORT=6951 # 种子传输端口
volumes: # 挂载卷
- /volume1/docker/qb/config:/config # 配置文件存储路径
- /volume1/docker/qb/downloads:/downloads
- /volume1/影视:/影视
ports: # 端口映射
- 8080:8080 # 映射网页用户界面端口
mem_limit: 4g # 限制内存使用量为4GB
restart: unless-stopped # 容器重启策略补充:部署与使用
配置与操作示例
Compose 部署
示例使用 LinuxServer 维护的容器发行;它与 qBittorrent 上游项目是不同维护主体。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/qbittorrent/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/qbittorrent /volume1/docker/qbittorrent/config /volume1/downloads
cd /volume1/docker/qbittorrent
HALO_PREPARE
cd /volume1/docker/qbittorrent
本示例使用数值 0 访问挂载目录,无需查询或填写 UID/GID。
services:
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
environment:
PUID: "0"
PGID: "0"
TZ: Asia/Shanghai
WEBUI_PORT: "8080"
TORRENTING_PORT: "6881"
volumes:
- /volume1/docker/qbittorrent/config:/config
- /volume1/downloads:/downloads
ports:
- "8080:8080"
- "6881:6881"
- "6881:6881/udp"
restart: unless-stopped
示例的 PUID、PGID 已写为 0,无需另填账号编号。8080 是管理网页;6881 是示例传入连接端口,TCP 与 UDP 映射用途不同。需要更换 Web UI 端口时,同时调整 WEBUI_PORT 和对应映射,避免校验错误。
启动后访问 http://NAS_IP:8080。当前发行的首次登录临时密码从本机日志取得,登录后立即改为自己的密码;不要把包含该密码的日志贴到公开页面。
保存路径与重新定位
程序中的下载目录填写 /downloads。可在其下区分 incomplete 与 complete,为任务设置分类后检查实际路径。已有任务迁移时先暂停,通过客户端的保存路径功能重新定位,再按需执行校验;不要仅在 File Station 移走文件后删除任务。
启动与状态检查
在保存 compose.yaml 和所需 .env 的项目目录执行:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
config 用于检查配置,不会启动服务。示例使用上游浮动发行通道;长期运行可改为项目实际发布的固定标签或已记录的镜像摘要,不猜写版本号。日志中出现的初始密码和访问凭据仅在自己的终端查看。
常见问题
- 程序能运行但无法写入:检查宿主目录、PUID/PGID 和共享权限,不用全局可写代替权限设计。
- 升级时先保存版本和配置,不把回退旧镜像等同于任务数据库必定兼容。
更新与备份
备份配置目录、任务和路径表;正在做种的数据需保留原内容与位置关系。
更新前记录当前镜像或仓库提交,停止会写入的任务并备份持久化数据;阅读版本迁移说明后再拉取并重建。数据库已经迁移时,回退还需要匹配的数据副本。需要暂时停服务可用 docker compose stop,不要把删除卷或清空数据目录当作更新步骤。