VPS 搭建 qBittorrent WebUI（2026）：Docker、HTTPS、下载目录与安全配置

qBittorrent 支持无桌面环境运行，并通过浏览器管理任务，适合以下用途：

• 长期分发自己的开源镜像、数据集或公开视频；
• 下载 Linux ISO、公开数据与合法授权素材；
• 为团队内部的大文件分发提供稳定在线节点；
• 在自己的设备之间做合法的点对点文件传输；
• 需要固定公网 IP 和持续上传能力的测试环境。

不适合的情况包括：

• 套餐明确禁止 BitTorrent、P2P 或高持续流量；
• VPS 只有几十 GB 系统盘，却计划保存大量文件；
• 月流量很小，超额后会产生高额费用或直接停机；
• 需要保存私密资料，却打算把 WebUI 直接暴露公网；
• 以为“1Gbps 端口”就代表可以长期跑满且不限流量。

qBittorrent 本身免费，并不等于带宽、存储、备份和版权风险也免费。购买 VPS 前应先阅读 Acceptable Use Policy、版权投诉流程、端口限制和流量计费说明。

qBittorrent 空闲时资源占用不高，但校验大文件、同时连接大量 Peer 和高速写盘时，会明显消耗 CPU、内存与 I/O。

持续占用 10Mbps 一个自然月，理论传输量约为 3.24TB；持续 100Mbps 则约为 32.4TB。BitTorrent 同时有下载和上传，服务商可能只计算出站，也可能计算双向流量，因此不能只看 qBittorrent 的下载统计。

磁盘选择同样重要：

• NVMe/SSD 适合大量小文件、频繁校验和多个并发任务；
• HDD 容量便宜，但随机读写和同时上传多个文件时更容易出现 I/O 等待；
• 块存储像本地磁盘一样使用，适合独立数据盘，但要确认 IOPS、吞吐和快照价格；
• 对象存储不具备普通文件系统的写入语义，不适合直接作为 qBittorrent 的活动下载目录；
• 网络盘断开可能让文件暂时消失，错误的自动管理设置会带来数据风险。

上线后建议使用站内的VPS 流量监控与超额预警教程，同时设置服务商账单告警。

本文采用以下结构：

浏览器 -> HTTPS 443 -> Caddy -> 127.0.0.1:8080 -> qBittorrent WebUI
Peer    -> TCP/UDP 6881 -> Docker -> qBittorrent 下载监听端口

端口规划：

WebUI 和 Peer 端口不是一回事。WebUI 只给管理员使用，Peer 端口用于 BitTorrent 数据连接。把 8080 开放全网既没有必要，也会增加密码爆破和 Web 漏洞风险。

先更新 Ubuntu：

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg ufw

生产环境建议按 Docker 官方仓库安装 Docker Engine 与 Compose 插件。安装完成后检查：

docker version
docker compose version
sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

如果你还没有形成 Compose 的健康检查、日志轮转、密钥和回滚习惯，可以先阅读VPS Docker Compose 生产环境配置清单。

本文命令默认当前用户可以执行 Docker。把用户加入 docker 组相当于授予接近 root 的主机控制能力，不应给不受信任的账号。

创建项目目录与独立下载目录：

sudo install -d -m 750 /opt/qbittorrent
sudo install -d -m 750 /srv/qbittorrent/downloads
sudo install -d -m 750 /srv/qbittorrent/downloads/incomplete
sudo install -d -m 750 /srv/qbittorrent/downloads/complete
sudo chown -R "$(id -u):$(id -g)" /opt/qbittorrent /srv/qbittorrent
cd /opt/qbittorrent

确认实际 UID、GID 和时区：

id -u
id -g
timedatectl show --property=Timezone --value

创建 /opt/qbittorrent/.env，把示例中的 UID、GID 和时区改成上一组命令的真实输出：

PUID=1000
PGID=1000
TZ=Asia/Shanghai
WEBUI_PORT=8080
TORRENTING_PORT=6881

保护环境文件：

chmod 600 /opt/qbittorrent/.env

.env 没有保存 WebUI 密码，但它仍属于部署配置。不要把整个项目目录直接提交到公开 Git 仓库。

创建 /opt/qbittorrent/compose.yaml：

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      PUID: "${PUID}"
      PGID: "${PGID}"
      TZ: "${TZ}"
      WEBUI_PORT: "${WEBUI_PORT}"
      TORRENTING_PORT: "${TORRENTING_PORT}"
    volumes:
      - ./config:/config
      - /srv/qbittorrent/downloads:/downloads
    ports:
      - "127.0.0.1:${WEBUI_PORT}:${WEBUI_PORT}/tcp"
      - "${TORRENTING_PORT}:${TORRENTING_PORT}/tcp"
      - "${TORRENTING_PORT}:${TORRENTING_PORT}/udp"
    restart: unless-stopped
    stop_grace_period: 30s
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

这份配置有几个关键点：

1. 8080 只映射到宿主机 127.0.0.1，公网不能直接访问；
2. 6881 同时映射 TCP 和 UDP，且与 TORRENTING_PORT 一致；
3. 配置和下载数据放在宿主机目录，删除容器不会删除文件；
4. Docker 日志设置大小和数量上限，避免日志无限增长；
5. no-new-privileges 阻止容器进程通过 setuid 等机制获得新权限。

LinuxServer 的官方镜像说明特别强调：修改 WebUI 端口时，必须同时修改端口映射和 WEBUI_PORT；修改 Peer 端口时，也要同时修改 TCP、UDP 映射和 TORRENTING_PORT。只改一处会导致 WebUI、CSRF 检查或入站连接异常。

先校验 Compose：

cd /opt/qbittorrent
docker compose config
docker compose pull
docker compose up -d
docker compose ps

当前 LinuxServer 镜像首次启动会在容器日志中输出 admin 用户的临时密码：

docker compose logs --tail=200 qbittorrent

也可以只筛选相关日志：

docker compose logs qbittorrent | grep -i -E 'password|webui'

从 qBittorrent 4.6.1 起，不应继续照抄旧教程中的固定默认密码 adminadmin。临时密码会出现在启动日志中；登录后必须立即修改用户名和强随机密码，否则容器重启后还可能生成新的临时密码。

此时在 VPS 本机测试：

curl -I http://127.0.0.1:8080
docker compose logs --tail=100 qbittorrent

返回 HTTP 响应说明 WebUI 已启动。由于端口只监听回环地址，从个人电脑直接访问 http://VPS-IP:8080 应该失败，这是预期的安全结果。

在自己的电脑执行：

ssh -L 8080:127.0.0.1:8080 [email protected]

203.0.113.10 是文档示例地址，请替换为 VPS 的真实 IP。保持 SSH 会话打开，然后浏览器访问：

http://127.0.0.1:8080

使用日志中的临时密码登录后，进入 WebUI 设置并完成：

• 修改默认管理员用户名和密码；
• 保持 CSRF 与 clickjacking 防护开启；
• 不要启用“本地网络免认证”或大范围子网免认证；
• 把默认保存路径设为 /downloads/complete；
• 把未完成任务路径设为 /downloads/incomplete；
• 确认监听端口为 6881，并关闭随机启动端口；
• 设置合理的全局上传、下载速度和并发任务数；
• 保存后退出，再用新账号重新登录一次。

截至 2026 年 8 月，qBittorrent 当前稳定版为 5.2.1。版本会继续更新，部署前应查看qBittorrent 官方发布页和官方新闻页，不要只相信镜像缓存中的旧版本号。

先把 downloads.example.com 的 A/AAAA 记录指向 VPS。该域名只是示例，必须替换成你自己的域名。

在 Caddyfile 中增加：

downloads.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080
}

校验并重载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager

开放 HTTP 和 HTTPS：

sudo ufw allow 80/tcp comment 'Caddy HTTP'
sudo ufw allow 443/tcp comment 'Caddy HTTPS'

完整的 Caddy 安装、DNS、自动证书和日志流程可参考VPS 用 Caddy 反向代理完全指南。

登录 qBittorrent WebUI 后，把 WebUI 的域名白名单设置为实际域名，并启用安全 Cookie。不要为了处理 Unauthorized 或 Host header 错误就关闭 Host Header Validation；应检查域名、反向代理 Host 头和端口配置是否一致。

HTTPS 只保护浏览器到 VPS 的管理连接，Peer 流量仍按 BitTorrent 协议工作。不要在 Caddy 或 Cloudflare 中代理 6881/TCP/UDP；普通 Web 反向代理无法替代 Peer 监听端口。

先确认 SSH 不会被锁在门外：

sudo ufw allow OpenSSH
sudo ufw allow 6881/tcp comment 'qBittorrent peer TCP'
sudo ufw allow 6881/udp comment 'qBittorrent peer UDP'
sudo ufw enable
sudo ufw status numbered

云平台安全组也要放行相同的 TCP/UDP Peer 端口。不要添加 8080/tcp 公网规则。

验证宿主机监听：

sudo ss -lntup | grep -E ':8080|:6881'
docker compose ps

预期结果是：

• 8080 只出现在 127.0.0.1；
• 6881 同时有 TCP 和 UDP 映射；
• Caddy 监听公网 80/443；
• WebUI 设置中的监听端口与 Compose 一致。

入站 Peer 端口开放后，qBittorrent 更容易成为主动节点并接受连接，但速度仍取决于资源可用性、Peer 数量、线路、磁盘和限速策略。端口开放不等于任何任务都能达到满速。

在 WebUI 中使用容器内路径：

/downloads/incomplete
/downloads/complete

不要填写宿主机的 /srv/qbittorrent/... 路径，因为容器内只看到挂载后的 /downloads。

检查权限：

cd /opt/qbittorrent
docker compose exec qbittorrent id
stat -c '%u:%g %a %n' config /srv/qbittorrent/downloads
touch /srv/qbittorrent/downloads/.write-test
rm /srv/qbittorrent/downloads/.write-test

如果容器日志出现 Permission denied，先比较容器 UID/GID、.env 中的 PUID/PGID 和宿主机目录所有者，不要直接使用 chmod -R 777。

至少保留 10%–20% 可用空间，并设置监控阈值：

df -h /srv/qbittorrent/downloads
df -i /srv/qbittorrent/downloads
du -xhd1 /srv/qbittorrent/downloads | sort -h

未完成任务可能同时占用预分配空间和临时文件。自动删除规则也必须谨慎：删除 qBittorrent 任务和删除磁盘文件是两个不同动作，点确认前先看清选项。

不要让 qBittorrent 长期跑满 VPS 端口。跑满上传会增加交互延迟，也可能触发服务商公平使用限速。

可从以下保守设置开始，再根据监控调整：

这些是排障起点，不是通用最优值。热门公开资源、私有 Tracker、机械盘、NVMe 和不同线路的合理设置差异很大。

限速时注意单位：qBittorrent 常以 KiB/s 显示，而 VPS 套餐常用 Mbps。近似换算为：

10 Mbps ≈ 1.19 MiB/s
100 Mbps ≈ 11.92 MiB/s

上传限制不能低到几乎无法回传协议数据，否则下载表现也可能受到影响。调整后至少观察一段完整业务周期，而不是只看几分钟峰值。

latest 标签便于跟随稳定版本，但更新前仍要看变更说明、备份配置并记录当前镜像摘要：

cd /opt/qbittorrent
docker compose images
docker image inspect lscr.io/linuxserver/qbittorrent:latest \
  --format '{{index .RepoDigests 0}}'
docker compose logs --tail=100 qbittorrent

备份配置后更新：

backup_stamp=$(date +%Y%m%d-%H%M%S)
docker compose stop qbittorrent
sudo tar -C /opt/qbittorrent -czf \
  "/root/qbittorrent-config-${backup_stamp}.tar.gz" \
  config compose.yaml .env
docker compose start qbittorrent

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 qbittorrent

更新后检查 WebUI 登录、任务列表、下载目录、监听端口和实际 Peer 连接。不要在任务大量写盘时直接强制终止容器。

若新镜像出现问题，可使用更新前记录的 digest 临时固定镜像，恢复配置备份后重新创建容器。镜像回滚和数据配置回滚是两件事：只换旧镜像不一定能读取新版本已经迁移过的配置，因此备份必须发生在更新前。

优先备份 /opt/qbittorrent/config，其中通常包含设置、任务状态、分类、标签和 fastresume 数据。下载文件是否备份取决于它们能否重新获取，以及你是否有权保存和分发。

建议分层：

• 配置目录：每天备份，保留多个版本；
• 自己创作或不可替代的文件：使用独立备份，不把做种副本当唯一备份；
• 可重新获取的公开镜像：可以只保留任务状态与校验信息；
• 大容量下载目录：先计算备份存储和出站费用，再决定策略。

备份完成后必须做恢复演练。可参考VPS 备份恢复演练教程，但不要把包含私有 Tracker 凭据或下载历史的配置包上传到公开存储。

• VPS 服务条款允许合法 BitTorrent/P2P 使用；
• 只处理有权下载、保存和分发的内容；
• WebUI 的 8080 只绑定 127.0.0.1；
• 公网管理入口使用域名 HTTPS；
• 已替换临时密码，并使用独立强密码；
• CSRF、clickjacking 和 Host Header Validation 保持开启；
• 没有配置大范围免认证子网；
• Peer 端口同时开放 TCP 和 UDP，WebUI 端口未开放；
• PUID、PGID 和下载目录权限一致，没有使用 777；
• Docker 日志设置轮转，磁盘与 inode 都有告警；
• 上传速度、并发任务和连接数不会长期压满服务器；
• 配置目录已备份，并实际测试过恢复；
• 更新前记录镜像摘要，检查官方 Release Notes；
• 私有 Tracker 地址、Cookie、下载历史和配置备份没有泄露。

• qBittorrent 官方网站与新闻
• qBittorrent GitHub Releases
• qBittorrent WebUI 密码恢复说明
• LinuxServer qBittorrent 容器文档