MENU
  1. ホーム
  2. Column
  3. gunicornでPythonアプリを本番公開！設定からパフォーマンス最適化まで

gunicornでPythonアプリを本番公開！設定からパフォーマンス最適化まで

Column

Flaskアプリを開発して、いざ本番環境にデプロイしようとしたら「flask runでは本番で使えません」と言われた経験ありませんか？開発サーバーは軽量で便利ですが、本番環境ではgunicornのようなWSGIサーバーが必要です。

この記事では、gunicorn --bind 0.0.0.0:$PORT web_dashboard:appのようなコマンドの意味から、実際の本番運用まで実践的に解説します。

目次

開発サーバーから本番環境への移行問題

まず、なぜ開発サーバーではダメなのか理解しましょう。

flask run や python app.py の限界

開発サーバーの問題点：

  • シングルスレッド処理
    ・同時に1つのリクエストしか処理できない
    ・複数ユーザーがアクセスすると遅くなる
  • セキュリティの脆弱性
    ・本番環境向けの設定がされていない
    ・デバッグ機能が有効になっている
  • パフォーマンス不足
    ・負荷に耐えられない
    ・メモリ効率が悪い
# 開発用（本番では使わない）
if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=5000)

gunicornが解決する課題

gunicorn（Green Unicorn）は本番環境に適したWSGIサーバーです：

  • ✅ マルチプロセス・マルチスレッド対応
  • ✅ 高いパフォーマンス
  • ✅ プロダクション向けセキュリティ
  • ✅ 豊富な設定オプション
  • ✅ ゼロダウンタイム再起動

gunicornの基本コマンドと設定

まずは基本的な使い方から見ていきましょう。

インストールと基本起動

# gunicornのインストール
pip install gunicorn

# 基本的な起動
gunicorn app:app

# 詳細指定での起動
gunicorn --bind 0.0.0.0:8000 --workers 4 app:app

コマンドオプションの詳細解説

冒頭のコマンド gunicorn --bind 0.0.0.0:$PORT web_dashboard:app を分解してみましょう：

# コマンドの構成要素
gunicorn \
  --bind 0.0.0.0:$PORT \    # IPアドレスとポート指定
  web_dashboard:app         # モジュール名:アプリケーション変数名

# --bind オプションの説明
# 0.0.0.0: すべてのインターフェースからアクセス可能
# $PORT: 環境変数からポート番号を取得
# web_dashboard: Pythonモジュール（ファイル）名
# app: Flaskアプリケーションオブジェクトの変数名

環境変数との組み合わせ

# 環境変数での設定例
export PORT=8000
export WORKERS=4
export BIND_ADDRESS="0.0.0.0"

# 環境変数を使用した起動
gunicorn --bind $BIND_ADDRESS:$PORT --workers $WORKERS web_dashboard:app

# .env ファイルでの管理
echo "PORT=8000" > .env
echo "WORKERS=4" >> .env
echo "BIND_ADDRESS=0.0.0.0" >> .env

# python-dotenv で読み込み
pip install python-dotenv

実践的な設定例集

実際の開発・本番環境での具体的な設定例を見てみましょう。

基本的なFlaskアプリ構成

# web_dashboard.py - Flaskアプリケーション
from flask import Flask, jsonify
import os

app = Flask(__name__)

@app.route('/')
def home():
    return jsonify({
        "message": "Welcome to Web Dashboard",
        "status": "running",
        "port": os.environ.get('PORT', 'unknown')
    })

@app.route('/health')
def health():
    return jsonify({"status": "healthy"}), 200

@app.route('/api/data')
def get_data():
    # 実際のデータ処理
    return jsonify({
        "data": [1, 2, 3, 4, 5],
        "timestamp": "2024-01-01T00:00:00Z"
    })

# 開発時のみ
if __name__ == '__main__':
    app.run(debug=True)

Docker環境での設定

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# 依存関係のインストール
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# アプリケーションコードのコピー
COPY . .

# ポート設定
ENV PORT=8000
EXPOSE $PORT

# gunicornでの起動
CMD gunicorn --bind 0.0.0.0:$PORT --workers 4 web_dashboard:app
# docker-compose.yml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - PORT=8000
      - FLASK_ENV=production
    volumes:
      - ./logs:/app/logs
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - web

Nginx + gunicorn構成

# nginx.conf
events {
    worker_connections 1024;
}

http {
    upstream gunicorn {
        server web:8000;
    }

    server {
        listen 80;
        server_name localhost;

        # 静的ファイルの配信
        location /static/ {
            alias /app/static/;
            expires 30d;
        }

        # アプリケーションへのプロキシ
        location / {
            proxy_pass http://gunicorn;
            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;
        }

        # ヘルスチェック
        location /health {
            proxy_pass http://gunicorn/health;
            access_log off;
        }
    }
}

環境別設定ファイル

# gunicorn.conf.py - 設定ファイル
import os

# 基本設定
bind = f"0.0.0.0:{os.environ.get('PORT', 8000)}"
workers = int(os.environ.get('WORKERS', 4))
worker_class = "sync"
worker_connections = 1000
max_requests = 1000
max_requests_jitter = 100

# ログ設定
accesslog = "logs/access.log"
errorlog = "logs/error.log"
loglevel = "info"
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'

# プロセス設定
preload_app = True
timeout = 30
keepalive = 2

# 環境別設定
env = os.environ.get('FLASK_ENV', 'production')

if env == 'development':
    reload = True
    loglevel = "debug"
elif env == 'production':
    workers = int(os.environ.get('WORKERS', 2 * os.cpu_count() + 1))
    worker_class = "gevent"
    worker_connections = 1000
# 設定ファイルを使用した起動
gunicorn -c gunicorn.conf.py web_dashboard:app

# 環境変数での起動スクリプト
#!/bin/bash
# start.sh

export FLASK_ENV=${FLASK_ENV:-production}
export PORT=${PORT:-8000}
export WORKERS=${WORKERS:-4}

# ログディレクトリの作成
mkdir -p logs

# gunicorn起動
if [ "$FLASK_ENV" = "development" ]; then
    gunicorn --reload --bind 0.0.0.0:$PORT --workers 1 web_dashboard:app
else
    gunicorn -c gunicorn.conf.py web_dashboard:app
fi

パフォーマンス最適化

gunicornの性能を最大限に引き出すための設定を見ていきましょう。

workerプロセス数の決め方

基本的な計算式：

# CPUバウンドなアプリケーション
workers = (CPU cores * 2) + 1

# I/Oバウンドなアプリケーション
workers = (CPU cores * 4) + 1

# 実際の設定例
export WORKERS=$(python -c "import os; print((os.cpu_count() * 2) + 1)")
echo "Workers: $WORKERS"

worker_classの選択

# gunicorn.conf.py での worker_class 設定

# 同期ワーカー（デフォルト）
# CPU集約的な処理に適している
worker_class = "sync"
workers = 4

# 非同期ワーカー（gevent）
# I/O集約的な処理（DB、API呼び出し）に適している
worker_class = "gevent"
worker_connections = 1000
workers = 2

# 非同期ワーカー（eventlet）
# WebSocketや長時間接続に適している
worker_class = "eventlet"
worker_connections = 1000

# 選択の指針
# - CPU集約的 → sync
# - I/O集約的 → gevent
# - WebSocket → eventlet

メモリ・CPU使用量の監視

# プロセス監視スクリプト
#!/bin/bash
# monitor.sh

while true; do
    echo "=== $(date) ==="
    
    # gunicornプロセスの確認
    ps aux | grep gunicorn | grep -v grep
    
    # メモリ使用量
    echo "Memory usage:"
    ps -o pid,ppid,cmd,%mem,%cpu --sort=-%mem | head -10
    
    # 接続数確認
    echo "Connections:"
    ss -tuln | grep :8000
    
    sleep 30
done

ボトルネック解消法

# アプリケーションレベルでの最適化

from flask import Flask
import time
import threading
from functools import lru_cache

app = Flask(__name__)

# キャッシュの活用
@lru_cache(maxsize=128)
def expensive_calculation(n):
    """重い計算処理のキャッシュ化"""
    time.sleep(0.1)  # 重い処理のシミュレーション
    return n * n

# コネクションプールの使用
from flask_sqlalchemy import SQLAlchemy

app.config['SQLALCHEMY_DATABASE_URI'] = 'postgresql://user:pass@localhost/db'
app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {
    'pool_size': 10,
    'pool_recycle': 120,
    'pool_pre_ping': True,
    'max_overflow': 20
}

db = SQLAlchemy(app)

# 非同期処理の活用
import asyncio
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=4)

@app.route('/async-task')
def async_task():
    def background_task():
        # 重い処理
        time.sleep(2)
        return "Task completed"
    
    future = executor.submit(background_task)
    # 必要に応じてfuture.result()で結果取得
    
    return {"status": "Task started"}

トラブルシューティング

実際の運用でよく遭遇する問題と解決方法をまとめました。

よくあるエラーと解決法

エラー1: “No module named ‘web_dashboard'”

# 原因: Pythonパスの問題
# 解決方法:

# 1. カレントディレクトリで実行
cd /path/to/your/app
gunicorn web_dashboard:app

# 2. PYTHONPATHの設定
export PYTHONPATH=/path/to/your/app:$PYTHONPATH
gunicorn web_dashboard:app

# 3. __init__.py の確認
touch __init__.py  # 必要に応じて作成

エラー2: “Address already in use”

# 原因: ポートがすでに使用されている
# 解決方法:

# 1. 使用中のプロセス確認
lsof -i :8000
netstat -tlnp | grep :8000

# 2. プロセス終了
kill -9 

# 3. 別のポート使用
gunicorn --bind 0.0.0.0:8001 web_dashboard:app

エラー3: “Worker timeout”

# 原因: 処理時間がタイムアウト値を超過
# 解決方法:

# タイムアウト時間の延長
gunicorn --timeout 60 --bind 0.0.0.0:8000 web_dashboard:app

# 設定ファイルでの指定
# gunicorn.conf.py
timeout = 60
graceful_timeout = 30

ログ設定とデバッグ方法

# 詳細ログ設定
# gunicorn.conf.py

import os

# ログディレクトリの作成
os.makedirs('logs', exist_ok=True)

# アクセスログ
accesslog = "logs/access.log"
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'

# エラーログ
errorlog = "logs/error.log"
loglevel = "info"

# アプリケーションログ
capture_output = True

# ログローテーション設定（外部ツールと組み合わせ）
# logrotate設定例
# /etc/logrotate.d/gunicorn
"""
/path/to/app/logs/*.log {
    daily
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 644 www-data www-data
    postrotate
        kill -USR1 $(cat /var/run/gunicorn.pid)
    endscript
}
"""
# デバッグ用コマンド集

# 詳細デバッグ起動
gunicorn --log-level debug --bind 0.0.0.0:8000 web_dashboard:app

# 設定確認
gunicorn --check-config -c gunicorn.conf.py web_dashboard:app

# プロセス確認
ps aux | grep gunicorn

# ログのリアルタイム監視
tail -f logs/access.log
tail -f logs/error.log

# 接続テスト
curl -I http://localhost:8000/
curl http://localhost:8000/health

Python Web開発をさらに極める関連記事

gunicornでの本番デプロイを習得したら、AI開発支援ツールやプロジェクト管理ツールも活用してより効率的な開発環境を構築しましょう：

🤖 AI開発支援・コード管理

📊 開発効率化・可視化ツール

まとめ：本番環境への確実なデプロイ

gunicornを使用することで、開発環境から本番環境への移行が安全かつ効率的に行えます。適切な設定により、高いパフォーマンスと安定性を実現できます。

今日から始められるアクション：

  • 既存のFlaskアプリをgunicornで起動してみる
  • 環境別の設定ファイルを作成する
  • Docker環境でのデプロイを試す
  • ログ監視とパフォーマンス測定を導入する

次回のプロジェクトでは、ぜひgunicornを活用して「安定して動作する」本番環境を構築してみてください！

gunicorn デプロイ よくある質問

❓ HerokuやVercelでもgunicornは使用できますか？

Herokuでは一般的にgunicornが使用されます。Procfileに「web: gunicorn app:app」と記述するだけです。VercelはNode.jsメインのプラットフォームですが、Python関数としてデプロイ可能です。AWS LambdaやGoogle Cloud Functionsなどサーバーレス環境では、gunicornではなく専用のハンドラーを使用します。

❓ worker数が多いほど性能は向上しますか？

必ずしもそうではありません。CPUコア数を大幅に超えるworker数は、コンテキストスイッチのオーバーヘッドでかえって性能が悪化します。基本は「(CPUコア数 × 2) + 1」から始めて、負荷テストで最適値を見つけることが重要です。メモリ使用量も考慮して調整してください。

❓ gunicornでSSL証明書は設定できますか？

gunicornでもSSL設定は可能ですが、一般的にはNginxやCloudflarなどのリバースプロキシでSSL終端することを推奨します。gunicornは–certfileと–keyfileオプションでSSL設定できますが、証明書の自動更新やセキュリティ設定の柔軟性を考慮すると、専用のプロキシサーバーを使用する方が運用しやすいです。

❓ ゼロダウンタイムデプロイはどうやって実現しますか？

gunicornのUSR2シグナルを使用してゼロダウンタイムデプロイが可能です。「kill -USR2 <マスタープロセスPID>」で新しいマスタープロセスを起動し、古いworkerを順次置き換えます。より確実な方法として、ロードバランサー（Nginx、ALB等）で複数のgunicornインスタンスを順次更新する手法も一般的です。

Column
API開発 ソフトウェアエンジニアリング テック人材
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

目次