[FastAPI] Uvicorn / Gunicorn

Uvicorn / Gunicorn

1. Uvicorn

• FastAPI의 비동기 기능을 지원하는 ASGI 서버로서 실제 요청/응답을 처리.
  • ASGI ↔ WSGI
• 단독 실행 시 단일 프로세스만 사용 → 병목 발생 가능.

2. Gunicorn

• 여러 개의 워커 프로세스를 띄워 병렬 요청 처리를 가능하게 함.
  • CPU 코어 수에 따라 워커를 나눠서 트래픽을 분산시켜 성능 향상.

---

`gunicorn` + `uvicorn.workers.UvicornWorker` 조합

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000

• gunicorn이 여러 워커 프로세스를 실행
  • 각 워커는 uvicorn을 내부적으로 실행
• 비동기 처리(uvicorn) + 병렬 처리(gunicorn)
  • 단점 : 복잡도 증가 (에러 로그 추적), 필요 리소스 증가(멀티 프로세스)

왜 UvicornWorker를 써야 하나?

- Gunicorn은 원래 WSGI 기반 앱(Django, Flask 등)을 위한 서버
- FastAPI는 ASGI 기반이기 때문에, Gunicorn이 바로 실행할 수 없습니다.
    - 그래서 ASGI 서버 역할을 하는 Uvicorn을 워커로 지정해야 합니다.

 

배포 환경에서는 Gunicorn이 프로세스를 관리하고, Uvicorn이 ASGI 요청을 처리하는 구조로 실행해야 FastAPI의 비동기 기능을 최대한 활용하면서도 병렬 요청을 효율적으로 처리할 수 있습니다.