Uvicorn — ASGI 웹 서버
Summary
FastAPI 애플리케이션을 실행하는 경량 비동기 웹 서버. ASGI(Asynchronous Server Gateway Interface) 표준 구현.
FastAPI 애플리케이션을 실행하는 경량 비동기 웹 서버. ASGI(Asynchronous Server Gateway Interface) 표준 구현.
개요
ASGI: HTTP 요청을 비동기적으로 처리하는 인터페이스 표준 (WSGI의 현대적 진화).
Uvicorn은:
- 경량 (메모리 적음)
- 빠름 (비동기 I/O)
- FastAPI·Starlette와 네이티브 통합
기본 실행
단일 워커:
uvicorn main:app --host 0.0.0.0 --port 8000main: 모듈명 (main.py)app: FastAPI 인스턴스명--host 0.0.0.0: 모든 네트워크 인터페이스에서 수신--port 8000: 포트 8000
개발 모드 (자동 리로드):
uvicorn main:app --reload코드 변경 시 자동 재시작.
다중 워커
기본: 1개 워커 = 1개 프로세스 = 동시 요청 수 제한
다중 워커 활성화:
uvicorn main:app --workers 4효과:
- 4개 프로세스 병렬 실행
- CPU 다중 코어 활용 (1코어 당 1 프로세스)
- 동시 요청 처리량 ~4배 증가
Docker에서의 Uvicorn
FastAPI 공식 방식 (최신)
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]fastapi run은 Uvicorn을 자동으로 호출 (Starlette 1.4+).
기존 방식 (명시적)
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]Gunicorn + Uvicorn (프로덕션 표준)
FROM tiangolo/uvicorn-gunicorn:python3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENV APP_MODULE=app:appGunicorn = 프로세스 매니저, 자식 Uvicorn 워커 관리 (최적화된 재시작·그레이스풀 셧다운).
CMD 형식: 올바른 사용법
Exec form (권장):
CMD ["uvicorn", "main:app", "--port", "8000"]- 형태: JSON 배열
- 동작: Uvicorn 프로세스가 PID 1로 실행
- 장점: 시그널(SIGTERM) 정상 수신 → 우아한 종료
Shell form (금지):
CMD uvicorn main:app --port 8000- 형태: 문자열
- 동작: /bin/sh가 PID 1로 실행 → Uvicorn은 자식 프로세스
- 문제: Uvicorn이 SIGTERM 미수신 → 강제 종료(SIGKILL) → 무중단 배포 실패
환경변수 설정
ENV PYTHONUNBUFFERED=1 # 즉시 로그 출력
ENV PYTHONDONTWRITEBYTECODE=1 # .pyc 파일 미생성
ENV PORT=8000런타임 오버라이드:
docker run -e PORT=9000 myimage관련 개념
- containerization — Docker에서 Uvicorn 실행
- structured-logging — 요청 로그 출력