Flask-socketio+gunicorn+eventlet 部署已经不需要在 ws_app 入口使用猴子补丁了

前言

在 Flask-SocketIO 的早期版本中，当使用 gunicorn + eventlet 部署 WebSocket 应用时，通常需要在应用入口处手动添加猴子补丁（monkey patch）来确保第三方库与 eventlet 的兼容性。然而，随着 Flask-SocketIO 生态系统的不断完善和最佳实践的演进，这种做法已经不再是必需的，甚至可能带来一些问题。

核心依赖包

Flask==2.2.5
gunicorn==23.0.0
eventlet==0.38.0
greenlet==3.1.1

传统做法的问题

1. 猴子补丁的副作用

在传统的部署方式中，开发者通常会在应用入口添加如下代码：

import eventlet
eventlet.monkey_patch()

from flask import Flask
from flask_socketio import SocketIO

app = Flask(__name__)
socketio = SocketIO(app, async_mode="eventlet")

然而，这种全局猴子补丁可能导致以下问题：

显式调用：如果在ws_app.py开头显式调用会有报错，可能导致额外问题：

❯ gunicorn -b "0.0.0.0:5001" --workers 1 --worker-class "eventlet" ws_app:app
9 RLock(s) were not greened, to fix this error make sure you run eventlet.monkey_patch() before importing any other modules.

2. 现代部署方式的优势

现代的 Flask-SocketIO 部署已经不再强制要求在应用层面进行猴子补丁，主要原因包括：

Gunicorn 的 eventlet worker 已经内置处理：当使用gunicorn --worker-class eventlet时，gunicorn 会自动处理 eventlet 的初始化
Flask-SocketIO 的智能检测：新版本的 Flask-SocketIO 能够自动检测运行环境并选择合适的异步模式
更好的错误处理：避免了猴子补丁可能引入的兼容性问题

推荐的部署配置

1. WebSocket 应用入口（ws_app.py）

# ws_app.py
from flask import Flask, jsonify
from flask_cors import CORS
from flask_socketio import SocketIO
from configs import config

app = Flask(__name__)
app.secret_key = "your-secret-key"
CORS(app, supports_credentials=True)
app.config.from_object(config)

# 不需要手动指定async_mode，让Flask-SocketIO自动检测
socketio = SocketIO(app, cors_allowed_origins="*")

@app.route("/health_check")
def health_check():
    return jsonify({
        "code": 10000,
        "message": "success",
        "data": {
            "status": "healthy",
            "service": "websocket"
        }
    })

2. Gunicorn 配置（gunicorn_ws_config.py）

# gunicorn_ws_config.py
proc_name = "socketsystem-websocket"
bind = "0.0.0.0:5001"

# 使用eventlet worker
worker_class = "eventlet"

# WebSocket应用建议使用单进程
workers = 1

# eventlet不建议使用threads配置
# 参考：https://github.com/miguelgrinberg/Flask-SocketIO/issues/924

3. 启动命令

# 使用gunicorn启动WebSocket服务
gunicorn --worker-class eventlet -w 1 -c configs/gunicorn_ws_config.py ws_app:app

特殊情况的处理

如果 eventlet 带来了兼容性问题，可以考虑使用线程模式：

# 使用线程模式的WebSocket应用
socketio = SocketIO(app, async_mode="threading", cors_allowed_origins="*")

对应的 gunicorn 配置：

# 使用线程worker
gunicorn -w 1 --threads 100 ws_app:app

性能对比

模式	并发处理能力	内存占用	兼容性	适用场景
eventlet	高	低	中等	高并发 WebSocket 应用
threading	中等	中等	高	CPU 密集型应用
gevent	高	低	中等	需要 gevent 生态的应用

最佳实践建议

优先使用 gunicorn 的 eventlet worker，而不是在应用层面进行猴子补丁
让 Flask-SocketIO 自动选择异步模式，除非有特殊需求
在遇到兼容性问题时，优先考虑调整第三方库的使用方式，而不是强制猴子补丁
对于 CPU 密集型应用，考虑使用线程模式而不是 eventlet

迁移指南

如果你的现有项目仍在使用猴子补丁，可以按以下步骤进行迁移：

移除应用入口的猴子补丁代码
更新 gunicorn 配置，确保使用正确的 worker 类型
测试 WebSocket 功能，确保一切正常工作
如果遇到问题，检查是否有第三方库需要特殊处理
考虑使用线程模式作为备选方案