155 lines
6.2 KiB
Markdown
155 lines
6.2 KiB
Markdown
# 🧲 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. 단일 웹 서버 모드 (권장)
|
|
프론트엔드 정적 파일이 빌드되어 포함되어 있으므로 단일 커맨드로 백엔드와 프론트엔드가 모두 서빙됩니다.
|
|
|
|
```bash
|
|
# 가상환경 활성화 후 실행
|
|
./venv/bin/python main.py
|
|
```
|
|
브라우저에서 **[http://localhost:8000](http://localhost:8000)** 으로 접속하세요.
|
|
|
|
### 2. 창(Desktop Window) 모드
|
|
`pywebview`를 통해 독립된 데스크톱 앱 창 형태로 실행할 수도 있습니다.
|
|
```bash
|
|
./venv/bin/python main.py --window
|
|
```
|
|
|
|
---
|
|
|
|
## 💻 개발 모드 (HMR & 실시간 반영)
|
|
|
|
### Backend 개별 실행
|
|
```bash
|
|
./venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
### Frontend 개별 실행
|
|
```bash
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
- 프론트엔드 개발 서버: `http://localhost:5173` (백엔드 `http://localhost:8000`으로 자동 프록시)
|
|
|
|
### Frontend 프로덕션 재빌드
|
|
프론트엔드 코드를 수정한 후 빌드하려면:
|
|
```bash
|
|
cd frontend
|
|
npm run build
|
|
```
|
|
|
|
---
|
|
|
|
## 🚢 실서버 배포 가이드 (Deployment)
|
|
|
|
이 프로젝트는 프론트엔드(`frontend/dist`)가 이미 백엔드(`FastAPI`)에 통합되어 빌드되어 있으므로, **포트 `8000`번 하나만 띄우면 웹 UI와 모든 API가 완전히 동작**합니다.
|
|
|
|
환경에 맞는 배포 방식을 선택하세요:
|
|
|
|
### 방법 1. Systemd 서비스 등록 (가장 추천: 홈서버/라즈베리파이/Linux)
|
|
서버 부팅 시 자동으로 백그라운드에서 실행되도록 등록합니다.
|
|
|
|
```bash
|
|
# 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 배포
|
|
도커 컨테이너로 완전 격리하여 배포할 수 있습니다.
|
|
|
|
```bash
|
|
# 컨테이너 빌드 및 백그라운드 실행
|
|
docker compose up -d --build
|
|
```
|
|
- 로그 확인: `docker compose logs -f`
|
|
- 컨테이너 종료: `docker compose down`
|
|
|
|
---
|
|
|
|
### 방법 3. Nginx 역방향 프록시 (외부 접속 & 도메인/HTTPS 연결)
|
|
도메인을 연결하거나 80/443 포트로 외부 접속을 열고자 할 때 Nginx 설정 예시:
|
|
|
|
```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 통신 상태 및 버전 표시
|