Uvicorn已内置SIGTERM处理逻辑,无需手动注册signal.signal;它会进入drain阶段停止新连接并等待活跃请求完成,但业务清理(如数据库释放)须通过ASGI lifespan协议在yield后执行。

Uvicorn本身已内置SIGTERM响应逻辑,你不需要手动注册signal.signal(signal.SIGTERM, ...)——直接注册反而容易破坏其内部事件循环,引发RuntimeError: Event loop stopped before Future completed。
Uvicorn收到SIGTERM后实际做了什么
它不是立刻退出,而是进入“drain”阶段:停止接受新连接、保持已有连接继续处理请求、等待所有活跃请求完成或超时(默认无硬性等待上限,取决于你配置的--timeout-graceful-shutdown)。这个过程由Uvicorn主事件循环自主控制,无需你干预信号接收。
但业务级清理(如数据库连接池释放、后台任务取消)必须由你显式定义,Uvicorn只负责“等”,不负责“清”。
-
--timeout-graceful-shutdown参数决定Uvicorn最多等多久才强制终止——不设值则无限等待,设太短会导致请求被中断 - 若用
--workers多进程模式,SIGTERM会发给master进程,再由master转发给各worker;此时每个worker仍独立执行自己的shutdown流程 - 在Kubernetes中,容器收到
TERM信号即等同于向Uvicorn进程发SIGTERM,但需确保terminationGracePeriodSeconds≥--timeout-graceful-shutdown
用lifespan替代@app.on_event("shutdown")
@app.on_event("shutdown")在Uvicorn 0.29+中已被标记为deprecated,且无法保证异步资源(如engine.dispose())在事件循环关闭前完成。正确方式是使用ASGI lifespan协议。
FastAPI支持通过lifespan参数接入标准ASGI生命周期管理,yield前为startup,yield后为shutdown,且全程在同一个事件循环中运行:
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
from contextlib import asynccontextmanager
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine
<p>engine = create_async_engine("sqlite+aiosqlite:///app.db")</p><p>@asynccontextmanager
async def lifespan(app: FastAPI):</p><h1>startup</h1><pre class="brush:python;toolbar:false;">yield
# shutdown —— 这里执行清理
await engine.dispose()
app = FastAPI(lifespan=lifespan)
- 必须用
asynccontextmanager,不能用普通contextmanager,否则await会报错 - yield之后的代码在Uvicorn确认所有请求结束、准备退出前执行,时机可控
- 若清理逻辑耗时较长(如批量写入日志、刷新缓存),建议加超时保护,避免阻塞整个退出流程
为什么不能在signal handler里调sys.exit()或loop.stop()
因为Uvicorn的主事件循环不是你启动的,也不是你拥有控制权的——它由Uvicorn自身管理。你在信号处理器里强行sys.exit(),会跳过Uvicorn的drain逻辑,导致正在处理的请求被截断、连接未关闭、连接池泄漏;而调loop.stop()在Uvicorn 0.20+后会触发RuntimeError,因其内部已改用asyncio.run()封装,不再允许外部停循环。
- 信号处理器只能用于设置状态标志(如
should_exit = True),不能执行业务清理 - 如果你用Gunicorn + UvicornWorker,信号由Gunicorn master接收并分发,Uvicorn worker只响应来自master的指令,不直收OS信号
- systemd部署时,务必配
StopSec=30,否则systemd可能在Uvicorn还没完成drain前就发KILL
真正关键的不是“怎么捕获信号”,而是“什么时候释放资源”——Uvicorn把时机交给你,但你要用对钩子。lifespan里的shutdown段是唯一既安全又可靠的出口,其余路径都绕不开资源泄漏风险。










