⚙️ Python Gunicorn

Python Web 應用的 WSGI HTTP 伺服器

Gunicorn(Green Unicorn)是穩定成熟的 Python WSGI 伺服器,常搭配 Nginx 反向代理部署 Django、Flask、FastAPI 等 Python Web 框架。

安裝

$ # 在虛擬環境中安裝(推薦)
python3 -m venv /opt/myapp/venv
source /opt/myapp/venv/bin/activate
pip install gunicorn

# 確認安裝
gunicorn --version

啟動 Python 應用

假設 Django 專案,myproject/wsgi.py 為 WSGI 入口點:

$ # Django
gunicorn myproject.wsgi:application \
  --bind 127.0.0.1:8000 \
  --workers 4 \
  --timeout 120

# Flask(app.py 中有 app = Flask(__name__))
gunicorn app:app --bind 127.0.0.1:8000 --workers 4

# FastAPI(需額外安裝 uvicorn)
pip install uvicorn[standard]
gunicorn main:app --worker-class uvicorn.workers.UvicornWorker \
  --bind 127.0.0.1:8000 --workers 4

設定為 systemd 服務

$ sudo vim /etc/systemd/system/myapp.service
[Unit]
Description=MyApp Gunicorn Server
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/myapp
Environment="PATH=/opt/myapp/venv/bin"
Environment="DJANGO_SETTINGS_MODULE=myproject.settings.production"
ExecStart=/opt/myapp/venv/bin/gunicorn \
    --workers 4 \
    --bind unix:/run/myapp/gunicorn.sock \
    --access-logfile /var/log/myapp/access.log \
    --error-logfile  /var/log/myapp/error.log \
    myproject.wsgi:application
Restart=on-failure
RuntimeDirectory=myapp

[Install]
WantedBy=multi-user.target
$ sudo mkdir -p /var/log/myapp
sudo chown www-data:www-data /var/log/myapp
sudo systemctl enable --now myapp

與 Nginx 整合

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass         http://unix:/run/myapp/gunicorn.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_read_timeout 120s;
    }

    location /static/ {
        alias /opt/myapp/staticfiles/;
        expires 30d;
    }

    location /media/ {
        alias /opt/myapp/media/;
    }
}

Worker 類型與數量建議

Worker 類型適用場景安裝
sync(預設)一般 Django/Flask,同步 I/O無需額外安裝
gevent高並發、長連線(如 SSE)pip install gevent
uvicorn.workers.UvicornWorkerFastAPI、async 應用pip install uvicorn
💡 Worker 數量建議:2 × CPU 核心數 + 1。例如 4 核心機器建議 9 個 worker。記憶體不足時適當減少。