100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# 프로젝트 결과 보고서: FastAPI 파일 관리 시스템
|
|
|
|
## 1. 프로그램 개요
|
|
본 프로그램은 **FastAPI**를 기반으로 한 웹 기반 파일 관리 시스템입니다. 사용자는 이미와 동영상 파일을 업로드하고, 서버에서 해당 파일을 다운로드하거나 목록을 확인할 수 있습니다.
|
|
|
|
### 주요 기능
|
|
- **파일 업로드 (`POST /api/files/upload`)**: 파일을 업로드하면 MIME 타입에 따라 `assets/images` 또는 `assets/videos` 폴더로 자동 분류하여 저장합니다.
|
|
- **파일 목록 조회 (`GET /api/files`)**: 서버에 저장된 모든 파일의 메타데이터(파일명, 타입, 업로드 날짜, 경로 등)를 JSON 형식으로 반환합니다.
|
|
- **파일 다운로드 (`GET /api/files/download`)**: 파일명을 파라미터로 전달하여 서버에 저장된 파일을 로컬로 다운로드할 수 있습니다.
|
|
- **파일 삭제 (`DELETE /api/files`)**: 서버에서 특정 파일을 삭제하고 메타데이터에서도 제거합니다.
|
|
- **메타데이터 관리**: 업로드된 파일의 정보는 `metadata.json` 파일에 기록되어 영구적으로 관리됩니다.
|
|
- **YouTube 다운로드 (`POST /api/files/youtube`)**: YouTube 링크를 전달받아 해당 영상을 서버로 다운로드하고 목록에 추가합니다.
|
|
- **실시간 스트리밍 지원**: `FileResponse`의 Range Requests 지원을 통해 대용량 영상 파일도 브라우저에서 원하는 시점으로 이동하며 끊김 없이 감상할 수 있습니다.
|
|
- **모던 파스텔 UI**: 사용자 친화적인 파스텔 톤의 카드 레이아웃과 반응형 디자인을 적용하여 모바일과 데스크톱 모두에서 쾌적하게 사용할 수 있습니다.
|
|
- **웹 인터페이스 서빙 (`/web`)**: `static/` 디렉토리의 HTML/JS 파일을 통해 사용자에게 웹 화면을 제공합니다.
|
|
|
|
---
|
|
|
|
## 2. 실행 방법
|
|
|
|
### 환경 준비
|
|
Python 3.9 버전 이상이 필요합니다.
|
|
|
|
1. **가상환경 생성 및 활성화**
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Linux/macOS
|
|
# 또는
|
|
.venv\Scripts\activate # Windows
|
|
```
|
|
|
|
2. **필수 패키지 설치**
|
|
```bash
|
|
pip install fastapi uvicorn python-multipart yt-dlp
|
|
```
|
|
|
|
### 서버 실행
|
|
```bash
|
|
python main.py
|
|
```
|
|
서버는 기본적으로 `http://0.0.0.0:8000`에서 실행됩니다.
|
|
|
|
---
|
|
|
|
## 3. curl을 이용한 테스트 방법
|
|
|
|
### A. 파일 업로드 테스트
|
|
`assets/images/dummy.png` 파일을 업로드하는 예시입니다.
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/api/files/upload" \
|
|
-H "accept: application/json" \
|
|
-H "Content-Type: multipart/form-data" \
|
|
-F "file=@assets/images/dummy.png" \
|
|
-F "description=테스트 이미지입니다" \
|
|
-F "uploader=홍길동"
|
|
```
|
|
|
|
### B. 파일 목록 조회 테스트
|
|
서버에 저장된 모든 파일의 정보를 확인합니다.
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/api/files"
|
|
```
|
|
|
|
### C. 파일 다운로드 테스트
|
|
`dummy.png`라는 이름의 파일을 다운로드하여 `downloaded_file.png`로 저장하는 예시입니다.
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/api/files/download?filename=dummy.png" \
|
|
--output downloaded_file.png
|
|
```
|
|
|
|
### D. 파일 삭제 테스트
|
|
서버의 파일을 삭제하는 예시입니다.
|
|
|
|
```bash
|
|
curl -X DELETE "http://localhost:8000/api/files?filename=dummy.png"
|
|
```
|
|
|
|
### E. YouTube 다운로드 테스트
|
|
YouTube 링크를 통해 영상을 다운로드하는 예시입니다.
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/api/files/youtube" \
|
|
-H "accept: application/json" \
|
|
-H "Content-Type: multipart/form-data" \
|
|
-F "url=https://www.youtube.com/watch?v=EXAMPLE_ID" \
|
|
-F "uploader=테스터"
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 디렉토리 구조
|
|
- `main.py`: FastAPI 애플리케이션 엔트리 포인트
|
|
- `metadata.json`: 파일 메타데이터 저장소
|
|
- `assets/`: 업로드된 실제 파일 저장 (images/videos 분류)
|
|
- `static/`: 웹 프론트엔드 정적 파일
|
|
- `REQUIREMENTS.md`: 프로젝트 요구사항 명세서
|