qBittorrent Next UI

面向 qBittorrent 的现代化、响应式第三方网页界面

项目简介

qBittorrent Next UI 使用 React、Vite、Tailwind CSS 与 shadcn/ui 构建，通过 qBittorrent Web API v2 提供完整的种子管理体验。它可以作为 qBittorrent 的备用网页界面部署，也可以由独立网页服务器托管。

本项目由 Transmission Next UI 改造而来，保留原项目优秀的响应式布局与交互方式，并将后端通信层替换为 qBittorrent Web API。

当前版本为早期可用版本。建议首次部署时保留一个已登录的原生网页界面页面，确认备用界面可用后再关闭。

功能

任务管理

列表与网格两种视图
搜索、状态、Tracker、目录与标签筛选
启动、停止、删除、重新校验与重新汇报
添加磁力链接和多个种子文件
重命名、移动目录、限速与分享率限制
批量移动、批量标签与批量替换 Tracker

详情与状态

查看种子属性、文件、Peer 与 Tracker
展示全局上传、下载速度和磁盘剩余空间
映射 qBittorrent 下载、做种、排队、校验与错误状态
支持自动刷新与备用速度限制模式

使用体验

桌面端、平板与移动端响应式布局
深色与浅色主题
简体中文与英文界面
Cookie 会话登录和自动验证
qBittorrent 5 的启动、停止接口，并兼容 qBittorrent 4 的旧接口

安装

qBittorrent Next UI 构建后是一组纯静态网页文件，不需要在服务器上持续运行 Node.js。推荐按下面的顺序选择安装方式：

推荐顺序	安装方式	独立访问端口	是否修改 qBittorrent 备用界面	适合场景
1	Docker + Nginx 独立部署	是	否	NAS、Docker、希望新版与原生界面并存，推荐大多数用户使用
2	直接导入 qBittorrent WebUI	否	是	希望直接替换 qBittorrent 原生界面，部署步骤最少
3	从源码构建	取决于部署方式	取决于部署方式	开发、二次修改或需要构建最新 `main` 分支

推荐先使用方式一。即使新版界面配置错误，仍可通过 qBittorrent 原生端口进入原生界面，排查和回滚更方便。

推荐安装方式一：Docker + Nginx 独立部署（推荐）

这种方式由 Nginx 容器提供 WebUI 静态文件，并把同源 /api/v2/ 请求转发给 qBittorrent。新版界面和 qBittorrent 原生界面使用不同端口，可以同时保留。

浏览器
  └─ Nginx WebUI 端口
       ├─ /          → WebUI 静态文件
       └─ /api/v2/   → qBittorrent Web API

这种方式不会修改 qBittorrent 的备用界面设置，也不需要关闭浏览器跨域保护。

第一步：准备目录和发行版

mkdir -p qbittorrent-next-ui-nginx/webui
cd qbittorrent-next-ui-nginx
curl -L https://github.com/cainiao524/qbittorrent-next-ui/releases/latest/download/qbittorrent-next-ui.zip -o qbittorrent-next-ui.zip
unzip qbittorrent-next-ui.zip -d webui

最终目录结构：

qbittorrent-next-ui-nginx/
├─ docker-compose.yml
├─ nginx.conf
└─ webui/
   ├─ index.html
   └─ assets/

第二步：确认 qBittorrent 的 Docker 网络

如果 qBittorrent 已经在 Docker 中运行，先查看它所在的网络：

docker inspect qbittorrent --format '{{range $name, $_ := .NetworkSettings.Networks}}{{$name}}{{"\n"}}{{end}}'

假设输出为 qbittorrent_default。nginx 加入这个网络后，就能通过容器名 qbittorrent 访问 qBittorrent 的 WebUI 端口。

第三步：创建 `docker-compose.yml`

services:
  webui:
    image: nginx:alpine
    container_name: qbittorrent-next-ui
    ports:
      - "8098:80"
    volumes:
      - ./webui:/usr/share/nginx/html:ro
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    networks:
      - qbittorrent_network
    restart: unless-stopped

networks:
  qbittorrent_network:
    external: true
    name: qbittorrent_default

把最后一行的 qbittorrent_default 改成上一步查询到的真实网络名。8098 是新界面对外访问端口，可以改成其他未占用端口。

第四步：创建 `nginx.conf`

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;
    client_max_body_size 100M;

    location /api/ {
        proxy_pass http://qbittorrent:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $proxy_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;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

这里的 qbittorrent 是 qBittorrent 容器名，8080 是容器内部 WebUI 端口。如果你的容器名称或内部端口不同，请同步修改 proxy_pass。

proxy_pass 不要附加 /api/ 或 /api/v2/。当前写法会原样保留请求路径，例如 /api/v2/auth/login 会被正确转发到 qBittorrent。

qBittorrent 在宿主机或另一台服务器时

如果 qBittorrent 不在同一个 Docker 网络中，可以删除 Compose 文件中的 networks 配置，并在服务中增加：

    extra_hosts:
      - "host.docker.internal:host-gateway"

然后把 nginx 配置改成宿主机地址：

proxy_pass http://host.docker.internal:8080;

qBittorrent 位于另一台设备时，直接使用它的局域网地址，例如：

proxy_pass http://192.0.2.20:8080;

192.0.2.20 是保留的文档示例地址，请替换成 qBittorrent 设备的真实局域网地址。请确保 qBittorrent WebUI 监听地址允许 nginx 所在设备访问，并且防火墙已放行对应端口。

第五步：启动并验证

docker compose config
docker compose up -d
docker ps --filter name=qbittorrent-next-ui
curl -I http://127.0.0.1:8098/
curl -i http://127.0.0.1:8098/api/v2/app/version

页面请求应返回 200。
API 请求在未登录时可能返回 403，这表示代理已经连通且 qBittorrent 正在要求认证。
502 Bad Gateway 表示 nginx 无法连接 proxy_pass 指定的地址，应检查容器名、网络和端口。

验证完成后访问：

http://服务器地址:8098

使用 qBittorrent WebUI 的用户名和密码登录。此部署方式不需要在 qBittorrent 中启用“备用网页用户界面”。

更新 WebUI

先解压到新目录并保留旧版，确认文件完整后再切换：

curl -L https://github.com/cainiao524/qbittorrent-next-ui/releases/latest/download/qbittorrent-next-ui.zip -o qbittorrent-next-ui.zip
mkdir webui-new
unzip qbittorrent-next-ui.zip -d webui-new
mv webui "webui.backup.$(date +%Y%m%d-%H%M%S)"
mv webui-new webui
chmod -R a+rX webui
docker restart qbittorrent-next-ui

常见问题

现象	检查方法
页面返回 `403`	确认 `webui/` 及其中所有文件对 nginx 容器可读，可执行 `chmod -R a+rX webui`
API 返回 `502`	检查 `proxy_pass`、qBittorrent 容器名、内部端口和 Docker 网络
登录一直失败	使用 qBittorrent 原生 WebUI 的账户；检查 qBittorrent 日志和主机头验证设置
页面仍是旧版本	强制刷新浏览器，或清除该站点缓存后重新打开
上传种子失败	确认 nginx 已设置足够大的 `client_max_body_size`

不要在没有 HTTPS 和强密码保护的情况下把此端口直接暴露到公网。公网访问建议在外层增加可信反向代理、TLS 证书和访问控制。

推荐安装方式二：直接导入 qBittorrent WebUI

这种方式把发行版文件设置为 qBittorrent 的备用网页用户界面。访问地址和端口保持不变，但启用后会直接替换原生界面，不需要额外运行 Nginx 容器。

第一步：下载并解压发行版

打开 Releases 页面，下载 qbittorrent-next-ui.zip。也可以在 Linux 或 NAS 终端执行：

mkdir -p qbittorrent-next-ui-release
cd qbittorrent-next-ui-release
curl -L https://github.com/cainiao524/qbittorrent-next-ui/releases/latest/download/qbittorrent-next-ui.zip -o qbittorrent-next-ui.zip
unzip qbittorrent-next-ui.zip -d webui

Windows PowerShell：

New-Item -ItemType Directory -Force qbittorrent-next-ui-release
Set-Location qbittorrent-next-ui-release
Invoke-WebRequest -Uri "https://github.com/cainiao524/qbittorrent-next-ui/releases/latest/download/qbittorrent-next-ui.zip" -OutFile "qbittorrent-next-ui.zip"
Expand-Archive -Path "qbittorrent-next-ui.zip" -DestinationPath "webui"

解压后的 webui/ 应直接包含 index.html、assets/ 和字体等静态文件。

第二步 A：Docker 版 qBittorrent

把解压目录只读挂载到 qBittorrent 容器内的 /webui。以下为 LinuxServer.io 镜像示例：

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    volumes:
      - ./config:/config
      - ./downloads:/downloads
      - ./qbittorrent-next-ui-release/webui:/webui:ro

重新创建容器使挂载生效：

docker compose up -d

然后在 qBittorrent 原生界面中完成启用：

打开“工具 → 选项 → 网页用户界面”。
启用“使用备用网页用户界面”。
备用网页界面文件路径填写 /webui。
保存设置并刷新浏览器。

第一次切换时建议保留一个已登录的原生界面页面。如果路径填写错误，可以关闭备用界面选项，或在停止 qBittorrent 后把配置文件中的 WebUI\AlternativeUIEnabled 改为 false。

第二步 B：非 Docker 版 qBittorrent

把 webui/ 放到 qBittorrent 运行用户有权读取的固定目录，例如 /opt/qbittorrent-next-ui，然后在“网页用户界面”设置中启用备用界面并填写该绝对路径：

sudo mkdir -p /opt/qbittorrent-next-ui
sudo cp -a webui/. /opt/qbittorrent-next-ui/
sudo chmod -R a+rX /opt/qbittorrent-next-ui

从源码构建（开发者）

环境要求

Git
Node.js 22 或更高版本
pnpm 10 或更高版本
qBittorrent 4.x 或 5.x

1. 获取源码并安装依赖

git clone https://github.com/cainiao524/qbittorrent-next-ui.git
cd qbittorrent-next-ui
pnpm install --frozen-lockfile

2. 检查并构建

pnpm typecheck
pnpm test
pnpm build

构建成功后，生产文件位于 dist/：

dist/
├─ index.html
└─ assets/

3. 部署构建结果

将 dist/ 中的全部文件复制到 qBittorrent 的备用网页界面目录，或复制到独立 nginx 的网页根目录。Docker 用户也可以直接使用仓库提供的 docker-compose.yml：

docker compose up -d

仓库中的 Compose 配置会把本地 dist/ 只读挂载到 qBittorrent 容器内的 /webui。首次启动后访问 http://服务器地址:8080，并在原生界面中把备用网页界面路径设置为 /webui。LinuxServer.io 镜像的临时管理员密码可通过以下命令查看：

docker compose logs qbittorrent

升级与回滚

发行版用户升级时，建议先保留旧目录，再解压新版本：

mv webui "webui.backup.$(date +%Y%m%d-%H%M%S)"
mkdir webui
unzip qbittorrent-next-ui.zip -d webui
docker restart qbittorrent

源码构建用户可以执行：

git pull --ff-only
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
docker restart qbittorrent

如果新版本出现问题，停止服务后把当前 webui 移走，再将最近的 webui.backup.* 改回 webui 即可回滚。

本地开发

pnpm install
pnpm dev

开发服务器默认将 /api 代理至 http://127.0.0.1:8080。qBittorrent 位于其他地址时，可在启动前设置：

VITE_QBITTORRENT_PROXY_TARGET=http://192.0.2.10:8080 pnpm dev

Windows PowerShell：

$env:VITE_QBITTORRENT_PROXY_TARGET = "http://192.0.2.10:8080"
pnpm dev

演示模式使用本地模拟数据，不会连接或修改真实 qBittorrent：

pnpm dev --mode demo

配置

环境变量	默认值	用途
`VITE_QBITTORRENT_API_URL`	`/api/v2`	前端调用的 qBittorrent Web API 前缀
`VITE_QBITTORRENT_PROXY_TARGET`	`http://127.0.0.1:8080`	开发服务器代理目标
`VITE_APP_DEMO`	`false`	是否使用本地模拟数据

作为 qBittorrent 备用网页界面部署时，通常应保留 VITE_QBITTORRENT_API_URL=/api/v2。

开发

常用命令

pnpm typecheck
pnpm test
pnpm build

生产构建结果位于 dist/。

关键目录

src/
├─ app/                 页面
├─ components/          界面组件
├─ hooks/               数据与交互逻辑
├─ lib/rpc-client.ts    qBittorrent Web API 适配层
├─ lib/rpc-client-mock.ts
└─ locales/             中英文翻译

接口兼容

界面层使用统一的种子模型，src/lib/rpc-client.ts 负责 qBittorrent 字段与接口转换，包括：

Cookie 会话认证
哈希标识与批量操作
状态字符串映射
文件、Peer、Tracker 和任务属性聚合
应用偏好与全局传输状态映射
qBittorrent 4 与 5 的操作接口兼容

接口实现参考 qBittorrent WebUI API 文档。

参与贡献

欢迎提交问题报告和合并请求。提交代码前请至少运行：

pnpm typecheck
pnpm test

许可证与来源

本项目沿用原项目的 MIT 许可证。二次分发时请保留许可证与来源说明。

上游界面：hisproc/transmission-next-ui
qBittorrent：qbittorrent/qBittorrent

Name		Name	Last commit message	Last commit date
Latest commit History 99 Commits
.github/workflows		.github/workflows
pic		pic
public		public
scripts		scripts
src		src
.env.demo		.env.demo
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
components.json		components.json
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation