DocsPricingBlog
Contact Us
Log inSign up for FREE
Back to Tech Articles

Gunicorn, Uvicorn, Nginx를 사용한 Python 웹 애플리케이션 프로덕션 배포

Aug 04, 2025
# Misc

Grace Collins

Solutions Engineer · Leapcell

This post is also available in English, 日本語, and Deutsch
Cover of "Gunicorn, Uvicorn, Nginx를 사용한 Python 웹 애플리케이션 프로덕션 배포"

소개

활기찬 Python 웹 개발의 세계에서 강력한 애플리케이션을 구축하는 것은 종종 첫 번째 단계에 불과합니다. 진정한 도전은 특히 실제 트래픽과 수요에 직면했을 때 이러한 애플리케이션을 최종 사용자에게 접근 가능하고 성능이 뛰어나며 안정적으로 만드는 데 있습니다. Flask 또는 FastAPI와 같은 프레임워크를 내장 개발 서버를 사용하여 직접 실행하는 것은 로컬 테스트에만 적합하며 프로덕션에는 적합하지 않습니다. 이러한 개발 서버는 일반적으로 단일 스레드이며 보안, 확장성 및 동시 요청의 견고한 처리에 필요한 기능이 부족합니다. 이 격차는 프로덕션 등급 배포 전략의 중요성에 대한 필요성을 제기합니다. Nginx와 같은 강력한 웹 서버와 Gunicorn 또는 Uvicorn과 같은 Python 전용 애플리케이션 서버를 효과적으로 결합하는 방법을 이해하는 것은 모든 진지한 Python 개발자에게 필수적입니다. 이 문서는 이 검증된 아키텍처를 사용하여 Python 웹 애플리케이션을 배포하는 모범 사례를 자세히 살펴보고 애플리케이션이 기능적일 뿐만 아니라 프로덕션 준비가 되어 있는지 확인합니다.

핵심 개념 설명

프로덕션 환경의 배포 세부 정보에 들어가기 전에 핵심 구성 요소를 정의해 보겠습니다.

WSGI (Web Server Gateway Interface): 웹 서버와 웹 애플리케이션 또는 프레임워크 간의 표준 Python 인터페이스입니다. 웹 서버가 Python 웹 애플리케이션과 통신하는 방법을 지정하여 다양한 웹 서버와 Python 프레임워크(예: Django, Flask) 간의 상호 운용성을 가능하게 합니다. Gunicorn은 WSGI HTTP 서버입니다.

ASGI (Asynchronous Server Gateway Interface): WSGI와 유사하게 ASGI는 비동기 Python 웹 애플리케이션을 위해 설계된 새로운 표준입니다. 기존의 동기식 요청과 WebSockets와 같은 장기 연결을 모두 지원합니다. Uvicorn은 ASGI HTTP 서버입니다.

Gunicorn (Green Unicorn): Unix용 Python WSGI HTTP 서버입니다. 사전 포크 작업자 모델 서버이므로 마스터 프로세스가 여러 작업자 프로세스를 포크합니다. 각 작업자는 요청을 순차적으로 처리하여 여러 CPU 코어를 활용하여 성능을 향상시킵니다. Gunicorn은 동기식 Python 웹 애플리케이션에 이상적입니다.

Uvicorn: Python을 위한 ASGI 서버 구현입니다. Uvicorn은 uvloop와 httptools를 기반으로 구축되어 매우 빠릅니다. FastAPI, Starlette, Quart와 같은 비동기 Python 웹 프레임워크를 실행하도록 설계되었으며, 래퍼를 통해 동기식 WSGI 애플리케이션도 제공할 수 있습니다.

Nginx: 고성능 오픈 소스 HTTP 및 역방향 프록시 서버입니다. Nginx는 안정성, 풍부한 기능 세트, 간단한 구성 및 낮은 리소스 소비로 유명합니다. 정적 파일 제공, 로드 밸런싱, SSL 종료 및 적절한 백엔드 애플리케이션 서버로 들어오는 클라이언트 요청을 전달하는 역방향 프록시 역할을 탁월합니다.

역방향 프록시: 하나 이상의 웹 서버 앞에 위치하여 클라이언트의 요청을 가로채는 서버입니다. 그런 다음 요청을 적절한 백엔드 서버로 전달하고 응답을 검색하여 클라이언트로 다시 보냅니다. 이를 통해 로드 밸런싱, 향상된 보안, SSL 종료 및 정적 파일 제공과 같은 이점을 얻을 수 있습니다.

배포 아키텍처 및 구현

최적의 배포 전략은 Gunicorn 또는 Uvicorn 앞에 Nginx를 역방향 프록시로 사용하는 것을 포함합니다. 아키텍처와 구현 방법에 대한 자세한 내용은 다음과 같습니다.

아키텍처 설명

  1. 클라이언트 요청: 사용자의 웹 브라우저가 도메인(예: yourdomain.com)으로 HTTP 요청을 보냅니다.
  2. Nginx (역방향 프록시): Nginx는 표준 HTTP/HTTPS 포트(80/443)에서 수신 대기합니다. 요청을 가로챕니다.
    • 요청이 정적 파일(이미지, CSS, JavaScript)인 경우 Nginx가 직접 제공하며, 이는 Python보다 훨씬 빠릅니다.
    • 요청이 동적 콘텐츠(API 엔드포인트, Python 앱에서 생성된 HTML 페이지)인 경우 Nginx는 요청을 Gunicorn/Uvicorn 서버로 전달합니다.
    • Nginx는 SSL/TLS 종료, 캐싱, 속도 제한 및 잠재적으로 여러 애플리케이션 서버 인스턴스에 대한 로드 밸런싱도 처리합니다.
  3. Gunicorn/Uvicorn (애플리케이션 서버): 이 서버는 Python 웹 애플리케이션을 실행합니다. 특정 포트 또는 Unix 소켓(예: localhost:8000)에서 수신 대기합니다. Nginx로부터 요청을 받으면 Python 애플리케이션으로 전달합니다.
    • Gunicorn은 작업자 프로세스 풀을 사용하여 동기식 요청을 효율적으로 처리합니다.
    • Uvicorn은 이벤트 루프와 작업자 프로세스를 사용하여 비동기 요청을 처리합니다.
  4. Python 웹 애플리케이션 (Flask/FastAPI/Django): 애플리케이션은 요청을 처리하고, 데이터베이스와 상호 작용하고, 로직을 수행하고, 응답을 생성합니다.
  5. 응답 반환: 애플리케이션은 응답을 Gunicorn/Uvicorn으로 보내고, Gunicorn/Uvicorn은 이를 Nginx로 보내고, 최종적으로 Nginx는 클라이언트로 보냅니다.

단계별 구현

간단한 FastAPI 애플리케이션(Uvicorn이 ASGI용으로 설계되었으므로)을 사용하여 설정을 시연해 보겠습니다. 원칙은 Gunicorn을 사용하는 Flask/Django의 경우에도 유사하며, 애플리케이션 서버만 바꾸면 됩니다.

프로젝트 구조 예시:

my_webapp/
├── app.py
├── requirements.txt
├── gunicorn_config.py (optional, for Gunicorn)
└── uvicorn_config.py (optional, for Uvicorn)

1. 간단한 FastAPI 애플리케이션 만들기 (app.py):

# app.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello from FastAPI!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "message": "This is an item"}

2. 종속성 정의 (requirements.txt):

fastapi
uvicorn[standard]
# For Gunicorn: gunicorn

3. 종속성 설치:

pip install -r requirements.txt

4. Uvicorn (FastAPI/ASGI) 또는 Gunicorn (Flask/Django/WSGI) 실행:

Uvicorn 사용:

명령줄에서 Uvicorn을 직접 실행할 수 있습니다. 프로덕션의 일반적인 방법은 더 복잡한 구성을 위해 uvicorn_config.py 스크립트를 사용하거나 systemd 서비스에서 직접 사용하는 것입니다.

# 개발용 기본 실행
uvicorn app:app --host 0.0.0.0 --port 8000

프로덕션의 경우 일반적으로 구성 파일이나 인수를 직접 전달하여 사용합니다.

# systemd 서비스 내의 프로덕션용 Uvicorn 명령 예시
# --workers 인수를 사용하면 Uvicorn이 여러 작업자 프로세스를 실행할 수 있습니다.
# TCP localhost보다 성능 향상을 위해 Unix 소켓에 바인딩하는 것이 좋을 수 있습니다.
# uvicorn app:app --workers 4 --unix /tmp/uvicorn.sock
uvicorn app:app --workers 4 --host 127.0.0.1 --port 8000

주요 Uvicorn 인수: * app:app: app.py 내의 FastAPI 인스턴스(app 객체)를 가리킵니다. * --workers N: 작업자 프로세스 수를 지정합니다. 일반적인 권장 사항은 N이 CPU 코어 수일 때 2 * N + 1입니다. * --host 127.0.0.1 --port 8000: Uvicorn을 localhost의 포트 8000에 바인딩합니다. Nginx 통합의 경우 약간의 성능 향상과 더 간단한 권한 관리를 위해 Unix 소켓에 바인딩하는 것이 종종 선호됩니다. 예: --unix /tmp/uvicorn.sock.

Gunicorn 사용 (Flask 앱 app.py에서 app = Flask(__name__) 사용 예시):

# 개발용 기본 실행
gunicorn app:app --bind 0.0.0.0:8000

프로덕션을 위한 경우:

# 프로덕션용 Gunicorn 명령 예시
gunicorn app:app --workers 4 --bind 127.0.0.1:8000
# 또는 Unix 소켓에 바인딩
# gunicorn app:app --workers 4 --bind unix:/tmp/gunicorn.sock

주요 Gunicorn 인수: * app:app: Flask/Django 애플리케이션 인스턴스를 가리킵니다. * --workers N: Uvicorn과 유사하게 작업자 프로세스 수를 결정합니다. * --bind 127.0.0.1:8000 또는 --bind unix:/tmp/gunicorn.sock: Gunicorn이 수신 대기할 주소 및 포트 또는 Unix 소켓을 지정합니다.

5. Nginx를 역방향 프록시로 구성:

Nginx가 표준 HTTP/HTTPS 포트에서 요청을 수신 대기하고 애플리케이션 서버로 전달하도록 지시해야 합니다. Nginx 구성 파일(sites-available/your_app 또는 OS에 따라 유사한 위치)에 새 Nginx 구성을 만듭니다.

# /etc/nginx/sites-available/your_app
server {
    listen 80;
    server_name your_domain.com www.your_domain.com; # 도메인으로 바꾸세요

    # 선택 사항: HTTP를 HTTPS로 리디렉션 (프로덕션에서 강력히 권장)
    # return 301 https://$host$request_uri;
    
    location /static/ {
        # Nginx에서 직접 정적 파일 제공 (예: 이미지, CSS, JS)
        # 이 경로가 존재하고 애플리케이션의 정적 파일 제공 설정과 일치하는지 확인
        alias /var/www/your_app/static/; 
        expires 30d; # 브라우저에서 정적 파일 캐시
        add_header Cache-Control "public";
    }

    location / {
        # 나머지 요청을 Uvicorn/Gunicorn 서버로 전달
        proxy_pass http://127.0.0.1:8000; # Uvicorn/Gunicorn이 바인딩하는 IP/포트 사용
        # Unix 소켓을 사용하는 경우: proxy_pass http://unix:/tmp/uvicorn.sock;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 선택 사항: 잠재적으로 긴 요청에 대한 제한 시간 증가
        proxy_connect_timeout 75s;
        proxy_send_timeout 75s;
        proxy_read_timeout 75s;
    }
}

# 선택 사항: SSL 종료를 위한 HTTPS용 서버 블록
# server {
#     listen 443 ssl;
#     server_name your_domain.com www.your_domain.com;

#     ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
#     ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;
#     ssl_session_cache shared:SSL:10m;
#     ssl_session_timeout 10m;
#     ssl_protocols TLSv1.2 TLSv1.3;
#     ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
#     ssl_prefer_server_ciphers on;

#     location / {
#         proxy_pass http://127.0.0.1:8000;
#         proxy_set_header Host $host;
#         proxy_set_header X-Real-IP $remote_addr;
#         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
#         proxy_set_header X-Forwarded-Proto $scheme;
#     }
# }

구성을 만든 후 심볼릭 링크를 만들어 Nginx 구성을 테스트합니다.

sudo ln -s /etc/nginx/sites-available/your_app /etc/nginx/sites-enabled/
sudo nginx -t # Nginx 구성 테스트
sudo systemctl restart nginx # Nginx 재시작

6. 프로세스 관리를 위해 Systemd 사용:

Uvicorn/Gunicorn 서버가 지속적으로 실행되고 실패하거나 재부팅 시 자동으로 다시 시작되도록 하려면 systemd와 같은 프로세스 관리자를 사용합니다. 서비스 파일(예: /etc/systemd/system/your_app.service)을 만듭니다.

# /etc/systemd/system/your_app.service
[Unit]
Description=Your FastAPI application
After=network.target

[Service]
User=your_user # 루트가 아닌 사용자로 바꾸세요
Group=your_group # 적절한 그룹으로 바꾸세요
WorkingDirectory=/path/to/my_webapp # 실제 프로젝트 경로로 바꾸세요
Environment="PATH=/path/to/your/venv/bin" # Python 가상 환경 경로
ExecStart=/path/to/your/venv/bin/uvicorn app:app --workers 4 --host 127.0.0.1 --port 8000
# Gunicorn의 경우: ExecStart=/path/to/your/venv/bin/gunicorn app:app --workers 4 --bind 127.0.0.1:8000
# Unix 소켓을 사용하는 경우: ExecStart=/path/to/your/venv/bin/uvicorn app:app --workers 4 --unix /tmp/uvicorn.sock
Restart=always

[Install]
WantedBy=multi-user.target

서비스를 사용 설정하고 시작합니다.

sudo systemctl daemon-reload # systemd 다시 로드
sudo systemctl start your_app
sudo systemctl enable your_app # 부팅 시 사용 설정
sudo systemctl status your_app # 상태 확인

애플리케이션 시나리오 및 모범 사례

  • 소규모 및 중규모 웹 앱: 이 설정은 대부분의 소규모 및 중규모 웹 애플리케이션 및 API에 충분히 강력합니다. Nginx는 정적 파일을 효율적으로 처리하고 게이트웨이 역할을 합니다.
  • API 백엔드: FastAPI 또는 Flask REST API를 제공하는 데 탁월하며, Uvicorn의 비동기 기능 또는 Gunicorn의 작업자 모델을 사용하여 효율적인 요청 처리가 가능합니다.
  • 정적 파일 제공: 항상 Nginx가 정적 자산을 처리하도록 하십시오. 이는 Python 애플리케이션의 부하를 크게 줄이고 이미지, CSS 및 JavaScript에 대한 응답 시간을 개선합니다.
  • 로드 밸런싱: 높은 트래픽 애플리케이션의 경우 여러 Uvicorn/Gunicorn 인스턴스(다른 서버에 있을 수 있음)를 실행하고 Nginx가 요청을 분산하도록 구성할 수 있습니다.
  • 보안: Nginx는 속도 제한, WAF 통합 및 SSL/TLS 암호화와 같은 보안 조치를 구현할 수 있습니다.
  • 로깅: Nginx 및 애플리케이션 서버(Uvicorn/Gunicorn) 모두 표준 출력 또는 파일로 기록하도록 구성하고 분석을 위해 로그 관리 시스템을 사용하십시오.
  • 모니터링: Nginx, 애플리케이션 서버 및 Python 애플리케이션의 상태 및 성능을 추적하기 위해 모니터링 도구를 통합하십시오.

결론

프로덕션을 위한 Python 웹 애플리케이션 배포는 개발 서버를 실행하는 것 이상을 요구합니다. 성능이 뛰어난 역방향 프록시로서 Nginx와 강력한 애플리케이션 서버로서 Gunicorn/Uvicorn의 조합은 확장 가능하고 안정적이며 효율적인 배포 전략의 기반을 형성합니다. 각 구성 요소를 신중하게 구성하여-작업자 프로세스 및 바인딩 주소를 현명하게 설정하고, Nginx가 정적 파일 및 SSL을 처리하도록 함-개발자는 Python 애플리케이션이 프로덕션 환경의 요구 사항을 충족하도록 보장할 수 있습니다. 이 아키텍처 패턴은 모범 사례일 뿐만 아니라 안전하고 성능이 뛰어난 고품질의 프로덕션 준비 Python 웹 서비스를 구축하기 위한 기본 단계입니다.

Share this article

HackerNews

More Posts from Leapcell

Popular Posts