[Linux] Uvicorn

Uvicorn이란?

 

Uvicorn은 ASGI 서버입니다.
ASGI(Asynchronous Server Gateway Interface)는 WSGI의 다음 세대로, 비동기 처리를 지원합니다.

 

즉, FastAPI, Django Channels, 최신 웹 프레임워크를 사용할 때는 ASGI 기반의 서버가 필요하고, 그 대표적인 것이 Uvicorn입니다. Django를 사용하면서 uwsgi를 통해 배포를 진행했었고, 비동기 처리를 위해 uvicorn으로 넘어가면서 배운 것들을 정리했습니다. 

---

WSGI vs ASGI

항목	WSGI	ASGI
요청 처리 방식	동기(Sync)	비동기(Async + Sync)
실시간 처리	어렵다	WebSocket, SSE 등 실시간 처리 가능
사용 예	Django, Flask	Fast API, Django Channels
서버 예시	Gunicorn, uWSGI	Uvicorn, Daphne, Hypercorn

 

Uvicorn은 ASGI 스펙을 따르기 때문에 동기와 비동기 코드를 모두 처리할 수 있으며, 고성능이 필요한 실시간 웹 환경에 적합합니다.

---

Uvicorn 실행 및 자동화 설정하기

 

앞서 Nginx 설정에서 요청을 내부 서버인 127.0.0.1:8000으로 전달하도록 구성했기 때문에, 해당 포트에서 실제로 동작하는 Python 서버(Uvicorn)가 준비되어 있어야 합니다.

uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000

 

하지만 실무에서는 매번 수동으로 실행하기보다는 시스템 서비스로 등록해 자동화하는 것이 일반적입니다.

 

systemd 서비스 등록하기

 

리눅스에서는 systemd를 통해 서버 재부팅 시 자동으로 Uvicorn을 실행하도록 설정할 수 있습니다.

 

1. 서비스 유닛 파일 작성

sudo nano /etc/systemd/system/uvicorn.service

 

예시

[Unit]
Description=Uvicorn daemon for Django project
After=network.target

[Service]
User=ubuntu
Group=ubuntu
WorkingDirectory=/home/ubuntu/myproject
Environment="PATH=/home/ubuntu/venv/bin"
ExecStart=/home/ubuntu/venv/bin/uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000

Restart=always

[Install]
WantedBy=multi-user.target

 

프로젝트 경로(WorkingDirectory)와 가상환경(PATH)은 실제 환경에 맞게 수정해야 합니다.

 

2. 서비스 등록 및 실행 

sudo systemctl daemon-reload     # 서비스 파일을 새로 읽어옵니다
sudo systemctl enable uvicorn    # 부팅 시 자동 실행되도록 등록합니다
sudo systemctl start uvicorn     # 서비스를 시작합니다
sudo systemctl status uvicorn    # 실행 상태를 확인합니다

 

이제 서버가 재시작되더라도 Uvicorn은 자동으로 백그라운드에서 실행됩니다.

---

 

전체 구성 흐름 요약

[ 사용자 브라우저 ]
        ↓ optatumai.com 요청 (HTTP/HTTPS)
     ┌─────────────────────┐
     │   Nginx (80/443)     │
     └─────────────────────┘
        ↓ proxy_pass
     ┌─────────────────────┐
     │  Uvicorn (8000포트)  │
     └─────────────────────┘
        ↓
     Django ASGI 애플리케이션

 

Nginx는 외부 요청을 받아 정적 파일은 직접 처리하고,
그 외 모든 요청을 내부의 Uvicorn 서버로 안전하게 전달합니다.

 

(번외) Django를 ASGI 환경에서 배포는 진행 중입니다. 동기 코드로 배포가 되는 것은 확인했으나, 로컬에서 비동기 코드를 사용했을 때 에러를 뿜습니다. 아시는 분 있으면 도와주세요..

 

🧭 다음 글 안내

 

이 글은 Linux 환경에서 Django를 Uvicorm과 함께 배포하는 단계입니다. Nginx와 연동까지 끝마쳤으니, 이제 실제 서비스를 띄울 준비가 끝났습니다.

 

👉 다음 글에서는 EC2 인스턴스 생성과 RDS 연결 방법을 정리합니다. 

[AWS] 웹 애플리케이션 배포하기 (EC2)

 

 

언제나처럼 — 시작은 삽질이지만, 끝은 지식입니다.