uWSGI 是功能最豐富的 Python 應用伺服器,支援 WSGI、uwsgi、HTTP、FastCGI 多種協定,內建進程管理、緩存、路由、訂閱、Emperor 多應用編排。配合 Nginx 反向代理,是現代 Python 生產部署的黃金組合。
# 官方 PPA(較新版本)
add-apt-repository ppa:stevecrozz/ppa
apt-get update
apt-get install uwsgi uwsgi-plugin-python3
# 或使用 pip(虛擬環境內)
pip install uwsgi
# /etc/nginx/sites-available/myapp
server {
listen 80;
server_name myapp.example.com;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:9090; # 或 unix:/run/uwsgi/myapp.sock
}
location /static {
alias /var/www/myapp/static;
expires 30d;
}
}
# 專案 wsgi.py 模組變數名為 application
uwsgi --http-socket :9090 --module myapp.wsgi:application --master --processes 4 --threads 2
# myapp/wsgi.py
import os
from django.core.wsgi import get_wsgi_application
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myapp.settings')
application = get_wsgi_application()
| 參數 | 說明 | 建議值 |
|---|---|---|
--socket / --http-socket | 監聽位址(UNIX socket 較快、安全) | unix:/run/uwsgi/app.sock |
--module | WSGI 模組路徑 pkg.module:application | myproject.wsgi:application |
--master | 啟用 Master 進程(管理 worker、平滑重載) | 必開 |
--processes / -p | Worker 進程數 | CPU 核心數 × 2 |
--threads | 每進程執行緒數 | 10-64 (I/O 密集) |
--harakiri | 請求超時秒數(殺掉卡住 worker) | 30-60 |
--limit-as | 單進程虛擬記憶體上限(MB) | 256-1024 |
--max-requests | 處理 N 請求後重啟 worker(防記憶體洩漏) | 1000-5000 |
--daemonize | 前台/後台模式與日誌檔 | /var/log/uwsgi/app.log |
--vhost | 虛擬主機模式(動態載入應用) | 多站共用一 uWSGI 實例 |
--pythonpath | 加入 Python 搜尋路徑 | /var/www/myapp |
--chdir | 切換工作目錄 | /var/www/myapp |
--virtualenv | 指定虛擬環境路徑 | /opt/venv/myapp |
--env | 設定環境變數 | DJANGO_SETTINGS_MODULE=prod |
uwsgi --socket :9090 --master --processes 4 --threads 10 --vhost \
--limit-as 128 --harakiri 30 --max-requests 10000 \
--daemonize /var/log/uwsgi/emperor.log
apt-get install python3-virtualenv
virtualenv /var/www/shared-env
source /var/www/shared-env/bin/activate
pip install django flask requests ...
# site1
server {
listen 80;
server_name app1.example.com;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:9090;
uwsgi_param UWSGI_PYHOME /var/www/shared-env;
uwsgi_param UWSGI_SCRIPT app1.wsgi:application;
uwsgi_param UWSGI_CHDIR /var/www/app1;
}
}
# site2
server {
listen 80;
server_name app2.example.com;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:9090;
uwsgi_param UWSGI_PYHOME /var/www/shared-env;
uwsgi_param UWSGI_SCRIPT app2.wsgi:application;
uwsgi_param UWSGI_CHDIR /var/www/app2;
}
}
關鍵參數:
UWSGI_PYHOME:虛擬環境路徑(對應 --virtualenv)UWSGI_SCRIPT:WSGI 模組路徑(對應 --module)UWSGI_CHDIR:工作目錄(對應 --chdir)Emperor 監控 vassals 目錄下的 .ini 檔案,自動啟動/重載/停止對應應用,各應用擁有獨立進程池、虛擬環境、使用者身分,隔離性最佳。
# /etc/systemd/system/uwsgi-emperor.service
[Unit]
Description=uWSGI Emperor
After=network.target
[Service]
ExecStart=/usr/local/bin/uwsgi --emperor /etc/uwsgi/vassals --uid www-data --gid www-data --logto /var/log/uwsgi/emperor.log
Restart=on-failure
KillSignal=SIGQUIT
Type=notify
StandardError=syslog
NotifyAccess=all
[Install]
WantedBy=multi-user.target
# /etc/uwsgi/vassals/app1.ini
[uwsgi]
chdir = /var/www/app1
module = wsgi:application
virtualenv = /opt/venv/app1
socket = /run/uwsgi/app1.sock
chmod-socket = 660
master = true
processes = 2
threads = 15
harakiri = 30
limit-as = 256
max-requests = 5000
vacuum = true
logto = /var/log/uwsgi/app1.log
location / {
include uwsgi_params;
uwsgi_pass unix:/run/uwsgi/app1.sock;
}
| 現象 | 排查方向 |
|---|---|
| 502 Bad Gateway | uWSGI 未啟動、socket 路徑錯誤、權限不足、harakiri 觸發 |
| 504 Gateway Timeout | 請求處理超過 proxy_read_timeout 或 harakiri |
| ImportError | 虛擬環境未正確指定、pythonpath 缺漏 |
| 記憶體持續增長 | 啟用 max-requests、檢查程式碼洩漏、考慮 reload-on-rss |
| 靜態檔 404 | Nginx alias 路徑錯誤、未執行 collectstatic |
uwsgi --stats 127.0.0.1:9191 暴露統計 socket,搭配 uwsgitop、Prometheus uwsgi-exporter、Grafana。workers.active、requests、avg_rt、tx/rx、rss。