프로젝트 결과 보고서: 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 버전 이상이 필요합니다.

가상환경 생성 및 활성화

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 또는
.venv\Scripts\activate     # Windows

필수 패키지 설치

pip install fastapi uvicorn python-multipart yt-dlp

서버 실행

python main.py

서버는 기본적으로 http://0.0.0.0:8000에서 실행됩니다.

3. curl을 이용한 테스트 방법

A. 파일 업로드 테스트

assets/images/dummy.png 파일을 업로드하는 예시입니다.

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. 파일 목록 조회 테스트

서버에 저장된 모든 파일의 정보를 확인합니다.

curl -X GET "http://localhost:8000/api/files"

C. 파일 다운로드 테스트

dummy.png라는 이름의 파일을 다운로드하여 downloaded_file.png로 저장하는 예시입니다.

curl -X GET "http://localhost:8000/api/files/download?filename=dummy.png" \
     --output downloaded_file.png

D. 파일 삭제 테스트

서버의 파일을 삭제하는 예시입니다.

curl -X DELETE "http://localhost:8000/api/files?filename=dummy.png"

E. YouTube 다운로드 테스트

YouTube 링크를 통해 영상을 다운로드하는 예시입니다.

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: 프로젝트 요구사항 명세서

4.0 KiB Raw Permalink Blame History