🧲 Transmission Magnet Manager

현재 호스트에 Docker로 구동 중인 Transmission (linuxserver/transmission, 포트 9091) 에 마그넷 링크를 원격으로 추가하고 다운로드 상태를 관리하는 FastAPI 백엔드 + Vue 3 프론트엔드 애플리케이션입니다.

---

🛠 기술 스택

• Backend: Python 3.14, FastAPI, Uvicorn, HTTPX, Pydantic
• Frontend: Vue 3 (Composition API, <script setup>), Vuetify 3, Material Design Icons (@mdi/font), Vite
• Torrent Engine: 호스트 Docker 컨테이너 (dd7da08820de, Transmission RPC 9091)

---

🚀 빠른 시작

1. 단일 웹 서버 모드 (권장)

프론트엔드 정적 파일이 빌드되어 포함되어 있으므로 단일 커맨드로 백엔드와 프론트엔드가 모두 서빙됩니다.

# 가상환경 활성화 후 실행
./venv/bin/python main.py

브라우저에서 http://localhost:8000 으로 접속하세요.

2. 창(Desktop Window) 모드

pywebview를 통해 독립된 데스크톱 앱 창 형태로 실행할 수도 있습니다.

./venv/bin/python main.py --window

---

💻 개발 모드 (HMR & 실시간 반영)

Backend 개별 실행

./venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

Frontend 개별 실행

cd frontend
npm run dev

• 프론트엔드 개발 서버: http://localhost:5173 (백엔드 http://localhost:8000으로 자동 프록시)

Frontend 프로덕션 재빌드

프론트엔드 코드를 수정한 후 빌드하려면:

cd frontend
npm run build

---

🚢 실서버 배포 가이드 (Deployment)

이 프로젝트는 프론트엔드(frontend/dist)가 이미 백엔드(FastAPI)에 통합되어 빌드되어 있으므로, 포트 8000번 하나만 띄우면 웹 UI와 모든 API가 완전히 동작합니다.

환경에 맞는 배포 방식을 선택하세요:

방법 1. Systemd 서비스 등록 (가장 추천: 홈서버/라즈베리파이/Linux)

서버 부팅 시 자동으로 백그라운드에서 실행되도록 등록합니다.

# 1. 서비스 파일을 systemd 경로로 복사
sudo cp transmission-manager.service /etc/systemd/system/

# 2. 서비스 데몬 리로드 및 부팅 시 자동 시작 활성화
sudo systemctl daemon-reload
sudo systemctl enable transmission-manager

# 3. 서비스 시작
sudo systemctl start transmission-manager

# 4. 상태 확인
sudo systemctl status transmission-manager

• 중지: sudo systemctl stop transmission-manager
• 로그 확인: journalctl -u transmission-manager -f

---

방법 2. Docker / Docker Compose 배포

도커 컨테이너로 완전 격리하여 배포할 수 있습니다.

# 컨테이너 빌드 및 백그라운드 실행
docker compose up -d --build

• 로그 확인: docker compose logs -f
• 컨테이너 종료: docker compose down

---

방법 3. Nginx 역방향 프록시 (외부 접속 & 도메인/HTTPS 연결)

도메인을 연결하거나 80/443 포트로 외부 접속을 열고자 할 때 Nginx 설정 예시:

server {
    listen 80;
    server_name my-torrent.example.com; # 도메인 또는 IP

    # 대용량 파일 다운로드 및 업로드 타임아웃 방지
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE 실시간 진행률 스트리밍 지원 필수 설정
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }
}

---

📌 주요 기능

1. 사이드 네비게이션 메뉴 (v-navigation-drawer)
   • 토렌트 관리: 마그넷 추가 및 활성 토렌트 모니터링 (실시간 활성 토렌트 개수 뱃지 표시)
   • 다운로드 파일 뷰어: 다운로드 완료 디렉토리(/mnt/ssd/transmission/downloads) 파일 브라우저
2. 마그넷 링크 추가 (POST /api/torrents/add)
   • magnet:?xt=urn:... 및 토렌트 URL 추가
   • 원클릭 클립보드 붙여넣기 지원
   • 저장 경로 커스텀 지정 옵션 (비워둘 시 기본 다운로드 경로 /downloads/complete 사용)
   • 추가 즉시 일시정지 옵션
3. 실시간 토렌트 현황 모니터링 (GET /api/torrents)
   • 파일명, 다운로드 진행률 (%), 파일 크기
   • 실시간 다운로드 / 업로드 속도 표시
   • 4초 주기 자동 새로고침 및 수동 새로고침
4. 토렌트 제어
   • 일시정지 (POST /api/torrents/{id}/stop)
   • 다운로드 시작/재개 (POST /api/torrents/{id}/start)
   • 토렌트 삭제 (DELETE /api/torrents/{id}: 데이터 보존 제거 또는 디스크 데이터 완전 삭제 지원)
5. 다운로드 파일 뷰어 (GET /api/files)
   • 브레드크럼(경로 이동) 및 상위 폴더 이동 지원
   • 파일 확장자별 자동 분류 아이콘 (폴더, 압축파일, 동영상, 음악, 이미지, 문서 등)
   • 파일 개별 다운로드 및 미디어 미리보기(동영상/오디오/이미지/문서 스트리밍 뷰어) 지원
   • 파일 한 번에 다운로드 (일괄 ZIP 다운로드):
     • 폴더 전체 다운로드: 현재 폴더 또는 하위 폴더를 통째로 하나의 .zip으로 묶어 한 번에 다운로드 (GET /api/files/download-folder)
     • 체크박스 다중 선택 다운로드: 원하는 파일/폴더들을 체크박스로 다중 선택하여 하나의 .zip 파일로 묶어서 일괄 다운로드 (POST /api/files/download-batch)
     • 선택 항목 일괄 삭제: 체크한 파일들을 한 번에 디스크에서 삭제 지원
   • 압축 파일 풀기 & 실시간 진행 과정 (POST /api/files/extract-stream):
     • 암호화 압축 파일 초고속 사전 감지 및 암호(비밀번호) 입력 지원
     • SSE(Server-Sent Events) 기반 실시간 압축 해제 진행률(0~100%) 프로그레스 바, 처리 중인 파일명, 완료 파일 개수 실시간 표시
   • 파일/폴더 삭제 지원
6. 연결 상태 모니터링 (GET /api/status)
   • Transmission 컨테이너와의 RPC 통신 상태 및 버전 표시