如何在Gunicorn进程内使用ThreadPoolExecutor？问题排查与解决

当Gunicorn worker进程达到max_requests配置的阈值时，会启动新的worker进程，同时向旧worker发送SIGTERM信号触发优雅关闭流程。旧worker在优雅关闭阶段（由timeout/graceful_timeout控制时长），会停止接收新HTTP请求，但后台运行的调度任务（你每0.5秒执行一次的任务）仍会继续运行并尝试调用perform提交新任务到ThreadPoolExecutor。

此时，Python解释器在进程退出前会逐步清理资源，或者Gunicorn的worker关闭逻辑会间接触发线程池进入shutdown状态，导致后续调用executor.submit()时抛出cannot schedule new futures after shutdown错误。你误以为"线程未随进程终止"，实际是旧worker在优雅关闭的窗口期内仍在运行，但线程池已被标记为不可接受新任务。

1. 给线程池添加优雅关闭逻辑 #

修改BaseQueueConsumer类，添加关闭标记和线程池清理方法，确保在worker关闭时停止提交新任务并等待现有任务完成：

from concurrent.futures import ThreadPoolExecutor, wait
from threading import Event

class BaseQueueConsumer:
    def __init__(self, threads: int):
        self._threads = threads
        self._executor = ThreadPoolExecutor(max_workers=1)
        self._shutdown_flag = Event()  # 标记是否进入关闭流程

    def perform(self, param1, param2, param3) -> None:
        if self._shutdown_flag.is_set():
            return  # 已触发关闭，拒绝提交新任务
        futures = []
        for _ in range(self._threads):
            futures.append(
                self._executor.submit(
                    BaseQueueConsumer.consume, param1, param2, param3
                )
            )
        wait(futures)  # 等待所有提交的任务执行完成，替代仅检查done()

    @staticmethod
    def consume(param1, param2, param3) -> None:
        # 原任务逻辑
        pass

    def shutdown(self):
        self._shutdown_flag.set()  # 通知调度器停止提交新任务
        self._executor.shutdown(wait=True)  # 等待现有任务完成后关闭线程池

2. 绑定FastAPI的关闭事件 #

在FastAPI应用中注册shutdown事件，确保应用关闭时触发线程池的清理：

from fastapi import FastAPI

app = FastAPI()
# 初始化你的队列消费者实例
queue_consumer = BaseQueueConsumer(threads=1)

@app.on_event("shutdown")
def handle_shutdown():
    queue_consumer.shutdown()

3. 优化Gunicorn优雅关闭配置 #

确保Gunicorn给旧worker足够的时间完成剩余任务，可在配置中明确设置优雅超时（如果未设置，默认继承timeout值）：

bind = 0.0.0.0:8080
worker_class = "uvicorn.workers.UvicornWorker"
workers = 3
loglevel = ServerConfig.LOG_LEVEL.lower()
max_requests = 1500
max_requests_jitter = 300
timeout = 120
graceful_timeout = 120  # 明确设置优雅关闭超时，确保旧worker有足够时间清理

4. 解耦调度任务与Worker进程 #

如果你的调度任务是全局定时任务，不应该绑定到单个Gunicorn Worker（多个Worker会重复执行任务），建议将调度逻辑独立为单独进程（比如使用APScheduler独立进程、Celery Beat），彻底避免Worker生命周期带来的冲突。

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