NAS Docker 기반 qBittorrent 무중단 다운로드 환경 구축 및 트러블슈팅

NAS나 홈서버 환경에서 토렌트 클라이언트를 데스크톱 대신 24시간 가동할 때 가장 안정적인 도구는 Docker 기반의 qBittorrent입니다.

그러나 컨테이너 실행 직후 마운트 볼륨의 쓰기 권한 충돌(Permission Denied)이나 외부 포트포워딩 미설정으로 인한 시더 연결 지연 이슈가 흔히 발생합니다. 실전 배포를 위한 docker-compose.yml 템플릿과 주요 설정 체크리스트를 정리합니다.

---

1. 아키텍처 개요 및 포트 포워딩

토렌트 클라이언트는 P2P 네트워크 특성상 인바운드 연결 포트가 열려 있어야 고속 피어(Peer)들과 원활하게 세션을 맺을 수 있습니다.

💡 핵심 점검 포인트
공유기(라우터) 관리자 페이지에서 6881/TCP, 6881/UDP 포트를 NAS의 내부 IP로 반드시 포트포워딩해야 합니다. 포트가 닫혀 있으면 다운로드 속도가 현저히 느려집니다.

---

2. Docker Compose 배포 템플릿

권한 오류를 사전에 방지하려면 NAS 호스트의 실제 사용자 UID/GID(id 명령어로 확인)를 PUID와 PGID 환경 변수로 명시해야 합니다.

version: "3.8"

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Seoul
      - WEBUI_PORT=8080
    volumes:
      - ./config:/config
      - /volume1/downloads:/downloads
    ports:
      - 8080:8080
      - 6881:6881
      - 6881:6881/udp
    restart: unless-stopped

배포 후 컨테이너를 구동합니다:

docker compose up -d

---

3. 자주 겪는 트러블슈팅

증상 1: 다운로드 시작 즉시 I/O Error: Permission Denied 발생

• 원인: 호스트 마운트 경로(/volume1/downloads)의 쓰기 권한이 컨테이너 내부의 PUID 사용자와 일치하지 않는 경우입니다.
• 해결법: 호스트 셸에서 해당 디렉토리의 소유권을 재할당합니다.

sudo chown -R 1000:1000 /volume1/downloads
sudo chmod -R 775 /volume1/downloads

증상 2: 다운로드 속도가 0 B/s에서 멈추는 현상

• 원인: 활성 피어(Peers) 수가 0으로 잡히거나 DHT 노드 검색이 차단된 상태입니다.

점검 항목	권장 설정값	비고
청취 포트(Listening Port)	6881	라우터 포트포워딩과 일치 필수
DHT / PeX 활성화	Checked (ON)	트래커 차단 시 피어 발굴용
익명 모드(Anonymous Mode)	OFF	초기 세션 연결 안정화 목적
최대 연결 수 (전체)	500	공유기 CPU 부하 방지

---

마무리 및 권장 사항

토렌트 파일을 내려받을 때 확장자가 .torrent가 아닌 실행 파일(.exe, .scr, .bat) 형태로 압축되어 있거나, 웹 UI에서 수상한 팝업을 띄우는 배너 링크는 반드시 격리하여 삭제하시기 바랍니다.