大约 7 年前，我加入了 PT 站点。当时 NAS 上安装的是最新的 qB 4.1.9，没想到一直用到了今天。
曾经尝试过跨版本升级（印象中是 4.2.5），结果导致客户端里的种子任务丢失，无法正常保种。由于积累的种子太多，恢复起来非常麻烦，所以后来只要运行稳定，我就一直没有再升级。
不过现在手机使用越来越普遍。毕业参加工作之后，使用桌面端的时间越来越少，平时更多的是通过手机管理 NAS。原版 WebUI 在手机上的操作体验确实不太理想。我也尝试过一些其他的 Alternative WebUI，但很多对老版本 qB 的兼容性并不好。
为了解决这些问题，才做的这个项目。目前覆盖 qBittorrent 4.1.x 至 5.2.x 的多个稳定版本。如果遇到兼容性问题或有改进建议，也欢迎留言反馈。 项目地址
WeiG qB WebUI 是一套面向桌面和手机端的 qBittorrent Alternate WebUI：
- 📱 手机端自适应
- 🌙 暗夜模式
- 🧱 兼容较老版本的 qBittorrent
- ✅ 支持 qBittorrent 4.1.x → 5.2.x
- 🐳 适用于 Windows、Linux、Docker、NAS
界面预览
桌面端
手机端
新手安装
第一次安装？点击展开 1 分钟教程
1. 解压
下载最新正式版 weig-qb-webui.zip，解压后会直接得到统一目录：
weig-qb-webui/├── public/├── private/├── VERSION└── GIT_SHA整个 weig-qb-webui 文件夹就是 WebUI 根目录，不要只复制 public 或 private。
2. 放到一个固定位置
把整个 weig-qb-webui 文件夹移动到一个以后不会随便删除的位置，例如：
Windows：D:\weig-qb-webuiLinux： /opt/weig-qb-webui后面 qBittorrent 要填写的就是这个目录。
3. 在 qBittorrent 中启用
打开 qBittorrent：
工具 → 选项… → WebUI
- 勾选 使用备选 WebUI。
- 找到 文件位置：。
- 填入刚才保存的
weig-qb-webui文件夹路径。 - 点击 确定 保存设置。
- 刷新 qBittorrent WebUI 页面。如果浏览器仍显示旧页面，可再按一次
Ctrl + F5强制刷新。
Windows 示例：
D:\weig-qb-webui普通 Linux 示例：
/opt/weig-qb-webui怎么判断路径填对了？ 你填写的目录里面应该能直接看到
public、private、VERSION等文件/目录。如果还要再进入一层weig-qb-webui才能看到这些内容，说明路径多填或少填了一层。
Docker 用户注意： qBittorrent 运行在容器里面，因此这里通常不能填写宿主机上的真实路径。Docker 的“宿主机 / 容器”区别和正确路径写法见下面 Docker 折叠教程。
一键安装
Linux / NAS 一键脚本统一从下面的 Dev Pages 固定入口下载。脚本地址不决定安装通道： 不加 -dev 默认安装稳定 main（使用最新且经过校验的 GitHub Release）；加 -dev 才安装当前 dev exact-SHA。安装脚本会保存在当前目录，方便以后更新或回滚。
Linux / NAS
curl -fsSL https://weigefenxiang.github.io/WeiG-qB-WebUI/downloads/dev/install.sh -o install.sh && sh install.sh -configure查看脚本位置和 WebUI 默认安装目录
./install.shWebUI 本体默认安装到：
~/.local/share/weig-qb-webui例如使用 root 用户运行时，通常就是：
/root/.local/share/weig-qb-webuiDocker
Docker 一键安装 / 多容器 / 路径说明（新手建议展开）
先理解“宿主机”和“容器”
如果你是在 VPS、Linux 服务器、群晖、威联通等设备上运行 Docker：
- 宿主机：真正运行 Docker 的那台 Linux / NAS，也就是你 SSH 登录进去后看到的系统。
- 容器：Docker 给 qBittorrent 单独创建的运行环境。qBittorrent 只能直接看到容器里的路径。
例如 Docker 创建 qBittorrent 时有这样的目录映射：
宿主机：/root/qbittorrent/config ↓ 映射到容器内：/configDocker Compose 中常见写法类似：
volumes: - /root/qbittorrent/config:/config冒号左边 /root/qbittorrent/config 是宿主机路径，右边 /config 是容器内路径。
如果 WeiG qB WebUI 实际安装到了：
宿主机：/root/qbittorrent/config/weig-qb-webui那么 qBittorrent 的 文件位置： 应填写：
/config/weig-qb-webui**不要填写 /root/qbittorrent/config/weig-qb-webui**，因为 qBittorrent 容器通常看不到这个宿主机路径。
情况 1：只有一个 qBittorrent Docker 容器
最简单，直接运行：
curl -fsSL https://weigefenxiang.github.io/WeiG-qB-WebUI/downloads/dev/install.sh -o install.sh && sh install.sh -configure安装器会尝试自动找到正在运行的 qBittorrent 容器、识别它的 /config 映射，把 WebUI 安装到合适的位置，并自动设置 qBittorrent。
情况 2：先看看机器上有哪些 qBittorrent 容器
如果不确定容器叫什么：
sh install.sh --list-containers也可以先用 Docker 自己的命令查看正在运行的容器：
docker ps例如你看到 qBittorrent 容器名是：
qbittorrent就可以明确指定它：
sh install.sh --container=qbittorrent -configure情况 3：机器上有多个 qBittorrent 容器
例如同时有：
qbittorrentqbittorrent-test先运行：
sh install.sh --list-containers安装正式使用的 qbittorrent：
sh install.sh --container=qbittorrent -configure安装测试容器 qbittorrent-test：
sh install.sh --container=qbittorrent-test -configure安装器不会在多个 qBittorrent 容器之间随便猜一个。
情况 4：你知道 qBittorrent 的宿主机 /config 目录
例如你的 Docker 配置目录是：
/root/qbittorrent/config可以直接指定：
sh install.sh --config-root=/root/qbittorrent/config -configure群晖上可能类似：
sh install.sh --config-root=/volume1/docker/qbittorrent -configure其他 NAS 可能类似：
sh install.sh --config-root=/share/Container/qbittorrent -configure这些只是示例，请换成你自己的真实 qBittorrent /config 宿主机目录。
情况 5：指定 WebUI 安装目录
已经指定容器时，也可以指定容器里希望使用的 WebUI 路径：
sh install.sh --container=qbittorrent -o /config/weig-qb-webui -configure安装器会根据 Docker /config 映射换算成宿主机上的实际安装目录。
情况 6：一次更新多个现有 WebUI 目录
有多个 qBittorrent 实例时，可以重复写 -o。安装包只下载和校验一次，全部目标准备完成后才开始切换；每个目标都在 ~/.config/weig-qb-webui/backups/ 下独立保留最近 3 份备份。
sh install.sh -dev \ -o /root/qbittorrent/config/weig-qb-webui \ -o /root/qbittorrent3/config/weig-qb-webui多目标模式不要加 -configure，各个 qBittorrent 实例继续使用自己已经配置好的备选 WebUI 路径。查看当前参数可运行 sh install.sh -help。
安装后应该看到什么
安装成功时脚本会输出类似：
Host install path: /root/qbittorrent/config/weig-qb-webuiqBittorrent Root Folder: /config/weig-qb-webui含义是：
Host install path：文件真正保存到宿主机哪里；qBittorrent Root Folder：你在 qBittorrent 的“文件位置：”中应该填写的容器内路径。
如果用了 -configure 并成功找到 qBittorrent 配置，安装器会自动启用 使用备选 WebUI 并设置路径；否则按照上面的“新手安装 → 在 qBittorrent 中启用”手动填写即可。
Windows PowerShell
Invoke-WebRequest https://weigefenxiang.github.io/WeiG-qB-WebUI/downloads/dev/install.ps1 -OutFile .\install.ps1; powershell -ExecutionPolicy Bypass -File .\install.ps1 -configure查看安装目录
C:\Users\<你的用户名>\AppData\Local\weig-qb-webui常用参数
Linux 和 Windows 使用相同的参数名称，文档统一使用小写（点击展开）
| 用途 | Linux / Docker / NAS | Windows PowerShell |
|---|---|---|
| 稳定 main | 默认，无需参数 | 默认，无需参数 |
| 指定正式版本 | -version 1.2.0 | -version 1.2.0 |
| 开发版 | -dev | -dev |
| 指定安装目录 | -o /path（Linux 可重复） | -o D:\path 或 -output D:\path |
| 指定自定义 qBittorrent 配置文件 | — | -qbconfig D:\path\qBittorrent.ini |
| 自动配置 qBittorrent | -configure | -configure |
| 回滚上一次安装 | -rollback | -rollback |
| 彻底卸载（不保留安装器备份） | -uninstall -purge | -uninstall -purge |
| 查看完整帮助 | -help | -help |
| 指定 Docker 容器 | --container=NAME | — |
| 列出 Docker 容器 | --list-containers | — |
指定 Docker /config 宿主机目录 | --config-root=/path | — |
说明： （点击展开）
- 不加
-dev默认安装稳定main（使用最新且经过校验的 GitHub Release）；加-dev才安装当前devexact-SHA。 -o中的o表示 output。Linux 可以重复写多个-o，一次下载并更新多个现有 WebUI 目录。- 安装器备份始终放在
~/.config/weig-qb-webui/backups/，并且每个安装目标独立只保留最近 3 份。 -configure会在安装后自动启用 qBittorrent 的 使用备选 WebUI / Use alternative WebUI 并设置 文件位置 / Files location；它只允许单目标使用。-rollback会恢复所选目标最近一次由安装器创建的备份；也可以重复-o一次回滚多个明确目标。- 推荐卸载使用
-uninstall -purge：按 installer-owned 安全流程卸载 WebUI 后，清理当前目标所属的安装器备份和 rollback 状态；不会删除其它安装目标的备份。共享状态目录为空时，Linux 的~/.config/weig-qb-webui（root 即/root/.config/weig-qb-webui）或 Windows 的%APPDATA%\weig-qb-webui也会自动清空。 - 如果希望保留安装器备份以后使用
-rollback，卸载时去掉-purge即可。 -version安装指定 GitHub Release，例如1.2.0；指定版本不存在时直接报错，不会自动退回 latest 或 dev。-help显示当前安装脚本支持的参数。- Docker 有多个 qBittorrent 容器时，用
--list-containers查看，再用--container=NAME明确指定；也可以用--config-root=/path直接指定宿主机上的 qBittorrent 配置目录。
指定版本和安装目录
Linux：
sh install.sh -version 1.2.0 -o /opt/weig-qb-webui -configureWindows：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -version 1.2.0 -o D:\weig-qb-webui -configure回滚
Linux：
sh install.sh -rollbackWindows：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -rollback一键卸载
Linux / NAS、Docker、Windows PowerShell 一键彻底卸载（点击展开）
默认推荐不保留安装器备份：卸载 WebUI、关闭当前目标的备选 WebUI、清理该目标的 installer-owned backups / rollback 状态，并删除下载到当前目录的安装脚本。
Linux / NAS
sh install.sh -uninstall -configure -purge && rm -f -- ./install.sh自定义安装目录继续加 -o /你的/weig-qb-webui。
Docker
单容器自动识别：
sh install.sh -uninstall -configure -purge && rm -f -- ./install.sh多容器：
sh install.sh -uninstall -configure -purge --container=qbittorrent && rm -f -- ./install.sh使用 --config-root 时：
sh install.sh -uninstall -configure -purge --config-root=/path/to/qbittorrent/config && rm -f -- ./install.shWindows PowerShell
powershell -ExecutionPolicy Bypass -File .\install.ps1 -uninstall -configure -purge; if ($LASTEXITCODE -eq 0) { Remove-Item .\install.ps1 -Force }自定义安装目录继续加 -o D:\weig-qb-webui。
-purge 只清当前卸载目标的备份，不会误删其它安装实例。共享状态目录没有其它内容时，Linux 的 ~/.config/weig-qb-webui（root 即 /root/.config/weig-qb-webui）或 Windows 的 %APPDATA%\weig-qb-webui 也会随之清空。
如需保留备份以后使用 -rollback，只要去掉 -purge。
更多帮助
Docker 多容器、NAS、自定义路径及高级部署说明见：新手安装、升级指南。
许可证
本项目使用 GNU General Public License v3。
Copyright © 2026 Wei.G / WeiG Share。
]]>
