FastAPI/Gunicorn请求队列机制及超时排队请求丢弃方案咨询

你的场景核心矛盾是默认配置下Gunicorn的TCP监听队列和UvicornWorker内部请求队列没有超时丢弃逻辑，导致已经超过客户端等待时效的请求仍然会被worker执行，浪费资源。以下是两种可直接落地的方案，适配tiangolo官方的uvicorn-gunicorn-fastapi-docker镜像：

方案1：应用层全局中间件实现（推荐，无镜像修改成本） #

直接在FastAPI代码中加入全局中间件，请求被worker取出准备执行业务逻辑前，先校验排队时长，超过阈值直接返回超时，不需要执行后续业务代码，实现成本最低。
示例代码如下：

import time
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()
# 和客户端约定的最大等待时长对齐，单位秒
CLIENT_MAX_WAIT = 5

@app.middleware("http")
async def drop_timeout_request(request: Request, call_next):
    # 从ASGI Scope中获取请求刚到达服务器的时间戳
    request_arrive_time = request.scope.get("time", time.time())
    # 计算请求在队列中等待的总时长
    wait_duration = time.time() - request_arrive_time
    
    # 等待时长超过阈值，直接返回超时，不执行业务逻辑
    if wait_duration >= CLIENT_MAX_WAIT:
        return JSONResponse(
            status_code=408,
            content={"detail": "Request wait timeout, discarded by server"}
        )
    
    # 未超时，继续处理请求
    return await call_next(request)

该方案优势：不需要调整Gunicorn/Uvicorn底层配置，兼容所有部署模式，不会直接拒绝请求，只是提前终止无效请求的处理，也便于后续统计超时丢弃的请求量。

方案2：调整Gunicorn底层配置，从队列层面限制排队 #

通过修改Gunicorn启动参数，从TCP队列层面控制排队长度，避免无效请求进入队列等待：

• 启动容器时传入GUNICORN_CMD_ARGS环境变量，配置核心参数：

  docker run -e GUNICORN_CMD_ARGS="--backlog=4 --timeout=5" <你的镜像名>
  

  参数说明：
  • --backlog=4：TCP全连接队列的最大长度，设置为和worker数量一致，当4个worker都处于忙碌状态时，新的请求会直接被TCP层拒绝，不会进入队列等待，从根源避免无效排队
  • --timeout=5：worker处理请求的最大时长，超过5秒worker会被强制重启，避免异常请求阻塞worker

如果要配合长连接配置，可以追加--keep-alive=5参数，空闲超过5秒的连接直接断开，和客户端超时逻辑对齐。

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