FastAPI 앱을 프로덕션에 어떻게 배포합니까?

Question

Accepted Answer

FastAPI는 **ASGI** 애플리케이션이므로, 프로덕션 배포는 ASGI 서버를 사용합니다. 일반적으로 **Uvicorn**(여러 워커를 위해 흔히 **Gunicorn**이 관리)을 nginx 같은 리버스 프록시 뒤에서 사용합니다. 컨테이너화(Docker)가 일반적인 현대적 접근 방식입니다.

## 프로덕션 서버 스택

```bash
# ❌ 개발 서버(--reload 포함)는 프로덕션용이 아님
uvicorn main:app --reload

# ✅ 프로덕션: Gunicorn이 여러 Uvicorn 워커를 관리 (모든 CPU 코어 사용)
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
# -w 4 → 4개의 워커 프로세스 (경험칙: ~2 × CPU 코어)
```

```text
클라이언트 → NGINX (리버스 프록시: TLS, 정적 파일, 로드 밸런싱)
           → GUNICORN (프로세스 매니저) → UVICORN 워커 (ASGI 앱 실행)
여러 워커가 FastAPI가 여러 CPU 코어를 사용하게 합니다 (각 워커 = 하나의 프로세스).
```

## 앱 Docker화 (일반적)

```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]
```

컨테이너는 환경 전반에서 일관된 배포를 위해 앱과 그 의존성을 패키징합니다(그 후 Kubernetes, ECS, 또는 Railway/Render/Fly 같은 PaaS에서 실행).

## 프로덕션 체크리스트

```text
1. 설정 & 비밀을 환경 변수로 (코드 아님); 시작 시 검증
2. 여러 워커 (Gunicorn + Uvicorn 워커)로 CPU 활용
3. HTTPS/TLS (nginx 또는 플랫폼/로드 밸런서에서)
4. 실제 데이터베이스 (PostgreSQL) + 커넥션 풀링; 마이그레이션 실행 (Alembic)
5. 브라우저 클라이언트를 위해 CORS를 허용 목록으로 설정 ("*" 아님)
6. 로깅 + 오류 모니터링 (Sentry) + 헬스 체크 엔드포인트
7. 백그라운드 작업을 위한 별도 워커 서비스 (Celery/ARQ) + 브로커 (Redis)
8. 수평 확장: 로드 밸런서 뒤의 여러 인스턴스 — 앱을 STATELESS하게 유지
   (세션/상태는 프로세스 메모리가 아닌 Redis에)
```

## async와 무상태성(statelessness)

```text
✓ 각 워커가 자체 이벤트 루프를 실행 → 워커는 병렬성을, async는 동시성을 제공
✓ 로드 밸런서 뒤에서 여러 인스턴스를 실행할 수 있도록 앱을 STATELESS하게 유지
```

## 왜 중요한가

FastAPI를 올바르게 배포하는 것은 애플리케이션을 프로덕션으로 가져가는 데 필수적이며, 개발 설정과 다른 **ASGI** 특성에 특화된 중요한 고려 사항을 수반합니다.

프로덕션 서버 스택을 이해하는 것이 기초입니다: 개발 서버(`uvicorn --reload`)는 프로덕션용이 아니므로, ASGI 서버를 통해 앱을 실행합니다 — 여러 프로세스를 위해 **Gunicorn이 관리하는 Uvicorn 워커**(모든 CPU 코어를 활용, 각 워커가 자체 이벤트 루프를 실행하므로), 일반적으로 TLS와 로드 밸런싱을 위해 nginx 뒤에서. **컨테이너화(Docker)**는 일관되고 이식 가능한 배포를 위한 일반적인 현대적 접근 방식입니다.

서버 설정을 넘어, 프로덕션 체크리스트는 보안 및 신뢰성에 핵심적인 관심사를 다룹니다: 설정과 비밀을 환경 변수로(절대 코드에 아님), HTTPS, 마이그레이션과 풀링이 있는 실제 데이터베이스, 적절한 CORS, 로깅과 모니터링, 백그라운드 작업을 위한 별도 워커 서비스, 그리고 확장을 위한 로드 밸런서 뒤의 **여러 무상태 인스턴스** 실행(상태를 프로세스 메모리가 아닌 Redis에 유지).

올바른 ASGI 서버 스택, 컨테이너화, 여러 워커, 프로덕션 강화로 FastAPI를 배포하는 방법을 아는 것은 중요한 시니어 수준 지식입니다. 모든 실제 FastAPI 애플리케이션은 성능 좋고, 안전하며, 확장 가능하려면 올바르게 배포되어야 하므로, 프로덕션 API를 출시하는 데 자주 관련되고 전문적으로 필수적인 주제입니다.