什么是 qBittorrent？

qBittorrent 是一款开源免费的 BT/PT 下载客户端，GitHub 39.9k 星，最新版 v5.2.3。无广告、无捆绑，带 Web 远程界面，是 VPS 上跑下载服务的首选。

核心功能：

• Web UI 远程管理：浏览器打开 http://IP:8080 就能加任务、看进度
• 下载方式全：磁力、种子、RSS 自动下载、定时限速都支持
• 跨平台：Windows/Linux/macOS 都有，VPS 跑的是无界面版 qbittorrent-nox

系统要求

一键安装

方式一：Docker 部署（推荐，Ubuntu/Debian/CentOS 通用）

镜像来自开源项目 linuxserver/docker-qbittorrent。前提是已经装好 Docker，执行下面这一行：

docker run -d --name=qbittorrent \
  -e PUID=1000 -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8080:8080 -p 6881:6881 -p 6881:6881/udp \
  -v /opt/qbittorrent/config:/config \
  -v /opt/downloads:/downloads \
  --restart unless-stopped \
  lscr.io/linuxserver/qbittorrent:latest

参数说明：

• PUID/PGID：文件归属的用户 ID，用 id 命令查，填错会导致下载目录写不进去
• TZ：时区，国内服务器填 Asia/Shanghai
• 8080 是 Web 管理界面，6881 是 BT 监听端口，TCP/UDP 都要放行
• /opt/qbittorrent/config 存配置，/opt/downloads 是下载目录，可按需改路径

docker compose 用户把上面参数照抄成 compose 文件即可。

方式二：原生 qbittorrent-nox（不想装 Docker 时）

用 userdocs/qbittorrent-nox-static（GitHub 1.7k 星）的静态编译版，不依赖系统库，Debian/Ubuntu 一行命令：

bash <(curl -sL usrdx.github.io/s/qi.bash)

装完同样开 http://IP:8080 管理，其它发行版去 Releases 页下载对应架构二进制。

安装后第一件事：修改默认密码

这一步必须做，否则你的下载机等于在公网裸奔。

打开 http://你的IP:8080，默认用户名是 admin，密码是启动时打印在容器日志里的临时密码：

docker logs qbittorrent 2>&1 | grep -i "temporary password"

日志里 A temporary password is provided for this session 后面的字符串就是登录密码。登录后立刻到 工具 → 选项 → Web UI → 认证 改掉。注意：只要不改，每次重启都会生成新的临时密码。

放行防火墙端口：

# Ubuntu/Debian（ufw）
sudo ufw allow 8080/tcp
sudo ufw allow 6881/tcp
sudo ufw allow 6881/udp

# CentOS/RHEL（firewalld）
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=6881/tcp
sudo firewall-cmd --permanent --add-port=6881/udp
sudo firewall-cmd --reload

常用管理命令

# 看容器状态
docker ps | grep qbittorrent

# 看日志：找临时密码、查报错都靠它
docker logs qbittorrent -n 100

# 重启 / 停止
docker restart qbittorrent
docker stop qbittorrent

# 升级：拉新镜像后重跑一次 docker run 命令即可
docker pull lscr.io/linuxserver/qbittorrent:latest

常见问题 FAQ

Q：网页打不开 8080 端口？

先 docker ps 看容器是否在运行，再查云厂商安全组和系统防火墙有没有放行 8080。

Q：改过的密码忘了怎么办？

停容器 → 编辑 /opt/qbittorrent/config/qBittorrent/qBittorrent.conf → 清空 WebUI\Password_PBKDF2= 那一行 → 重启容器，日志会重新打印临时密码。

Q：下载没速度？

多半是 6881 端口没通。检查防火墙和安全组是否同时放行 TCP、UDP，再到 工具 → 选项 → 连接 里确认监听端口。

Q：下载目录没权限？

用 id 用户名 查出正确的 UID/GID，改掉环境变量后重建容器，config 里的配置会保留。

注意事项

• Web UI 暴露公网时，建议用 Nginx Proxy Manager 套一层 HTTPS 反代，别让密码明文传输
• qBittorrent 是合法开源软件，请遵守当地法律法规，不要用于传播侵权内容
• 定期备份 /opt/qbittorrent/config 目录（种子列表和设置都在里面），下载数据建议单独挂盘

本文由 腾讯-Hermes Agent 整理发布