qBitWebUI：现代化的 qBittorrent 多实例管理界面

引言#

qBittorrent 作为一款开源的 BitTorrent 客户端,凭借其轻量、无广告和跨平台的特性,深受用户喜爱。然而,当你需要管理多个 qBittorrent 实例时,在不同的 Web UI 之间来回切换就会变得非常繁琐。

Maciejonos

qbitwebui

Waiting for api.github.com...

00K

Waiting...

qBitWebUI 正是为了解决这个痛点而诞生的现代化管理界面。它不仅提供了统一的多实例管理能力,还带来了更现代化的用户体验、PWA 支持、Prowlarr 集成等强大功能。

项目介绍#

qBitWebUI 是一个基于 Web 的 qBittorrent 管理工具,允许你从单一界面管理多个 qBittorrent 实例。项目采用现代化的技术栈构建,提供流畅的用户体验。

核心特性:

多实例管理 - 在一个界面中管理所有 qBittorrent 实例
实时监控 - 自动刷新种子状态和下载进度
安全认证 - AES-256-GCM 加密存储连接凭证
Prowlarr 集成 - 直接搜索索引器并添加种子
PWA 支持 - 可安装为移动应用,支持离线访问
多主题支持 - Catppuccin、Gruvbox、Dracula、Nord 等主题
文件浏览器 - 直接浏览和管理下载目录
RSS 管理 - 订阅 RSS 源并设置自动下载规则
高度可定制 - 自定义列布局、过滤器和显示选项

技术栈:

项目使用 React 19、TypeScript、Tailwind CSS v4、Vite、TanStack Query、Hono、SQLite 和 Bun 构建,确保了现代化的开发体验和优秀的性能表现。

核心优势#

多实例统一管理#

这是 qBitWebUI 最核心的功能。如果你有多台服务器运行 qBittorrent,传统方式需要记住每个实例的地址和端口,然后在浏览器标签页之间来回切换。qBitWebUI 让你可以:

在一个界面中添加和管理所有 qBittorrent 实例
快速切换不同实例,查看各自的下载状态
为每个实例设置独立的速度限制(全局和备用速度)
统一的操作体验,无需适应不同版本的 UI

现代化的用户界面#

相比 qBittorrent 原生的 Web UI,qBitWebUI 提供了更加现代化和美观的界面:

响应式设计,完美适配桌面和移动设备
流畅的动画和交互效果
直观的信息展示,一目了然
支持拖放操作,自定义列顺序
键盘快捷键支持,提高操作效率

TIP
最最最重要的一点：如果你用过原版UI，可以发现他经常大批量种子卡死的情况。（PT 玩家肯定知道我在说什么）

UI 预览和使用#

主页#

Homepage

登录注册页面#

添加节点页面#

Add node

种子页面#

seed

管理页面#

manager page

工具页面#

Tools

部署方式#

qBitWebUI 提供了多种部署方式,这里介绍两种最便捷的方法 Compose 和 Dokploy 一键部署。

方式一: Docker Compose 部署#

1. 创建 docker-compose.yml#

首先创建一个目录用于存放配置文件,然后创建 docker-compose.yml:

1
version: "3.8"
2

3
services:
4
  qbitwebui:
5
    image: ghcr.io/maciejonos/qbitwebui:latest
6
    restart: unless-stopped
7
    ports:
8
      - "3000:3000"
9
    environment:
10
      # 必需: 加密密钥,用于存储凭证(至少 32 个字符)
11
      - ENCRYPTION_KEY=your-secret-key-min-32-chars-long
12
      # 可选: 服务器端口(默认: 3000)
13
      - PORT=3000
14
      # 可选: 数据库位置(默认: ./data/qbitwebui.db)
15
      - DATABASE_PATH=/data/qbitwebui.db
16
      # 可选: Salt 文件位置(默认: ./data/.salt)
17
      - SALT_PATH=/data/.salt
18
      # 可选: 允许自签名证书(默认: false)
19
      # - ALLOW_SELF_SIGNED_CERTS=false
20
      # 可选: 禁用认证/登录,单用户模式(默认: false)
21
      # - DISABLE_AUTH=false
22
      # 可选: 禁用新用户注册,创建默认管理员账户(默认: false)
23
      # - DISABLE_REGISTRATION=false
24
      # 可选: 启用文件浏览器,设置下载路径
25
      # - DOWNLOADS_PATH=/downloads
26
    volumes:
27
      - qbitwebui_data:/data
28
      # 可选: 挂载下载目录以启用文件浏览器功能
29
      # 只读挂载(仅浏览和下载):
30
      # - /path/to/your/downloads:/downloads:ro
31
      # 读写挂载(允许删除/移动/复制/重命名):
32
      # - /path/to/your/downloads:/downloads
33
    healthcheck:
34
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
35
      interval: 30s
36
      timeout: 5s
37
      retries: 3
38
      start_period: 10s
39

40
volumes:
41
  qbitwebui_data:

2. 生成加密密钥#

ENCRYPTION_KEY 是必需的环境变量,用于加密存储 qBittorrent 的连接凭证。你可以使用以下命令生成一个安全的密钥:

1
openssl rand -hex 32

将生成的密钥替换 docker-compose.yml 中的 your-secret-key-min-32-chars-long。

3. 启动服务#

1
docker-compose up -d

4. 访问界面#

启动后,在浏览器中访问 http://your-server-ip:3000,首次访问会提示注册账户。

5. 添加 qBittorrent 实例#

登录后,点击添加实例按钮,填写以下信息:

名称: 给实例起个名字(如 “家庭 NAS”)
URL: qBittorrent Web UI 地址(如 http://192.168.1.100:8080)
用户名: qBittorrent 的用户名
密码: qBittorrent 的密码

保存后即可开始管理该实例。

方式二: Dokploy 一键部署#

Dokploy 是一个开源的 PaaS 平台,类似于 Vercel/Netlify,但可以自托管。如果你已经在使用 Dokploy,可以通过导入模板的方式一键部署 qBitWebUI。

使用模板部署#

注: Dokploy 模板目前已提交到官方模板库(PR #675),等待合并后可以直接在模板市场中找到。在此之前,你也可以手动导入模板配置。

dokply import

复制下面的导入

1
ewogICJjb21wb3NlIjogInZlcnNpb246IFwiMy44XCJcblxuc2VydmljZXM6XG4gIHFiaXR3ZWJ1aTpcbiAgICBpbWFnZTogZ2hjci5pby9tYWNpZWpvbm9zL3FiaXR3ZWJ1aTpsYXRlc3RcbiAgICByZXN0YXJ0OiB1bmxlc3Mtc3RvcHBlZFxuICAgIGVudmlyb25tZW50OlxuICAgICAgIyBSZXF1aXJlZDogRW5jcnlwdGlvbiBrZXkgZm9yIHN0b3JpbmcgY3JlZGVudGlhbHMgKG1pbiAzMiBjaGFycylcbiAgICAgIC0gRU5DUllQVElPTl9LRVk9JHtFTkNSWVBUSU9OX0tFWX1cbiAgICAgICMgT3B0aW9uYWw6IFNlcnZlciBwb3J0IChkZWZhdWx0OiAzMDAwKVxuICAgICAgLSBQT1JUPSR7UE9SVDotMzAwMH1cbiAgICAgICMgT3B0aW9uYWw6IERhdGFiYXNlIGxvY2F0aW9uIChkZWZhdWx0OiAuL2RhdGEvcWJpdHdlYnVpLmRiKVxuICAgICAgLSBEQVRBQkFTRV9QQVRIPSR7REFUQUJBU0VfUEFUSDotL2RhdGEvcWJpdHdlYnVpLmRifVxuICAgICAgIyBPcHRpb25hbDogU2FsdCBmaWxlIGxvY2F0aW9uIChkZWZhdWx0OiAuL2RhdGEvLnNhbHQpXG4gICAgICAtIFNBTFRfUEFUSD0ke1NBTFRfUEFUSDotL2RhdGEvLnNhbHR9XG4gICAgICAjIE9wdGlvbmFsOiBBbGxvdyBzZWxmLXNpZ25lZCBjZXJ0aWZpY2F0ZXMgZm9yIHFCaXR0b3JyZW50IGluc3RhbmNlcyAoZGVmYXVsdDogZmFsc2UpXG4gICAgICAjIC0gQUxMT1dfU0VMRl9TSUdORURfQ0VSVFM9JHtBTExPV19TRUxGX1NJR05FRF9DRVJUUzotZmFsc2V9XG4gICAgICAjIE9wdGlvbmFsOiBEaXNhYmxlIGF1dGhlbnRpY2F0aW9uL2xvZ2luIChzaW5nbGUtdXNlciBtb2RlKSAoZGVmYXVsdDogZmFsc2UpXG4gICAgICAjIC0gRElTQUJMRV9BVVRIPSR7RElTQUJMRV9BVVRIOi1mYWxzZX1cbiAgICAgICMgT3B0aW9uYWw6IERpc2FibGUgbmV3IHJlZ2lzdHJhdGlvbnMsIGNyZWF0ZXMgZGVmYXVsdCBhZG1pbiBhY2NvdW50IChkZWZhdWx0OiBmYWxzZSlcbiAgICAgICMgLSBESVNBQkxFX1JFR0lTVFJBVElPTj0ke0RJU0FCTEVfUkVHSVNUUkFUSU9OOi1mYWxzZX1cbiAgICAgICMgT3B0aW9uYWw6IEVuYWJsZSBmaWxlIGJyb3dzZXIgYnkgc2V0dGluZyBkb3dubG9hZHMgcGF0aFxuICAgICAgIyAtIERPV05MT0FEU19QQVRIPS9kb3dubG9hZHNcbiAgICB2b2x1bWVzOlxuICAgICAgLSBxYml0d2VidWlfZGF0YTovZGF0YVxuICAgICAgIyBPcHRpb25hbDogTW91bnQgZG93bmxvYWRzIGRpcmVjdG9yeSBmb3IgZmlsZSBicm93c2VyIGZlYXR1cmVcbiAgICAgICMgUmVhZC1vbmx5IG1vdW50IChicm93c2UgJiBkb3dubG9hZCBvbmx5KTpcbiAgICAgICMgLSAvcGF0aC90by95b3VyL2Rvd25sb2FkczovZG93bmxvYWRzOnJvXG4gICAgICAjIE9yIHJlYWQtd3JpdGUgbW91bnQgKGVuYWJsZXMgZGVsZXRlL21vdmUvY29weS9yZW5hbWUpOlxuICAgICAgIyAtIC9wYXRoL3RvL3lvdXIvZG93bmxvYWRzOi9kb3dubG9hZHNcbiAgICBoZWFsdGhjaGVjazpcbiAgICAgIHRlc3Q6IFtcIkNNRFwiLCBcIndnZXRcIiwgXCItLW5vLXZlcmJvc2VcIiwgXCItLXRyaWVzPTFcIiwgXCItLXNwaWRlclwiLCBcImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMFwiXVxuICAgICAgaW50ZXJ2YWw6IDMwc1xuICAgICAgdGltZW91dDogNXNcbiAgICAgIHJldHJpZXM6IDNcbiAgICAgIHN0YXJ0X3BlcmlvZDogMTBzXG5cbnZvbHVtZXM6XG4gIHFiaXR3ZWJ1aV9kYXRhOlxuIiwKICAiY29uZmlnIjogIlt2YXJpYWJsZXNdXG5tYWluX2RvbWFpbiA9IFwiJHtkb21haW59XCJcbmVuY3J5cHRpb25fa2V5ID0gXCIke3Bhc3N3b3JkOjMyfVwiXG5cbltjb25maWddXG5bW2NvbmZpZy5kb21haW5zXV1cbnNlcnZpY2VOYW1lID0gXCJxYml0d2VidWlcIlxucG9ydCA9IDMwMDBcbmhvc3QgPSBcIiR7bWFpbl9kb21haW59XCJcbnBhdGggPSBcIi9cIlxuXG5bY29uZmlnLmVudl1cbkVOQ1JZUFRJT05fS0VZID0gXCIke2VuY3J5cHRpb25fa2V5fVwiXG5QT1JUID0gXCIzMDAwXCJcbkRBVEFCQVNFX1BBVEggPSBcIi9kYXRhL3FiaXR3ZWJ1aS5kYlwiXG5TQUxUX1BBVEggPSBcIi9kYXRhLy5zYWx0XCJcbiIKfQ==

如果你正在寻找一个更好的 qBittorrent 管理方案,qBitWebUI 绝对值得一试。

qBitWebUI：现代化的 qBittorrent 多实例管理界面

引言#

项目介绍#

核心优势#

多实例统一管理#

现代化的用户界面#

UI 预览和使用#

主页#

登录注册页面#

添加节点页面#

种子页面#

管理页面#

工具页面#

部署方式#

方式一: Docker Compose 部署#

1. 创建 docker-compose.yml#

2. 生成加密密钥#

3. 启动服务#

4. 访问界面#

5. 添加 qBittorrent 实例#

方式二: Dokploy 一键部署#

使用模板部署#

相关链接#