在使用 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 生产部署中稳定运行后台任务的核心实践。该方案兼顾简洁性与可维护性，适用于中小型实时应用（如监控推送、心跳保活等场景）。
