Uvicorn ASGI(Asynchronous Server Gateway Interface) 서버 사용방법

Uvicorn은 Python의 ASGI(Asynchronous Server Gateway Interface) 서버로, FastAPI 같은 비동기 웹 프레임워크를 실행할 때 가장 많이 사용되는 고성능 서버입니다. 설치는 pip install uvicorn으로 간단하며, 명령줄이나 코드 내에서 실행할 수 있습니다.

🔹 Uvicorn 기본 개념

• ASGI 서버: 비동기 프로그래밍을 지원하는 Python 서버 인터페이스. Django, FastAPI 등과 호환.
• 지원 프로토콜: HTTP/1.1, WebSocket.
• 주요 특징: 빠른 속도, 낮은 메모리 사용량, 비동기 이벤트 루프(asyncio, uvloop) 지원.

🔹 설치 방법

bash

pip install uvicorn

추가적으로 FastAPI 같은 프레임워크와 함께 사용 시:

bash

pip install fastapi uvicorn

🔹 실행 방법

1. 명령줄 실행

bash

uvicorn main:app --reload --host 0.0.0.0 --port 8000

• main:app → main.py 파일의 app 객체 실행
• --reload → 코드 변경 시 자동 재시작
• --host → 기본값 127.0.0.1, 외부 접속은 0.0.0.0
• --port → 기본값 8000, 원하는 포트 지정 가능

2. Python 코드 내 실행

python

import uvicorn

if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

🔹 주요 옵션 정리

옵션설명

--host	서버가 수신할 호스트 주소 (기본: 127.0.0.1)
--port	포트 번호 (기본: 8000)
--reload	코드 변경 시 자동 재시작
--workers	워커 프로세스 수 지정 (멀티코어 활용)
--loop	이벤트 루프 선택 (asyncio, uvloop)
--http	HTTP 프로토콜 구현 선택 (h11, httptools)
--ws	WebSocket 구현 선택 (websockets, wsproto)

 

 

🔹 FastAPI와 함께 사용 예시

python

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

실행:

bash

uvicorn main:app --reload

🔹 배포 시 고려사항

• 개발 환경: --reload 옵션 사용 (자동 재시작).
• 운영 환경: --workers 옵션으로 멀티 프로세스 실행 → CPU 코어 활용 극대화.
• 컨테이너 환경(Docker/Kubernetes): 보통 워커 대신 단일 프로세스 실행 후 컨테이너 단위로 확장.

 

🔹 개발 환경 (로컬 실행)

개발 단계에서는 코드 변경 시 자동으로 서버가 재시작되도록 --reload 옵션을 사용합니다.

bash

uvicorn main:app --reload --host 0.0.0.0 --port 8000

• --reload: 코드 수정 시 자동 재시작
• --host 0.0.0.0: 외부 접속 허용
• --port 8000: 기본 포트

🔹 운영 환경 (배포)

운영 환경에서는 안정성과 성능을 위해 --reload 대신 멀티 워커를 활용합니다.

1. Uvicorn 단독 실행

bash

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

• CPU 코어 수에 맞춰 워커 개수를 지정하면 성능 향상

2. Gunicorn + Uvicorn Workers

운영 환경에서 가장 많이 쓰는 방식은 Gunicorn과 함께 사용하는 것입니다.

bash

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

• Gunicorn: 프로세스 관리 및 로드 밸런싱 담당
• UvicornWorker: ASGI 서버 실행

🔹 Docker 환경 배포

컨테이너 환경에서는 보통 단일 프로세스로 실행하고, 컨테이너 오케스트레이션(Kubernetes 등)으로 확장합니다.

Dockerfile 예시:

dockerfile

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

🔹 배포 시 고려사항

• Reverse Proxy: Nginx, Traefik 같은 리버스 프록시와 함께 사용 → HTTPS, 로드 밸런싱, 캐싱 지원
• Logging & Monitoring: 운영 환경에서는 로그 관리와 모니터링 필수
• Scaling: Gunicorn 워커 수 조정 또는 컨테이너 확장

🔹 정리

• 개발: uvicorn main:app --reload
• 운영: gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app
• 컨테이너: Dockerfile로 Uvicorn 실행 후 오케스트레이션