2025년 7월의 원본 스레드는 qBittorrent App Store 설치 실패로 시작해 LinuxServer.io 컨테이너를 수동으로 설치하는 것으로 끝났습니다. 이 페이지의 이전 요약은 “풀 실패”에서 “LinuxServer를 사용하라”로 너무 빠르게 넘어갔습니다. 전체 스레드에는 중요한 버전 관련 우회 과정이 담겨 있습니다. IceWhale은 앱 설치 동작이 개선된 ZimaOS 1.4.2 beta1을 테스트해 달라고 요청했고, 베타는 설치되었지만 사용자의 GTX 1070에서 새로운 GPU 관련 문제를 일으켰으며, 사용자는 결국 1.4.1로 돌아갔습니다.
수동으로 설치한 qBittorrent 컨테이너는 원래 사용자가 사용하기에 충분히 잘 작동했지만, 당시 사용자가 적용한 WebUI 우회 방법에서는 호스트 헤더 검증과 CSRF 보호가 비활성화되었습니다. 현재 설치에서 이를 기본 해결 방법으로 적용해서는 안 됩니다.
원래 실패는 이미지 풀 문제였습니다
이미지 풀 오류는 시작된 후 충돌하는 컨테이너와는 다릅니다. 문제 해결의 대상은 이미지 참조, 레지스트리 액세스, App Store 정의 또는 ZimaOS 앱 설치 계층입니다.
IceWhale이 ZimaOS 1.4.2 Beta1을 제안했습니다
Zima-Giorgio는 당시 최신 버전이었던 1.4.2 beta1을 사용해 보라고 요청했습니다. 해당 릴리스에서 앱 설치 환경이 개선되었으며 문제를 해결할 수도 있었기 때문입니다. 업데이트가 자동으로 표시되지 않자 Giorgio는 당시 베타 버전에 대한 공식 오프라인 업데이트 방법을 안내했습니다.
해당 명령은 2025년 사전 릴리스 빌드에 속하므로 현재 서버에서 다시 사용해서는 안 됩니다. 역사적으로 중요한 의미는 IceWhale이 App Store 풀 실패가 ZimaOS 버전과 관련되었을 가능성을 고려했다는 점입니다.
베타가 사용자에게 다른 문제를 일으켰습니다
사용자는 베타를 설치했지만, 베타가 GTX 1070 GPU를 무시했다는 본인의 설명에 따라 나중에 1.4.1로 되돌렸습니다. 이는 단 하나의 앱을 복구하기 위해 베타로 업그레이드할 때도 서버의 나머지 기능에 대한 회귀 검사를 포함해야 하는 이유를 보여 줍니다.
특정 지원상의 이유로 시험판 빌드를 테스트해야 하는 경우가 아니라면, 현재 시스템에서는 최신 안정 ZimaOS 릴리스를 사용해야 합니다.
이후 사용자는 LinuxServer.io qBittorrent 이미지를 설치했습니다.
현재 LinuxServer.io qBittorrent는 다음을 사용합니다. lscr.io/linuxserver/qbittorrent중요한 영구 설정 및 네트워크 설정은 다음과 같습니다.
-
/configqBittorrent 구성용 - 컨테이너에 매핑된 호스트 다운로드 폴더
- 파일 소유권 설정을 위한 PUID 및 PGID
- WebUI 포트
- TCP 및 UDP를 통한 BitTorrent 수신 포트입니다.
2025년 구성을 기억에 의존해 다시 만드는 대신 현재 LinuxServer.io qBittorrent 컨테이너 설정을 사용하세요.
WEBUI_PORT와 Docker 포트 매핑을 동기화하세요
현재 이미지는 일반적으로 8080 포트에서 WebUI를 제공합니다. 다른 호스트 포트를 사용하려면 해당 호스트 포트를 컨테이너 서비스에 매핑하면 됩니다. 내부 WebUI 포트 자체를 변경하는 경우 LinuxServer.io에서는 다음 값을 요구합니다. WEBUI_PORT 환경 변수 값과 Docker 매핑을 일치시키세요.
WebUI 포트가 일치하지 않으면 인증 또는 보안 헤더 문제처럼 보이는 연결 실패가 발생할 수 있습니다.
시작 로그의 임시 비밀번호 사용
소스의 사용자는 첫 번째 비밀번호를 로그에서 확인할 수 있다고 정확히 언급했습니다. 현재 LinuxServer.io 동작에서는 다음 계정에 사용할 임시 비밀번호가 생성됩니다. admin 시작 시 계정.
qBittorrent 컨테이너 로그를 열고 첫 로그인에 임시 값을 사용한 다음, WebUI에서 즉시 영구 비밀번호를 설정하세요.
기본적으로 HostHeaderValidation 및 CSRFProtection을 비활성화하지 마세요
과거 소스의 사용자는 다음과 같이 추가했습니다.
WebUI\HostHeaderValidation=false
WebUI\CSRFProtection=falseqBittorrent 구성 파일에 추가했습니다. 사용자는 이후 애플리케이션이 작동하는 것처럼 보였다고 보고했지만, 이러한 옵션은 브라우저를 대상으로 하는 보안 검사를 의도적으로 약화합니다.
현재 설치에서는 먼저 올바른 포트, WebUI URL, 리버스 프록시 헤더 및 인증 구성을 해결해야 합니다. WebUI 액세스 문제에 대한 표준 답변으로 “CSRF 비활성화”를 사용하지 마세요.
리버스 프록시가 관련된 경우 올바르게 구성하세요.
호스트 헤더 오류는 WebUI가 예상하지 못한 호스트 이름이나 프록시를 통해 애플리케이션에 액세스할 때 자주 나타납니다. 일반적으로 올바른 해결 방법은 전역적으로 모든 검증을 비활성화하는 것이 아니라 프록시와 qBittorrent의 WebUI 설정을 일관되게 구성하는 것입니다.
WebUI 트래픽과 BitTorrent 피어 트래픽은 서로 다른 포트를 사용합니다.
브라우저에서 qBittorrent를 관리하는 데 사용하는 포트는 인바운드 피어 연결에 사용하는 포트와 다릅니다. 선택한 토렌트 수신 대기 포트를 TCP와 UDP로 게시하고, qBittorrent 자체의 수신 대기 포트 설정도 일치시켜야 합니다.
서버가 NAT 뒤에 있고 인바운드 피어 연결이 필요하다면, 라우터 또는 VPN 설계는 Docker 포트 매핑과 별도로 결정해야 합니다.
다운로드를 실제 ZimaOS 저장 공간에 매핑
대용량 토렌트가 일회용 컨테이너 레이어나 작은 시스템 디스크에 쌓이지 않도록 하세요. 다운로드 디렉터리를 의도한 ZimaOS 저장 공간에 매핑하고, 대용량 다운로드를 시작하기 전에 컨테이너 사용자가 해당 위치에 쓸 수 있는지 확인하세요.
컨테이너를 다시 만들기 전에 /config 유지
qBittorrent 환경설정, 카테고리, 경로 및 애플리케이션 상태는 영구 구성 디렉터리에 저장됩니다. 이미지를 변경하거나 App Store 배포를 사용자 지정 컨테이너로 교체하기 전에 백업하세요.
ZimaOS의 qBittorrent FAQ
원래 문제가 qBittorrent 충돌이었나요?
아니요. App Store 설치가 Docker 이미지 가져오기 단계에서 실패했습니다.
사용자가 베타 버전에서 ZimaOS 1.4.1로 되돌아간 이유는 무엇인가요?
베타 버전이 GTX 1070을 예상대로 처리하지 못했다고 보고했습니다.
첫 번째 qBittorrent 비밀번호는 어디에서 가져오나요?
현재 LinuxServer.io 컨테이너는 시작 로그에 임시 관리자 비밀번호를 출력합니다.
WebUI가 작동하도록 CSRF 보호를 비활성화해야 하나요?
기본 접근 방식으로는 권장하지 않습니다. 먼저 현재 포트, 프록시, 호스트 이름 및 인증 구성을 수정하세요.
