Flask-SocketIO是实现WebSocket实时通信的常用扩展，uWSGI则是Python Web应用的主流部署服务器，二者结合多进程部署时，异步模式的配置需要兼顾SocketIO的事件循环机制与uWSGI的进程管理特性，否则会出现连接异常、消息丢失等问题。
核心配置原理
Flask-SocketIO的异步模式依赖于底层的异步事件循环，而uWSGI多进程部署时，每个工作进程会独立运行自己的事件循环，因此需要确保uWSGI的异步配置与SocketIO的异步引擎匹配。如果配置不当，会导致WebSocket握手失败、进程间无法同步连接状态等问题。
异步引擎选择
Flask-SocketIO支持多种异步引擎，在uWSGI多进程场景下，推荐使用eventlet或gevent作为异步引擎，二者都能很好地适配uWSGI的异步工作模式。需要在应用初始化时指定异步引擎：
import eventlet eventlet.monkey_patch() # 打补丁，让标准库的IO操作支持异步 from flask import Flask from flask_socketio import SocketIO app = Flask(__name__) # 指定异步模式为eventlet，也可替换为gevent socketio = SocketIO(app, async_mode='eventlet')
uWSGI核心配置项
uWSGI的配置需要开启异步模式，并指定工作进程数与线程数，同时需要启用WebSocket支持。以下是关键的配置参数说明：
| 配置项 | 说明 | 推荐值 |
|---|---|---|
| processes | 工作进程数 | 根据服务器CPU核心数设置，如4核设为4 |
| threads | 每个进程的线程数 | 若使用eventlet/gevent异步模式，可设为1 |
| async | 异步工作模式开关 | 设为进程数的2-4倍，如16 |
| ugreen | 启用uWSGI的绿色线程支持 | 若使用gevent引擎设为true |
| websocket | 启用WebSocket支持 | 设为true |
完整部署配置示例
Flask应用代码
应用代码需要按照异步引擎的要求进行初始化，同时定义基础的SocketIO事件处理逻辑：
import eventlet
eventlet.monkey_patch()
from flask import Flask, render_template
from flask_socketio import SocketIO, emit
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key_here'
# 初始化SocketIO，指定异步模式为eventlet
socketio = SocketIO(app, async_mode='eventlet', cors_allowed_origins='*')
@app.route('/')
def index():
return render_template('index.html')
# 定义连接事件
@socketio.on('connect')
def handle_connect():
print('客户端连接成功')
emit('server_message', {'data': '欢迎连接WebSocket服务'})
# 定义自定义消息事件
@socketio.on('client_message')
def handle_client_message(msg):
print(f'收到客户端消息: {msg}')
emit('server_message', {'data': f'服务器已收到消息: {msg["content"]}'}, broadcast=True)
if __name__ == '__main__':
# 开发环境运行，生产环境使用uWSGI启动
socketio.run(app, host='0.0.0.0', port=5000)
uWSGI配置文件
创建uwsgi.ini配置文件，内容如下：
[uwsgi] # 应用入口，格式为模块名:SocketIO实例名 module = app:socketio # 网络配置 http = 0.0.0.0:5000 http-websockets = true # 进程与异步配置 processes = 4 threads = 1 async = 16 enable-threads = true # 日志配置 logto = /var/log/uwsgi/flask-socketio.log
启动命令
通过以下命令启动uWSGI服务：
uwsgi --ini uwsgi.ini
常见问题排查
- 连接频繁断开：检查是否忘记打eventlet/gevent的补丁，或者uWSGI未开启WebSocket支持
- 消息无法广播：多进程场景下，默认进程间不共享连接状态，需要配置消息队列（如Redis）作为SocketIO的广播通道，在初始化SocketIO时添加
message_queue='redis://127.0.0.1:6379/0'参数 - 静态资源加载异常：确认uWSGI的http配置是否正确，若使用Nginx反向代理，需要额外配置WebSocket的升级头信息
注意：如果使用gevent作为异步引擎，需要将eventlet.monkey_patch()替换为import gevent; gevent.monkey.patch_all()，同时uWSGI配置中添加ugreen = true参数。
Flask-SocketIOuWSGI多进程部署异步模式配置修改时间：2026-07-05 01:36:23