CPanel部署Flask-SocketIO应用WebSocket连接失败问题求助

核心问题 #

当前Passenger默认以WSGI模式启动Flask应用，但SocketIO需要依赖eventlet异步服务器处理WebSocket连接，现有passenger_wsgi.py仅导出Flask实例，没有启动eventlet服务器，导致日志提示"You need to use the eventlet server"，最终WebSocket连接失败。

解决方案步骤 #

1. 修改passenger_wsgi.py适配SocketIO启动 #

替换原有代码为以下内容，确保用eventlet启动SocketIO服务，同时兼容Passenger的WSGI模式：

import eventlet
eventlet.monkey_patch()

# 从你的主应用文件导入socketio和app实例
from app import socketio, app

# 直接启动eventlet服务器（用于命令行启动）
if __name__ == "__main__":
    # 替换为你的SSL证书路径，CPanel生成的证书通常在/etc/letsencrypt/live/你的域名/下
    ssl_cert = "/etc/letsencrypt/live/www.name.com/fullchain.pem"
    ssl_key = "/etc/letsencrypt/live/www.name.com/privkey.pem"
    socketio.run(app, host='0.0.0.0', port=443, ssl_context=(ssl_cert, ssl_key))
else:
    # Passenger需要的WSGI应用实例
    application = app

2. 调整CPanel Passenger应用启动设置 #

• 进入CPanel的Passenger App Manager，找到你的应用
• 修改"Startup Command"为python passenger_wsgi.py，替代默认的自动检测
• 重启应用，确保Passenger以命令行方式启动eventlet服务器，而非纯WSGI模式

3. 前端连接优化 #

修改前端的SocketIO连接代码，强制使用WebSocket并适配当前域名：

const socket = io.connect(window.location.origin, {
    transports: ['websocket'],
    secure: true
});

去掉硬编码的域名和端口，避免环境不一致导致的连接问题。

4. 验证依赖安装 #

确保服务器已安装正确版本的依赖：

pip install --upgrade eventlet flask-socketio flask-cors

注意：flask-socketio 5.x及以上版本需要eventlet 0.30.x及以上版本，版本不兼容也会导致连接失败。

5. Nginx反向代理配置（若CPanel使用Nginx） #

如果无法直接修改Nginx主配置，可通过CPanel的Apache Configuration > Include Editor添加Nginx片段：

location /socket.io {
    proxy_pass http://127.0.0.1:443;  # 对应socketio.run设置的端口
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

这段配置用于将WebSocket请求转发到eventlet服务器，确保连接能正确建立。

内容的提问来源于stack exchange，提问作者KianFakheriAghdam