update README.md
Dohyun Lim
parent
56069a04a1
commit
ece201f92b
198
README.md
198
README.md
|
|
@ -4,24 +4,29 @@ AI 기반 광고 음악 생성 서비스의 백엔드 API 서버입니다.
|
|||
|
||||
## 기술 스택
|
||||
|
||||
- **Language**: Python 3.13
|
||||
- **Framework**: FastAPI
|
||||
- **Database**: MySQL (asyncmy 비동기 드라이버)
|
||||
- **Database**: MySQL (asyncmy 비동기 드라이버), Redis
|
||||
- **ORM**: SQLAlchemy (async)
|
||||
- **Package Manager**: uv
|
||||
- **AI Services**:
|
||||
- OpenAI ChatGPT (가사 생성, 마케팅 분석)
|
||||
- Suno AI (음악 생성)
|
||||
- Creatomate (비디오 생성)
|
||||
|
||||
## 프로젝트 구조
|
||||
|
||||
```text
|
||||
app/
|
||||
├── core/ # 핵심 설정 및 공통 모듈
|
||||
├── database/ # 데이터베이스 세션 및 설정
|
||||
├── core/ # 핵심 설정 및 공통 모듈 (logging, exceptions)
|
||||
├── database/ # 데이터베이스 세션 및 Redis 설정
|
||||
├── dependencies/ # FastAPI 의존성 주입
|
||||
├── home/ # 홈 API (크롤링, 영상 생성 요청)
|
||||
├── lyric/ # 가사 API (가사 생성)
|
||||
├── song/ # 노래 API (Suno AI 음악 생성)
|
||||
├── user/ # 사용자 모듈 (카카오 로그인, JWT 인증)
|
||||
├── video/ # 비디오 관련 모듈
|
||||
└── utils/ # 유틸리티 (ChatGPT, Suno, 크롤러)
|
||||
└── utils/ # 유틸리티 (ChatGPT, Suno, 크롤러, 프롬프트)
|
||||
```
|
||||
|
||||
## API 엔드포인트
|
||||
|
|
@ -57,22 +62,84 @@ app/
|
|||
`.env` 파일에 다음 환경 변수를 설정합니다:
|
||||
|
||||
```env
|
||||
# 프로젝트 설정
|
||||
PROJECT_NAME=CastAD
|
||||
PROJECT_DOMAIN=localhost:8000
|
||||
DEBUG=True
|
||||
# ================================
|
||||
# 프로젝트 기본 정보
|
||||
# ================================
|
||||
PROJECT_NAME=CastAD # 프로젝트 이름
|
||||
PROJECT_DOMAIN=localhost:8000 # 프로젝트 도메인 (호스트:포트)
|
||||
PROJECT_VERSION=0.1.0 # 프로젝트 버전
|
||||
DESCRIPTION=FastAPI 기반 CastAD 프로젝트 # 프로젝트 설명
|
||||
ADMIN_BASE_URL=/admin # 관리자 페이지 기본 URL
|
||||
DEBUG=True # 디버그 모드 (True: 개발, False: 운영)
|
||||
|
||||
# ================================
|
||||
# MySQL 설정
|
||||
MYSQL_HOST=localhost
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_USER=your_user
|
||||
MYSQL_PASSWORD=your_password
|
||||
MYSQL_DB=castad
|
||||
# ================================
|
||||
MYSQL_HOST=localhost # MySQL 호스트 주소
|
||||
MYSQL_PORT=3306 # MySQL 포트 번호
|
||||
MYSQL_USER=castad-admin # MySQL 사용자명
|
||||
MYSQL_PASSWORD=o2o1324 # MySQL 비밀번호
|
||||
MYSQL_DB=castad # 사용할 데이터베이스명
|
||||
|
||||
# API Keys
|
||||
CHATGPT_API_KEY=your_openai_api_key
|
||||
SUNO_API_KEY=your_suno_api_key
|
||||
SUNO_CALLBACK_URL=https://your-domain.com/api/suno/callback
|
||||
# ================================
|
||||
# Redis 설정
|
||||
# ================================
|
||||
REDIS_HOST=localhost # Redis 호스트 주소
|
||||
REDIS_PORT=6379 # Redis 포트 번호
|
||||
|
||||
# ================================
|
||||
# CORS 설정
|
||||
# ================================
|
||||
CORS_ALLOW_ORIGINS='["*"]' # 허용할 Origin 목록 (JSON 배열 형식)
|
||||
CORS_ALLOW_CREDENTIALS=True # 자격 증명(쿠키 등) 허용 여부
|
||||
CORS_ALLOW_METHODS='["*"]' # 허용할 HTTP 메서드 (JSON 배열 형식)
|
||||
CORS_ALLOW_HEADERS='["*"]' # 허용할 HTTP 헤더 (JSON 배열 형식)
|
||||
CORS_MAX_AGE=600 # Preflight 요청 캐시 시간 (초)
|
||||
|
||||
# ================================
|
||||
# Azure Blob Storage 설정
|
||||
# ================================
|
||||
AZURE_BLOB_SAS_TOKEN=your_sas_token # Azure Blob Storage SAS 토큰
|
||||
AZURE_BLOB_BASE_URL=https://... # Azure Blob Storage 기본 URL
|
||||
|
||||
# ================================
|
||||
# Creatomate 템플릿 설정
|
||||
# ================================
|
||||
TEMPLATE_ID_VERTICAL=your_template_id # 세로형(9:16) 비디오 템플릿 ID
|
||||
TEMPLATE_DURATION_VERTICAL=60.0 # 세로형 비디오 기본 길이 (초)
|
||||
TEMPLATE_ID_HORIZONTAL=your_template_id # 가로형(16:9) 비디오 템플릿 ID
|
||||
TEMPLATE_DURATION_HORIZONTAL=20.0 # 가로형 비디오 기본 길이 (초)
|
||||
|
||||
# ================================
|
||||
# JWT 토큰 설정
|
||||
# ================================
|
||||
JWT_SECRET=your_secret_key # JWT 서명용 비밀키 (랜덤 문자열 권장)
|
||||
JWT_ALGORITHM=HS256 # JWT 알고리즘 (기본: HS256)
|
||||
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60 # Access Token 만료 시간 (분)
|
||||
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7 # Refresh Token 만료 시간 (일)
|
||||
|
||||
# ================================
|
||||
# 프롬프트 설정
|
||||
# ================================
|
||||
PROMPT_FOLDER_ROOT=./app/utils/prompts # 프롬프트 파일 루트 디렉토리
|
||||
MARKETING_PROMPT_NAME=marketing_prompt # 마케팅 분석용 프롬프트 파일명
|
||||
SUMMARIZE_PROMPT_NAME=summarize_prompt # 요약용 프롬프트 파일명
|
||||
LYLIC_PROMPT_NAME=lyric_prompt # 가사 생성용 프롬프트 파일명
|
||||
|
||||
# ================================
|
||||
# 로그 설정
|
||||
# ================================
|
||||
LOG_CONSOLE_ENABLED=True # 콘솔 로그 출력 여부
|
||||
LOG_FILE_ENABLED=True # 파일 로그 저장 여부
|
||||
LOG_LEVEL=DEBUG # 전체 로그 레벨 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
||||
LOG_CONSOLE_LEVEL=DEBUG # 콘솔 출력 로그 레벨
|
||||
LOG_FILE_LEVEL=DEBUG # 파일 저장 로그 레벨
|
||||
LOG_MAX_SIZE_MB=15 # 로그 파일 최대 크기 (MB)
|
||||
LOG_BACKUP_COUNT=30 # 로그 백업 파일 보관 개수
|
||||
LOG_DIR=logs # 로그 저장 디렉토리 경로
|
||||
# - 절대 경로: 해당 경로 사용
|
||||
# - 상대 경로: 프로젝트 루트 기준
|
||||
# - /www/log/uvicorn 존재 시: 자동으로 해당 경로 사용 (운영)
|
||||
```
|
||||
|
||||
## 실행 방법
|
||||
|
|
@ -110,3 +177,100 @@ fastapi run main.py
|
|||
## API 문서
|
||||
|
||||
서버 실행 후 `/docs` 에서 Scalar API 문서를 확인할 수 있습니다.
|
||||
|
||||
## 서버 아키텍처
|
||||
|
||||
### 전체 시스템 흐름
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Client (Web/Mobile) │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ FastAPI Application │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||||
│ │ Auth API │ │ Home API │ │ Lyric API │ │ Song/Video API │ │
|
||||
│ │ (카카오) │ │ (크롤링) │ │ (가사생성) │ │ (음악/영상 생성) │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
|
||||
└─────────┼────────────────┼────────────────┼─────────────────────┼───────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐
|
||||
│ Kakao OAuth │ │ Naver Maps │ │ ChatGPT │ │ External AI Services │
|
||||
│ (로그인) │ │ (크롤링) │ │ (OpenAI) │ │ ┌───────┐ ┌──────────┐ │
|
||||
└─────────────────┘ └─────────────┘ └─────────────┘ │ │ Suno │ │Creatomate│ │
|
||||
│ │ (음악) │ │ (영상) │ │
|
||||
│ └───────┘ └──────────┘ │
|
||||
└─────────────────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Data Layer │
|
||||
│ ┌─────────────┐ ┌─────────────────────┐ │
|
||||
│ │ MySQL │ │ Azure Blob Storage │ │
|
||||
│ │ (메인 DB) │ │ (미디어 저장소) │ │
|
||||
│ └─────────────┘ └─────────────────────┘ │
|
||||
│ ┌─────────────┐ │
|
||||
│ │ Redis │ │
|
||||
│ │ (캐시/세션) │ │
|
||||
│ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 광고 콘텐츠 생성 플로우
|
||||
|
||||
```
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ 1. 입력 │───▶│ 2. 크롤링 │───▶│ 3. 가사 │───▶│ 4. 음악 │───▶│ 5. 영상 │
|
||||
│ │ │ │ │ 생성 │ │ 생성 │ │ 생성 │
|
||||
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│장소 URL │ │Naver Maps│ │ ChatGPT │ │ Suno AI │ │Creatomate│
|
||||
│or 이미지 │ │ 크롤러 │ │ API │ │ API │ │ API │
|
||||
└────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│장소 정보 │ │ 광고 가사 │ │ MP3 │ │ 광고 영상 │
|
||||
│이미지 수집 │ │ 텍스트 │ │ 파일 │ │ 파일 │
|
||||
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### 인증 플로우 (카카오 OAuth)
|
||||
|
||||
```
|
||||
┌────────┐ ┌────────────┐ ┌───────────┐ ┌────────────┐
|
||||
│ Client │ │ CastAD │ │ Kakao │ │ MySQL │
|
||||
│ │ │ Backend │ │ OAuth │ │ │
|
||||
└───┬────┘ └─────┬──────┘ └─────┬─────┘ └─────┬──────┘
|
||||
│ │ │ │
|
||||
│ 1. 로그인 요청 │ │ │
|
||||
│───────────────▶│ │ │
|
||||
│ │ │ │
|
||||
│ 2. 카카오 URL │ │ │
|
||||
│◀───────────────│ │ │
|
||||
│ │ │ │
|
||||
│ 3. 카카오 로그인 │ │ │
|
||||
│────────────────────────────────▶ │ │
|
||||
│ │ │ │
|
||||
│ 4. 인가 코드 │ │ │
|
||||
│◀──────────────────────────────── │ │
|
||||
│ │ │ │
|
||||
│ 5. 콜백 (code) │ │ │
|
||||
│───────────────▶│ 6. 토큰 요청 │ │
|
||||
│ │─────────────────▶│ │
|
||||
│ │ 7. Access Token │ │
|
||||
│ │◀─────────────────│ │
|
||||
│ │ │ │
|
||||
│ │ 8. 사용자 저장/조회 │ │
|
||||
│ │─────────────────────────────────▶ │
|
||||
│ │◀───────────────────────────────── │
|
||||
│ │ │ │
|
||||
│ 9. JWT 토큰 발급 │ │ │
|
||||
│◀───────────────│ │ │
|
||||
│ │ │ │
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue