Flask应用部署Gunicorn时因后台线程未初始化报NameError

我是Gunicorn新手，尝试将Flask应用部署到Gunicorn时遇到问题，问题可通过以下代码复现：

import threading
from flask import Flask

def perpetual_background_process():
    while True:
        pass

def start_background_thread():
    global extra_thread
    extra_thread = threading.Thread(target=perpetual_background_process)
    extra_thread.start()

app = Flask(__name__)

@app.route('/')
def hello_world():
    return str(extra_thread.is_alive())

if __name__ == '__main__':
    start_background_thread()
    app.run()

当使用Flask内置服务器运行时，浏览器能正确显示True，但使用Gunicorn启动后，访问/路径会出现如下错误：

➜ app_folder gunicorn -b 0.0.0.0:5000 app:app
[2024-01-24 22:05:11 +0800] [65632] [INFO] Starting gunicorn 21.2.0
[2024-01-24 22:05:11 +0800] [65632] [INFO] Listening at: http://0.0.0.0:5000 (65632)
[2024-01-24 22:05:11 +0800] [65632] [INFO] Using worker: sync
[2024-01-24 22:05:11 +0800] [65634] [INFO] Booting worker with pid: 65634
[2024-01-24 22:05:15,612] ERROR in app: Exception on / [GET]
Traceback (most recent call last):
  File "/opt/anaconda3/lib/python3.8/site-packages/flask/app.py", line 2528, in wsgi_app
    response = self.full_dispatch_request()
  File "/opt/anaconda3/lib/python3.8/site-packages/flask/app.py", line 1825, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/opt/anaconda3/lib/python3.8/site-packages/flask/app.py", line 1823, in full_dispatch_request
    rv = self.dispatch_request()
  File "/opt/anaconda3/lib/python3.8/site-packages/flask/app.py", line 1799, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**view_args)
  File "/Users/my_name/Downloads/testing/app.py", line 17, in hello_world
    return str(extra_thread.is_alive())
NameError: name 'extra_thread' is not defined

看起来应用在Gunicorn中无法在app启动前初始化extra_thread，请问如何让应用正常运行？

解决方案 #

问题核心原因 #

Gunicorn启动Flask应用时，是直接导入app:app对象，不会执行脚本中if __name__ == '__main__':代码块的内容——这部分只有直接用python app.py运行时才会触发。因此你的后台线程初始化代码根本没执行，导致请求时找不到extra_thread变量。

修复方法 #

1. 单worker场景直接初始化线程

如果使用Gunicorn默认的单sync worker，可直接在创建app对象后启动线程，无需放在if __name__块内：

import threading
from flask import Flask

def perpetual_background_process():
    while True:
        pass

def start_background_thread():
    global extra_thread
    extra_thread = threading.Thread(target=perpetual_background_process)
    extra_thread.daemon = True  # 设置为守护线程，主进程退出时自动终止
    extra_thread.start()

app = Flask(__name__)
# Gunicorn导入时会执行此代码，初始化线程
start_background_thread()

@app.route('/')
def hello_world():
    return str(extra_thread.is_alive())

if __name__ == '__main__':
    app.run()

注意：若启用多worker模式（如gunicorn -w 4 app:app），每个worker进程都会启动独立的后台线程，可能造成资源浪费，这种场景不适用此方法。

2. 使用应用上下文信号初始化（全版本兼容，推荐）

通过Flask的appcontext_pushed信号，确保线程在应用上下文加载时初始化：

import threading
from flask import Flask, signals

extra_thread = None

def perpetual_background_process():
    while True:
        pass

def init_background_thread(sender, **kwargs):
    global extra_thread
    # 避免重复初始化线程
    if extra_thread is None or not extra_thread.is_alive():
        extra_thread = threading.Thread(target=perpetual_background_process)
        extra_thread.daemon = True
        extra_thread.start()

app = Flask(__name__)
# 绑定信号，应用上下文推送时触发初始化
signals.appcontext_pushed.connect(init_background_thread, app)

@app.route('/')
def hello_world():
    return str(extra_thread.is_alive())

if __name__ == '__main__':
    init_background_thread(app)
    app.run()

3. Flask 2.0以下版本可用before_first_request

对于旧版本Flask，可使用before_first_request装饰器，在第一个请求到来前初始化线程：

import threading
from flask import Flask

extra_thread = None

def perpetual_background_process():
    while True:
        pass

def start_background_thread():
    global extra_thread
    extra_thread = threading.Thread(target=perpetual_background_process)
    extra_thread.daemon = True
    extra_thread.start()

app = Flask(__name__)

@app.before_first_request
def init_thread():
    start_background_thread()

@app.route('/')
def hello_world():
    return str(extra_thread.is_alive())

if __name__ == '__main__':
    start_background_thread()
    app.run()

额外注意事项 #

• 务必将后台线程设置为守护线程（daemon=True），防止Gunicorn退出后残留僵尸线程。
• 多worker场景下，建议使用独立的任务队列（如Celery）管理后台任务，避免每个worker重复启动线程。

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