Python uWSGI安装配置指南
编程小白也能理解的详细教程
什么是uWSGI？
uWSGI 是一个 Web 应用服务器，它就像是你 Python Web 应用（如 Flask 或 Django）的”翻译官”和”快递员”：
- 翻译官角色：将你的 Python 代码翻译成网络可以理解的语言（WSGI 协议）
- 快递员角色：高效地将用户请求送到你的应用，并将结果返回给用户
- 多面手：支持多种协议（HTTP、FastCGI、SCGI）和应用框架
为什么需要uWSGI？ 当你在开发环境中直接运行 Flask 或 Django 时，它们自带的服务器不适合处理真实用户访问。uWSGI 可以提供高性能、稳定性，还能处理多用户同时访问。
🚀
高性能
处理请求速度快
🔧
可配置
丰富的配置选项
🧩
模块化
支持多种插件
🔄
持久运行
7×24小时稳定运行
安装uWSGI
准备工作
- 确保已安装 Python（建议 Python 3.6+）
- 准备好你的 Python 虚拟环境（强烈推荐使用）
# 创建并激活虚拟环境（Windows）
python -m venv myenv
myenv\Scripts\activate
# 创建并激活虚拟环境（Linux/macOS）
python3 -m venv myenv
source myenv/bin/activate
安装方法
最简单的方法（推荐）：
pip install uwsgi
如果遇到编译问题：
- Windows：需要安装 C/C++ 编译环境（如 Visual Studio Build Tools）
- Linux：安装开发工具包（如Ubuntu:
sudo apt-get install build-essential python-dev）
注意： uWSGI 的名字在 pip 上是 uwsgi（全小写），不要写成大写字母！
uWSGI配置基础
命令行运行方式
快速测试你的应用是否能在 uWSGI 上运行：
# 对于Flask应用
uwsgi –http :8000 –module myapp:app
# 对于Django应用
uwsgi –http :8000 –module myproject.wsgi
什么是WSGI入口点？
每个Python Web应用都需要一个WSGI入口点，uWSGI通过这个入口点来调用你的应用：
- Flask:
app = Flask(__name__)中的app - Django:
myproject/wsgi.py中的application
配置文件方法（推荐）
将配置写入文件使管理更简单：
# uwsgi.ini 文件示例
[uwsgi]
# 使用HTTP协议，端口8000
http = :8000
# Flask应用的入口点
module = myapp:app
# 虚拟环境路径
virtualenv = /path/to/your/venv
# 主进程
master = true
# 工作进程数（根据CPU核心数调整）
processes = 4
# 每个工作进程的线程数
threads = 2
# 应用文件改动时自动重启
touch-reload = reload.txt
高级配置选项
常用配置项说明
socket: 指定通信socket（Nginx连接时使用）chdir: 切换到指定目录（应用的根目录）home: Python虚拟环境路径processes: 工作进程数量（CPU核心数×2是个好起点）threads: 每个工作进程的线程数harakiri: 请求超时时间（秒）max-requests: 进程处理请求数上限（防止内存泄漏）
与Nginx配合使用
在实际部署中，uWSGI通常搭配Nginx使用：
# uWSGI配置（使用socket通信）
[uwsgi]
socket = 127.0.0.1:3031
chdir = /path/to/your/app
module = myapp:app
virtualenv = /path/to/venv
processes = 4
threads = 2
Nginx配置示例：
server {
listen 80;
server_name yourdomain.com;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:3031; # 与uWSGI的socket端口一致
}
# 处理静态文件
location /static {
alias /path/to/your/app/static;
}
}
部署与生产环境
以服务方式运行（Linux）
创建 systemd 服务文件（/etc/systemd/system/myapp.service）：
[Unit]
Description=My Python Web App
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/your/app
Environment=”PATH=/path/to/venv/bin”
ExecStart=/path/to/venv/bin/uwsgi –ini uwsgi.ini
[Install]
WantedBy=multi-user.target
# 然后执行
sudo systemctl daemon-reload
sudo systemctl start myapp
sudo systemctl enable myapp # 开机自启
日志配置
配置日志文件以方便排错：
# 在uwsgi.ini中添加
[uwsgi]
# …
logto = /var/log/uwsgi/myapp.log
disable-logging = true # 禁用请求日志，保留错误日志
log-4xx = true # 记录客户端错误
log-5xx = true # 记录服务器错误
性能调优提示： 工作进程数(processes)设置为CPU核心数的2-4倍，线程数(threads)根据I/O等待时间调整（I/O密集型应用可增加线程数）
常见问题及解决方案
安装问题
问题： 安装时出现编译错误
解决：
- 确保已安装Python开发包（python3-dev 或 python3-devel）
- 确保安装了C编译器（gcc/clang）
- Windows用户需安装Visual Studio Build Tools
运行问题
问题： uWSGI启动时报 “no module named …”
解决：
- 检查虚拟环境路径是否正确
- 确认在虚拟环境中安装了所有依赖包
- 尝试在配置中添加 PYTHONPATH
性能问题
问题： 在高并发时响应慢或有超时
解决：
- 增加工作进程数（processes）和线程数（threads）
- 调整 harakiri 超时设置（例如设置为60秒）
- 考虑使用 –lazy-apps 选项（某些框架需要）
- 检查数据库连接池设置