以下是适配 Debian 13 VPS 环境 的 qBittorrent Docker 部署版 docker-compose.yml
它包含了：
✅ 持久化配置与下载目录映射
✅ 合理的权限与 PUID/PGID 配置
✅ 预设 WebUI 中文、端口与时区
✅ 目录结构清晰（含分类：music、movie、game）
✅ 自启动与重启策略
✅ 可直接运行、长期稳定使用
一、目录结构建议
在你的 VPS 用户主目录下创建这些文件夹：
mkdir -p /opt/qbittorrent/{config,downloads/{music,movie,game}}二、docker-compose.yml 完整内容
services:
qbittorrent:
image: linuxserver/qbittorrent:latest
container_name: qbittorrent
restart: unless-stopped
network_mode: bridge
ports:
- "8080:8080" # WebUI
- "6881:6881" # TCP
- "6881:6881/udp" # UDP
environment:
- PUID=1000 # 宿主机用户ID（用 id 命令查看）
- PGID=1000 # 宿主机用户组ID
- TZ=Asia/Shanghai # 时区
- WEBUI_PORT=8080
- TORRENTING_PORT=6881
- LANG=zh_CN.UTF-8 # WebUI语言（中文）
- UMASK_SET=022 # 控制文件权限
volumes:
- /opt/qbittorrent/config:/config
- /opt/qbittorrent/downloads:/downloads
healthcheck:
test: ["CMD-SHELL", "wget -q --spider http://localhost:8080 || exit 1"] # 健康检查
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
三、部署步骤
1.保存文件
nano /opt/qbittorrent/docker-compose.yml粘贴上面配置内容。
2.启动服务
cd /opt/qbittorrent
sudo docker compose up -d3.查看状态
sudo docker ps出现 qbittorrent 容器即表示运行成功。
4.访问 WebUI
浏览器打开：
http://你的服务器IP:8080默认登录：
用户名：admin
密码：LinuxServer 的 qBittorrent 镜像默认密码是随机生成的
查看容器日志找密码：
docker logs qbittorrent在日志中寻找类似这样的行：
root@vps ~ # docker logs qbittorrent
[migrations] started
[migrations] no migrations found
───────────────────────────────────────
██╗ ███████╗██╗ ██████╗
██║ ██╔════╝██║██╔═══██╗
██║ ███████╗██║██║ ██║
██║ ╚════██║██║██║ ██║
███████╗███████║██║╚██████╔╝
╚══════╝╚══════╝╚═╝ ╚═════╝
Brought to you by linuxserver.io
───────────────────────────────────────
To support LSIO projects visit:
https://www.linuxserver.io/donate/
───────────────────────────────────────
GID/UID
───────────────────────────────────────
User UID: 0
User GID: 0
───────────────────────────────────────
Linuxserver.io version: 5.1.2-r3-ls422
Build-date: 2025-10-26T06:58:02+00:00
───────────────────────────────────────
[custom-init] No custom files found, skipping...
WebUI 将在内部准备不久后启动。请稍等…
******** 信息 ********
要控制 qBittorrent，请访问下列地址的 WebUI：http://localhost:8080
WebUI 管理员用户名是：admin
未设置 WebUI 管理员密码。为此会话提供了一个临时密码：SHvLxTp96
你应该在程序首选项中设置你自己的密码5.首次登录后立即修改密码！
四、权限确认（重要）
若容器启动时报权限错误，可执行：
sudo chown -R 1000:1000 /opt/qbittorrent
sudo chmod -R 755 /opt/qbittorrent如果你想使用当前用户权限（非 root），先确认：
id例如输出：
uid=1000(youruser) gid=1000(youruser)则 PUID=1000, PGID=1000 即正确。
五、后期维护与更新
✅ 更新容器
cd /opt/qbittorrent
sudo docker compose pull
sudo docker compose up -d✅ 停止 / 启动 / 查看日志
sudo docker compose stop
sudo docker compose start
sudo docker compose logs -f六、可选增强建议（HTTPS / 域名访问）
HTTPS / 域名访问 用 Nginx/acme 反向代理 qBittorrent WebUI
1.前提条件确认
- 你的域名 qb.example.com 已在 Cloudflare DNS 中添加一条 A 记录、AAAA（如果 IPv6 稳定）记录，指向你的 VPS IP。
- Cloudflare 的小云朵是“灰色云（仅DNS模式）”，不要先启用代理（橙色云），否则 TLS 验证会失败。
- VPS 上安装了 Nginx acme（如果没有先安装）：
sudo apt update
sudo apt install -y nginx acme2.使用 acme.sh 申请证书
1️⃣ 设置 Cloudflare API 环境变量（仅需一次）
export CF_Account_ID="你的Cloudflare Account_ID"
export CF_Token="你的Cloudflare API_Token"
export CF_Zone_ID="你的Cloudflare Zone_ID" # 可选但推荐2️⃣ 申请证书
acme.sh --issue --dns dns_cf -d qb.example.com --keylength ec-256成功后会提示：
Your cert is in: /root/.acme.sh/qb.example.com/qb.example.com.cer
Your key is in: /root/.acme.sh/qb.example.com/qb.example.com.key3️⃣ 安装证书到 Nginx 目录（可选，下文不需要这步）
sudo mkdir -p /etc/nginx/ssl/qb.example.com
acme.sh --install-cert -d qb.example.com --ecc \
--key-file /etc/nginx/ssl/qb.example.com/key.pem \
--fullchain-file /etc/nginx/ssl/qb.example.com/fullchain.pem \
--reloadcmd "systemctl reload nginx"3.配置 Nginx 反向代理（IPv4 + IPv6 + HTTPS）
- 编辑配置文件：
sudo nano /etc/nginx/sites-available/qbittorrent.conf- 填入以下 配置模板👇
server {
listen 80;
listen [::]:80;
server_name qb.example.com;
# 自动跳转到 HTTPS
return 301 https://$host$request_uri;
}
# ========================
# HTTPS 主服务
# ========================
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on; # 修正 http2 警告
server_name qb.example.com;
# SSL 证书路径（根据 acme.sh 安装路径）
ssl_certificate /root/.acme.sh/qb.example.com_ecc/fullchain.cer;
ssl_certificate_key /root/.acme.sh/qb.example.com_ecc/qb.example.com.key;
# TLS 配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
# 禁用 OCSP stapling（避免警告）
ssl_stapling off;
ssl_stapling_verify off;
# 安全头部
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;
# 客户端和代理优化
client_max_body_size 0; # qBittorrent 需要无限制上传
proxy_read_timeout 600s;
proxy_connect_timeout 60s;
proxy_send_timeout 300s;
# gzip 压缩优化（可选，提高访问速度）
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
gzip_min_length 256;
gzip_comp_level 5;
location / {
proxy_pass http://127.0.0.1:8080; # qBittorrent WebUI 端口
proxy_http_version 1.1;
# 基本代理头
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
# WebSocket 支持
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 缓冲区关闭，防止下载中断
proxy_buffering off;
}
}
- 启用该配置：
sudo ln -s /etc/nginx/sites-available/qbittorrent.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx4.测试与验证
- 浏览器访问：👉 https://qb.example.com
- 确认证书正常、页面加载 HTTPS 🔒
- 查看 Nginx 日志：sudo tail -f /var/log/nginx/access.log /var/log/nginx/error.log
- 自动续期任务由 acme.sh –cron 自动处理。