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

Gunicorn, Uvicorn、Nginx を使用した Python Web アプリケーションのプロダクションデプロイ

Aug 04, 2025
# Misc

Grace Collins

Solutions Engineer · Leapcell

This post is also available in English, 한국어, and Deutsch
Cover of "Gunicorn, Uvicorn、Nginx を使用した Python Web アプリケーションのプロダクションデプロイ"

はじめに

Python Web 開発の活気に満ちた世界では、強力なアプリケーションの構築がしばしば最初のステップにすぎません。真の課題は、特に実際のトラフィックや需要に直面した場合に、これらのアプリケーションをエンドユーザーが利用可能で、パフォーマンスが高く、信頼性の高いものにすることです。Flask や FastAPI のようなフレームワークを組み込みの開発サーバーで直接実行することは、ローカル テストには適していますが、プロダクションには適していません。これらの開発サーバーは通常シングルスレッドであり、セキュリティ、スケーラビリティ、および同時リクエストの堅牢な処理に必要な機能が欠けています。このギャップにより、プロダクショングレードのデプロイ戦略の重要な必要性が生じます。Nginx のような強力な Web サーバーと Gunicorn や Uvicorn のような Python 固有のアプリケーション サーバーを効果的に組み合わせる方法を理解することは、あらゆる真剣な Python 開発者にとって非常に重要です。この記事では、この実績のあるアーキテクチャを使用して Python Web アプリケーションをデプロイするためのベストプラクティスについて詳しく説明し、アプリケーションが機能的であるだけでなく、プロダクションに対応していることを保証します。

コアコンセプトの説明

プロダクション環境のデプロイメントの詳細に入る前に、主要な要素を定義しましょう。

WSGI (Web Server Gateway Interface): Web サーバーと Web アプリケーションまたはフレームワーク間の標準 Python インターフェイスです。Web サーバーが Python Web アプリケーションと通信する方法を指定し、さまざまな Web サーバーと Python フレームワーク (Django、Flask など) 間の相互運用性を可能にします。Gunicorn は WSGI HTTP サーバーです。

ASGI (Asynchronous Server Gateway Interface): WSGI に似ていますが、ASGI は非同期 Python Web アプリケーションのために設計された新しい標準です。従来の同期リクエストと WebSockets のような長寿命接続の両方をサポートします。Uvicorn は ASGI HTTP サーバーです。

Gunicorn (Green Unicorn): Unix 用の Python WSGI HTTP サーバーです。プリフォークワーカーモデルのサーバーであり、マスタープロセスが起動し、複数のワーカープロセスをフォークします。各ワーカーはリクエストを順次処理し、複数の CPU コアを活用することでパフォーマンスを向上させます。Gunicorn は同期 Python Web アプリケーションに最適です。

Uvicorn: Python 用の ASGI サーバー実装です。Uvicorn は uvloop と httptools をベースにしており、非常に高速です。FastAPI、Starlette、Quart のような非同期 Python Web フレームワークを実行するように設計されており、ラッパーを介して同期 WSGI アプリケーションを提供することもできます。

Nginx: 高性能なオープンソースの HTTP およびリバースプロキシサーバーです。Nginx は、その安定性、豊富な機能セット、シンプルな構成、および低いリソース消費で知られています。静的ファイルの提供、ロード バランシング、SSL 終端、およびクライアント リクエストを適切なバックエンド アプリケーション サーバーに転送するリバース プロキシとして優れています。

リバース プロキシ: 1 つ以上の Web サーバーの前に配置され、クライアントからのリクエストをインターセプトするサーバーです。次に、これらのリクエストを適切なバックエンド サーバーに転送し、応答を取得してクライアントに送信します。これにより、ロード バランシング、セキュリティの強化、SSL 終端、静的ファイル提供などのメリットが得られます。

デプロイメントアーキテクチャと実装

最適なデプロイメント戦略は、Nginx を Gunicorn または Uvicorn の前面でリバース プロキシとして使用することです。アーキテクチャとその実装方法の内訳を以下に示します。

アーキテクチャの説明

  1. クライアントリクエスト: ユーザーの Web ブラウザがドメイン (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 Web アプリケーションを実行します。特定のポートまたは Unix ソケット (localhost:8000 など) でリッスンします。Nginx からリクエストを受信すると、Python アプリケーションに渡します。
    • Gunicorn は、同期リクエストを効率的に処理するために、ワーカー プロセスのプールを使用します。
    • Uvicorn は、イベント ループとワーカー プロセスを使用して非同期リクエストを処理します。
  4. Python Web アプリケーション (Flask/FastAPI/Django): アプリケーションはリクエストを処理し、データベースと対話し、ロジックを実行し、応答を生成します。
  5. 応答バック: アプリケーションは 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 サービスで直接使用するのが一般的です。

# Basic run for development
uvicorn app:app --host 0.0.0.0 --port 8000

プロダクションでは、通常、構成ファイルを使用するか、引数を直接渡します。

# Example for a production Uvicorn command within a systemd service
# The --workers argument allows Uvicorn to run multiple worker processes.
# You might want to bind to a Unix socket for better performance over TCP localhost
# 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__) の例):

# Basic run for development
gunicorn app:app --bind 0.0.0.0:8000

プロダクションの場合:

# Example for a production Gunicorn command
gunicorn app:app --workers 4 --bind 127.0.0.1:8000
# Or bind to a Unix socket
# 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 構成ファイル (OS によって異なりますが、/etc/nginx/sites-available/your_app など) で新しいファイルを作成します。

# /etc/nginx/sites-available/your_app
server {
    listen 80;
    server_name your_domain.com www.your_domain.com; # Replace with your domain

    # Optional: Redirect HTTP to HTTPS (highly recommended for production)
    # return 301 https://$host$request_uri;
    
    location /static/ {
        # Serve static files directly from Nginx (e.g., images, CSS, JS)
        # Ensure this path exists and matches your application's static file serving setup
        alias /var/www/your_app/static/; 
        expires 30d; # Cache static files in browser
        add_header Cache-Control "public";
    }

    location / {
        # Forward all other requests to the Uvicorn/Gunicorn server
        proxy_pass http://127.0.0.1:8000; # Use the IP/port your Uvicorn/Gunicorn binds to
        # OR if using a Unix socket: 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;
        
        # Optional: Increase timeout for potentially long requests
        proxy_connect_timeout 75s;
        proxy_send_timeout 75s;
        proxy_read_timeout 75s;
    }
}

# Optional: Server block for HTTPS with SSL termination
# 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 # Test Nginx configuration
sudo systemctl restart nginx # Restart 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 # Replace with a non-root user
Group=your_group # Replace with appropriate group
WorkingDirectory=/path/to/my_webapp # Replace with your actual project path
Environment="PATH=/path/to/your/venv/bin" # Path to your Python virtual environment
ExecStart=/path/to/your/venv/bin/uvicorn app:app --workers 4 --host 127.0.0.1 --port 8000
# For Gunicorn: ExecStart=/path/to/your/venv/bin/gunicorn app:app --workers 4 --bind 127.0.0.1:8000
# If using a Unix socket: 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 # Reload systemd
sudo systemctl start your_app
sudo systemctl enable your_app # Enable on boot
sudo systemctl status your_app # Check status

アプリケーションシナリオとベストプラクティス

  • 中小規模の Web アプリケーション: このセットアップは、ほとんどの中小規模の Web アプリケーションや 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 Web アプリケーションをデプロイするには、開発サーバーを実行する以上のことが必要です。Nginx を高性能なリバース プロキシとして、Gunicorn/Uvicorn を堅牢なアプリケーション サーバーとして組み合わせることで、スケーラブルで信頼性の高い効率的なデプロイメント戦略のバックボーンが形成されます。各コンポーネントを慎重に構成する — ワーカー プロセスの数とバインド アドレスを賢く設定し、Nginx に静的ファイルと SSL を処理させることから始めます — 開発者は Python アプリケーションがプロダクション環境の要求に耐えられるようにすることができます。このアーキテクチャ パターンはベスト プラクティスであるだけでなく、安全でパフォーマンスの高い、本番環境対応の Python Web サービスを構築するための基本的なステップです。

Share this article

HackerNews

More Posts from Leapcell

Popular Posts