在使用 gunicorn 部署 flask（尤其是 flask-socketio）应用时，`if __name__ == ‘__main__’` 中的后台线程不会自动执行——需将线程初始化逻辑移至模块顶层，并通过独立变量暴露 wsgi 应用实例。
Gunicorn 作为 WSGI http 服务器，其工作方式是导入模块并获取指定的可调用对象（如 app），而非执行整个 python 文件。这意味着 if __name__ == ‘__main__’: 块内的代码（包括后台线程启动逻辑）在 Gunicorn 启动时完全被跳过，导致你观察到日志中缺失 “background task started…” 的输出。
要解决此问题，关键在于：将后台线程的创建与启动逻辑从 __main__ 块中提取出来，确保它在模块被导入时即执行；同时明确区分开发模式（socketio.run()）与生产部署模式（Gunicorn 加载的 WSGI 实例）。
✅ 正确实现方式（适配 Gunicorn + Flask-SocketIO）
以下是重构后的完整代码，已移除冗余配置、修复线程生命周期隐患，并增强健壮性：
import threading import logging from flask import Flask from flask_socketio import SocketIO app = Flask(__name__) socketio = SocketIO(app, cors_allowed_origins="*") # 根据需要调整 CORS # 配置日志（避免重复 handlers） logging.basicConfig( level=logging.DEBUG, format='%(asctime)s [%(levelname)s] %(message)s', datefmt='%Y-%m-%d %H:%M:%S' ) logger = logging.getLogger(__name__) @app.route('/') def index(): return "Flask-SocketIO background task is running." # ✅ 后台任务函数：支持优雅退出（推荐加 stop_event） def background_task(stop_event): logger.debug("Background task started in thread: %s", threading.current_thread().ident) while not stop_event.is_set(): logger.debug("Background task running...") try: socketio.emit('background_task_response', {'data': 'Background Task Result'}) except Exception as e: logger.error("Failed to emit via SocketIO: %s", e) # 使用 socketio.sleep() 仅在 SocketIO 环境中有效（如 eventlet/gevent） # 此处改用标准 time.sleep 避免依赖 worker 类型 import time time.sleep(5) logger.info("Background task stopped.") # ✅ 全局线程管理（避免重复启动） _background_thread = None _stop_event = threading.Event() def start_background_thread(): global _background_thread if _background_thread is None or not _background_thread.is_alive(): _stop_event.clear() _background_thread = threading.Thread( target=background_task, args=(_stop_event,), name="Flask-Background-Task", daemon=True # 关键：设为守护线程，避免阻塞 Gunicorn 主进程退出 ) _background_thread.start() logger.info("Background thread started.") # ✅ 在模块加载时立即启动后台线程（Gunicorn 会导入此模块） start_background_thread() # ✅ 显式声明 WSGI 应用入口点（Gunicorn 调用目标） gunicorn_app = app # ✅ 开发模式：仅当直接运行脚本时启用（不用于 Gunicorn） if __name__ == '__main__': # 注意：此处不再传入 gunicorn 参数；这些应由命令行或配置文件控制 socketio.run(app, host='0.0.0.0', port=8000, debug=True, use_reloader=True)? 部署命令与注意事项
-
启动 Gunicorn（推荐使用 gevent 或 eventlet worker 支持 websocket）：
# 安装依赖（若未安装） pip install gevent flask-socketio # 启动（注意：使用 gunicorn_app 而非 app） gunicorn -w 2 -k gevent --worker-connections 1000 -b 0.0.0.0:8000 test:gunicorn_app -
⚠️ 重要注意事项：
- 不要在 __main__ 中配置 Gunicorn 参数（如 bind, workers），这些应通过命令行或 gunicorn.conf.py 管理；
- 线程必须设为 daemon=True：否则 Gunicorn 主进程无法正常终止（Ctrl+C 不生效）；
- 避免在多 worker 场景下重复启动线程：上述代码通过 _background_thread 全局状态防止重复创建；
- socketio.sleep() 仅在 eventlet/gevent 环境下有效；若使用 sync worker，务必替换为 time.sleep()，否则抛出异常；
- 如需更高级调度（如定时、任务持久化），建议迁移到 APScheduler 或 Celery，而非裸线程。
✅ 总结
Gunicorn 的模块导入机制决定了后台逻辑必须“提前就绪”。将线程初始化提升至模块作用域、显式导出 WSGI 实例、合理管理线程生命周期，是 Flask 生产部署中稳定运行后台任务的核心实践。该方案兼顾简洁性与可维护性，适用于中小型实时应用（如监控推送、心跳保活等场景）。