引言
qBittorrent 作为一款开源的 BitTorrent 客户端,凭借其轻量、无广告和跨平台的特性,深受用户喜爱。然而,当你需要管理多个 qBittorrent 实例时,在不同的 Web UI 之间来回切换就会变得非常繁琐。
正是为了解决这个痛点而诞生的现代化管理界面。它不仅提供了统一的多实例管理能力,还带来了更现代化的用户体验、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 提供了更加现代化和美观的界面:
- 响应式设计,完美适配桌面和移动设备
- 流畅的动画和交互效果
- 直观的信息展示,一目了然
- 支持拖放操作,自定义列顺序
- 键盘快捷键支持,提高操作效率
最最最重要的一点：如果你用过原版UI，可以发现他经常大批量种子卡死的情况。（PT 玩家肯定知道我在说什么）
UI 预览和使用
主页
登录注册页面
添加节点页面
种子页面
管理页面
工具页面
部署方式
qBitWebUI 提供了多种部署方式,这里介绍两种最便捷的方法:Docker Compose 和 Dokploy 一键部署。
方式一: Docker Compose 部署
1. 创建 docker-compose.yml
首先创建一个目录用于存放配置文件,然后创建 docker-compose.yml:
YAML
1version: "3.8"
2
3services:
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
40volumes:
41 qbitwebui_data:2. 生成加密密钥
ENCRYPTION_KEY 是必需的环境变量,用于加密存储 qBittorrent 的连接凭证。你可以使用以下命令生成一个安全的密钥:
Bash
1openssl rand -hex 32将生成的密钥替换 docker-compose.yml 中的 your-secret-key-min-32-chars-long。
3. 启动服务
Bash
1docker-compose up -d4. 访问界面
启动后,在浏览器中访问 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),等待合并后可以直接在模板市场中找到。在此之前,你也可以手动导入模板配置。
复制下面的导入
Bash
1ewogICJjb21wb3NlIjogInZlcnNpb246IFwiMy44XCJcblxuc2VydmljZXM6XG4gIHFiaXR3ZWJ1aTpcbiAgICBpbWFnZTogZ2hjci5pby9tYWNpZWpvbm9zL3FiaXR3ZWJ1aTpsYXRlc3RcbiAgICByZXN0YXJ0OiB1bmxlc3Mtc3RvcHBlZFxuICAgIGVudmlyb25tZW50OlxuICAgICAgIyBSZXF1aXJlZDogRW5jcnlwdGlvbiBrZXkgZm9yIHN0b3JpbmcgY3JlZGVudGlhbHMgKG1pbiAzMiBjaGFycylcbiAgICAgIC0gRU5DUllQVElPTl9LRVk9JHtFTkNSWVBUSU9OX0tFWX1cbiAgICAgICMgT3B0aW9uYWw6IFNlcnZlciBwb3J0IChkZWZhdWx0OiAzMDAwKVxuICAgICAgLSBQT1JUPSR7UE9SVDotMzAwMH1cbiAgICAgICMgT3B0aW9uYWw6IERhdGFiYXNlIGxvY2F0aW9uIChkZWZhdWx0OiAuL2RhdGEvcWJpdHdlYnVpLmRiKVxuICAgICAgLSBEQVRBQkFTRV9QQVRIPSR7REFUQUJBU0VfUEFUSDotL2RhdGEvcWJpdHdlYnVpLmRifVxuICAgICAgIyBPcHRpb25hbDogU2FsdCBmaWxlIGxvY2F0aW9uIChkZWZhdWx0OiAuL2RhdGEvLnNhbHQpXG4gICAgICAtIFNBTFRfUEFUSD0ke1NBTFRfUEFUSDotL2RhdGEvLnNhbHR9XG4gICAgICAjIE9wdGlvbmFsOiBBbGxvdyBzZWxmLXNpZ25lZCBjZXJ0aWZpY2F0ZXMgZm9yIHFCaXR0b3JyZW50IGluc3RhbmNlcyAoZGVmYXVsdDogZmFsc2UpXG4gICAgICAjIC0gQUxMT1dfU0VMRl9TSUdORURfQ0VSVFM9JHtBTExPV19TRUxGX1NJR05FRF9DRVJUUzotZmFsc2V9XG4gICAgICAjIE9wdGlvbmFsOiBEaXNhYmxlIGF1dGhlbnRpY2F0aW9uL2xvZ2luIChzaW5nbGUtdXNlciBtb2RlKSAoZGVmYXVsdDogZmFsc2UpXG4gICAgICAjIC0gRElTQUJMRV9BVVRIPSR7RElTQUJMRV9BVVRIOi1mYWxzZX1cbiAgICAgICMgT3B0aW9uYWw6IERpc2FibGUgbmV3IHJlZ2lzdHJhdGlvbnMsIGNyZWF0ZXMgZGVmYXVsdCBhZG1pbiBhY2NvdW50IChkZWZhdWx0OiBmYWxzZSlcbiAgICAgICMgLSBESVNBQkxFX1JFR0lTVFJBVElPTj0ke0RJU0FCTEVfUkVHSVNUUkFUSU9OOi1mYWxzZX1cbiAgICAgICMgT3B0aW9uYWw6IEVuYWJsZSBmaWxlIGJyb3dzZXIgYnkgc2V0dGluZyBkb3dubG9hZHMgcGF0aFxuICAgICAgIyAtIERPV05MT0FEU19QQVRIPS9kb3dubG9hZHNcbiAgICB2b2x1bWVzOlxuICAgICAgLSBxYml0d2VidWlfZGF0YTovZGF0YVxuICAgICAgIyBPcHRpb25hbDogTW91bnQgZG93bmxvYWRzIGRpcmVjdG9yeSBmb3IgZmlsZSBicm93c2VyIGZlYXR1cmVcbiAgICAgICMgUmVhZC1vbmx5IG1vdW50IChicm93c2UgJiBkb3dubG9hZCBvbmx5KTpcbiAgICAgICMgLSAvcGF0aC90by95b3VyL2Rvd25sb2FkczovZG93bmxvYWRzOnJvXG4gICAgICAjIE9yIHJlYWQtd3JpdGUgbW91bnQgKGVuYWJsZXMgZGVsZXRlL21vdmUvY29weS9yZW5hbWUpOlxuICAgICAgIyAtIC9wYXRoL3RvL3lvdXIvZG93bmxvYWRzOi9kb3dubG9hZHNcbiAgICBoZWFsdGhjaGVjazpcbiAgICAgIHRlc3Q6IFtcIkNNRFwiLCBcIndnZXRcIiwgXCItLW5vLXZlcmJvc2VcIiwgXCItLXRyaWVzPTFcIiwgXCItLXNwaWRlclwiLCBcImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMFwiXVxuICAgICAgaW50ZXJ2YWw6IDMwc1xuICAgICAgdGltZW91dDogNXNcbiAgICAgIHJldHJpZXM6IDNcbiAgICAgIHN0YXJ0X3BlcmlvZDogMTBzXG5cbnZvbHVtZXM6XG4gIHFiaXR3ZWJ1aV9kYXRhOlxuIiwKICAiY29uZmlnIjogIlt2YXJpYWJsZXNdXG5tYWluX2RvbWFpbiA9IFwiJHtkb21haW59XCJcbmVuY3J5cHRpb25fa2V5ID0gXCIke3Bhc3N3b3JkOjMyfVwiXG5cbltjb25maWddXG5bW2NvbmZpZy5kb21haW5zXV1cbnNlcnZpY2VOYW1lID0gXCJxYml0d2VidWlcIlxucG9ydCA9IDMwMDBcbmhvc3QgPSBcIiR7bWFpbl9kb21haW59XCJcbnBhdGggPSBcIi9cIlxuXG5bY29uZmlnLmVudl1cbkVOQ1JZUFRJT05fS0VZID0gXCIke2VuY3J5cHRpb25fa2V5fVwiXG5QT1JUID0gXCIzMDAwXCJcbkRBVEFCQVNFX1BBVEggPSBcIi9kYXRhL3FiaXR3ZWJ1aS5kYlwiXG5TQUxUX1BBVEggPSBcIi9kYXRhLy5zYWx0XCJcbiIKfQ==如果你正在寻找一个更好的 qBittorrent 管理方案,qBitWebUI 绝对值得一试。
相关链接
- 项目地址: https://github.com/Maciejonos/qbitwebui
- Docker 镜像: ghcr.io/maciejonos/qbitwebui
- Dokploy 模板 PR: https://github.com/Dokploy/templates/pull/675
- 模板预览: qBitWebUI Template Preview
最后更新： 1月24日 09:12
