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. 고정된 위치로 이동

나중에 실수로 삭제하지 않을 위치에 전체 폴더를 옮깁니다.

Windows: D:\weig-qb-webui
Linux:   /opt/weig-qb-webui

이 경로를 qBittorrent에 입력합니다.

3. qBittorrent에서 활성화

qBittorrent를 엽니다.

도구 → 옵션… → WebUI

현재 qBittorrent 공식 한국어 UI 용어입니다. 이어서:

1. 대체 WebUI 사용을 켭니다.
2. **파일 위치:**를 찾습니다.
3. 저장한 weig-qb-webui 폴더 경로를 입력합니다.

Windows 예시:

D:\weig-qb-webui

Linux 예시:

/opt/weig-qb-webui

4. 확인/OK을 눌러 저장합니다.
5. qBittorrent WebUI 페이지를 새로고침합니다. 이전 화면이 남으면 Ctrl + F5를 눌러 보세요.

경로가 맞는지 확인하는 방법: 입력한 폴더 안에 public, private, VERSION 등이 바로 보여야 합니다.

Docker 사용자: qBittorrent는 컨테이너 안에서 실행되므로 호스트 경로를 그대로 입력할 수 없는 경우가 많습니다. 아래 Docker 안내를 확인하세요.

./install.sh

기본 WebUI 설치 경로:

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

root로 실행한 경우 일반적으로:

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

호스트와 컨테이너

• 호스트: Docker가 실제로 실행되는 Linux/NAS 시스템입니다.
• 컨테이너: qBittorrent가 실행되는 Docker 환경입니다.

예를 들어:

호스트:      /root/qbittorrent/config
   ↓ 매핑
컨테이너:    /config

Docker Compose 예시:

volumes:
  - /root/qbittorrent/config:/config

WebUI가 호스트의:

/root/qbittorrent/config/weig-qb-webui

에 설치되었다면 qBittorrent의 **파일 위치:**에는:

/config/weig-qb-webui

를 입력해야 합니다.

qBittorrent 컨테이너가 하나뿐인 경우

curl -fsSL https://weigefenxiang.github.io/WeiG-qB-WebUI/downloads/dev/install.sh -o install.sh && sh install.sh -configure

설치기가 실행 중인 qBittorrent 컨테이너와 /config 매핑을 자동으로 찾습니다.

컨테이너 목록 보기

sh install.sh --list-containers

또는:

docker ps

qbittorrent를 명시적으로 선택:

sh install.sh --container=qbittorrent -configure

여러 컨테이너가 있으면 설치기는 임의로 선택하지 않습니다.

상황 3: qBittorrent 컨테이너가 여러 개일 때

qbittorrent와 qbittorrent-test가 모두 있다면 목록을 먼저 확인하고 설치 대상을 지정하세요. 설치 프로그램이 임의로 선택하지 않습니다.

sh install.sh --list-containers
sh install.sh --container=qbittorrent -configure
sh install.sh --container=qbittorrent-test -configure

호스트의 /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

WebUI 경로 지정

sh install.sh --container=qbittorrent -o /config/weig-qb-webui -configure

상황 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에서 확인할 수 있습니다.

설치 후 경로 확인

설치가 완료되면 다음과 비슷한 경로가 표시됩니다. 첫 번째는 호스트의 실제 설치 위치이고, 두 번째는 qBittorrent의 Files location에 입력할 컨테이너 내부 경로입니다.

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

C:\Users\<사용자 이름>\AppData\Local\weig-qb-webui

PowerShell 매개변수 이름은 대소문자를 구분하지 않습니다.

• -dev 없이 실행하면 main의 검증된 GitHub 정식 릴리스를 설치합니다. -dev는 현재 dev의 exact-SHA 개발 빌드를 선택합니다.
• -o는 output의 약자로, Linux에서 여러 번 지정하면 한 번의 다운로드로 기존 WebUI 폴더들을 업데이트할 수 있습니다.
• 백업은 ~/.config/weig-qb-webui/backups/에 저장되며 설치 대상별로 최신 3개씩 보관됩니다.
• -configure는 qBittorrent의 Use alternative WebUI를 켜고 Files location을 지정합니다. 단일 대상만 지원합니다.
• -rollback은 선택한 대상의 최근 설치 프로그램 백업을 복원합니다. -o를 반복하면 여러 명시적 대상도 롤백할 수 있습니다.
• -uninstall -purge는 해당 대상의 WebUI와 백업, 롤백 상태를 제거하되 다른 대상의 백업은 그대로 두며 공유 폴더는 비었을 때만 정리합니다.
• 나중에 -rollback을 쓸 계획이라면 제거할 때 -purge를 생략하세요.
• -version 1.2.0처럼 GitHub 정식 릴리스를 지정할 수 있습니다. 없으면 오류가 나며 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

롤백

롤백:

sh install.sh -rollback

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 /path/to/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만 빼면 됩니다.