WeiG qB WebUI：qBittorrent「替補 WebUI」新手安裝教學

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-webui
Linux：  /opt/weig-qb-webui

之後 qBittorrent 要填寫的就是這個目錄。

3. 在 qBittorrent 中啟用

開啟 qBittorrent：

工具 → 選項… → WebUI

這是 qBittorrent 目前繁體中文官方用語。接著：

1. 勾選 使用替補 WebUI。
2. 找到 檔案位置：。
3. 填入剛才儲存的 weig-qb-webui 資料夾路徑。

Windows 範例：

D:\weig-qb-webui

一般 Linux 範例：

/opt/weig-qb-webui

4. 按一下 確定 儲存設定。
5. 重新整理 qBittorrent WebUI 頁面。如果瀏覽器仍顯示舊頁面，可再按一次 Ctrl + F5 強制重新整理。

怎麼判斷路徑填對了？ 你填寫的目錄裡應該能直接看到 public、private、VERSION 等檔案/目錄。如果還要再進入一層 weig-qb-webui 才能看到這些內容，表示路徑多填或少填了一層。

Docker 使用者注意： qBittorrent 執行在容器裡，因此這裡通常不能直接填宿主機上的真實路徑。Docker 的「宿主機 / 容器」差異與正確路徑寫法請看下面 Docker 折疊教學。

./install.sh

WebUI 本體預設安裝到：

~/.local/share/weig-qb-webui

例如使用 root 使用者執行時，通常就是：

/root/.local/share/weig-qb-webui

先理解「宿主機」和「容器」

如果你是在 VPS、Linux 伺服器、Synology、QNAP 等裝置上執行 Docker：

• 宿主機：真正執行 Docker 的那台 Linux / NAS，也就是你 SSH 登入後看到的系統。
• 容器：Docker 為 qBittorrent 建立的獨立執行環境。qBittorrent 可以直接看到容器內路徑，但不能任意看到宿主機路徑。

例如 Docker 建立 qBittorrent 時有這樣的目錄映射：

宿主機：/root/qbittorrent/config
   ↓ 映射到
容器內：/config

Docker 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 容器

例如同時有：

qbittorrent
qbittorrent-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

Synology 上可能類似：

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；各個實例仍沿用原本設定的 WebUI 路徑。參數請見 sh install.sh -help。

安裝後應該看到什麼

安裝成功時腳本會輸出類似：

Host install path: /root/qbittorrent/config/weig-qb-webui
qBittorrent Root Folder: /config/weig-qb-webui

意思是：

• Host install path：檔案實際儲存在宿主機哪裡；
• qBittorrent Root Folder：你在 qBittorrent「檔案位置：」中應填寫的容器內路徑。

如果使用 -configure 並成功找到 qBittorrent 設定，安裝器會自動啟用 使用替補 WebUI 並設定路徑；否則請依照上面的「新手安裝 → 在 qBittorrent 中啟用」手動填寫。

C:\Users\<你的使用者名稱>\AppData\Local\weig-qb-webui

Linux 與 Windows 盡量使用相同的公開參數名稱；文件統一使用小寫。PowerShell 參數名稱本身不區分大小寫。

• 不加 -dev 使用 main 最新且經過驗證的 GitHub Release；加 -dev 才安裝目前 dev 的 exact-SHA 開發版。
• -o 是 output，Linux 可重複指定多個現有安裝目錄，下載與驗證套件只需一次。
• 備份放在 ~/.config/weig-qb-webui/backups/，每個安裝目標獨立保留最近 3 份。
• -configure 會啟用 使用備選 WebUI / Use alternative WebUI 並設定 檔案位置 / Files location，僅能用於單一目標。
• -rollback 可還原所選目標最近的安裝器備份；重複 -o 也能一次回滾多個指定目標。
• -uninstall -purge 只清理該目標的 WebUI、安裝器備份和回滾狀態，不會影響其他目標；共享狀態目錄為空時也會清除。
• 若要保留備份日後使用 -rollback，解除安裝時請去掉 -purge。
• -version 1.2.0 可指定 GitHub Release；版本不存在會報錯，不會自動切換到 latest 或 dev。
• -help 顯示目前安裝器支援的參數。
• 多個 Docker 容器請先用 --list-containers 查看，再用 --container=NAME 指定；或使用 --config-root=/path 指定宿主機上的設定目錄。

指定版本與安裝目錄

Linux：

sh install.sh -version 1.2.0 -o /opt/weig-qb-webui -configure

Windows：

powershell -ExecutionPolicy Bypass -File .\install.ps1 -version 1.2.0 -o D:\weig-qb-webui -configure

回滾

Linux：

sh install.sh -rollback

Windows：

powershell -ExecutionPolicy Bypass -File .\install.ps1 -rollback

預設建議不保留安裝器備份：解除安裝 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.sh

Windows 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。