Python Web应用收到SIGTERM后数据库连接不释放，因未显式调用close()/dispose()且连接池引用阻止GC；需用signal.signal在主线程注册处理器触发优雅停机，配合Lifespan或on_shutdown执行engine.dispose()与Session清理。
Python Web应用收到SIGTERM后为什么数据库连接不释放
进程被 SIGTERM 中断时，Python 默认不会自动清理数据库连接（比如 psycopg2、SQLAlchemy 连接池里的连接），导致连接在数据库端长时间处于 idle 状态，甚至触发连接数上限报错。根本原因是：主线程退出时，未显式调用 close() 或 dispose()，而连接对象本身不会被立即 GC（尤其连接池中的连接有引用保持）。
如何用signal.signal捕获SIGTERM并触发清理逻辑
直接注册信号处理器是最快路径，但要注意：信号只能在主线程中安全处理；若 Web 框架（如 Flask、FastAPI）启用了多线程或多进程（如 gunicorn 的 worker 模式），必须确保只在主进程注册，且清理逻辑不阻塞信号响应。
- 使用
signal.signal(signal.SIGTERM, handler)注册，handler 接收两个参数：sig和frame - handler 内部应避免耗时操作（如等待数据库事务完成），优先设标志位 + 触发 graceful shutdown 流程
- 务必调用
signal.pthread_sigmask(signal.SIG_BLOCK, [signal.SIGTERM])（可选）防止子线程误收信号 - 示例片段：
import signal import sys <p>def shutdown_handler(sig, frame): print("Received SIGTERM, shutting down...")</p><h1>这里调用你的 cleanup_db()、stop_server() 等</h1><pre class="brush:php;toolbar:false;">cleanup_db() sys.exit(0)signal.signal(signal.SIGTERM, shutdown_handler)
SQLAlchemy连接池关闭的正确顺序和关键参数
仅调用 engine.dispose() 不够——它只清空连接池缓存，不强制关闭已 checkout 的连接；若还有活跃请求正在用连接，会引发异常或资源泄漏。必须配合应用层的“拒绝新请求 + 等待现有请求结束”流程。
立即学习“Python免费学习笔记（深入）”；
- 启动前配置连接池：设置
pool_pre_ping=True（探测连接有效性）、pool_recycle=3600（避免长连接超时失效） - 停机时按顺序执行：
app.should_exit = True（通知服务器停止接受新请求）→ 等待活跃请求自然结束（需框架支持）→ 调用engine.dispose()→ 显式关闭所有Session实例（如有长期存活的 session 对象） - 若用
scoped_session，需调用session.remove()清理线程局部存储 - 错误做法：
del engine或依赖__del__—— 不可靠，GC 时机不可控
FastAPI/Starlette中集成优雅停机的实际钩子位置
FastAPI 本身不暴露原生信号接口，但 Starlette 的 Lifespan 协议和 Uvicorn 的 on_shutdown 事件才是更可控的入口。别在 signal.signal 里直接关服务，而是用它来触发 Lifespan 的 shutdown 流程。
- 在
lifespan异步上下文管理器中实现 shutdown 逻辑：from contextlib import asynccontextmanager from fastapi import FastAPI <p>@asynccontextmanager async def lifespan(app: FastAPI):</p><h1>startup</h1><pre class="brush:php;toolbar:false;">yield # shutdown —— 这里放 cleanup_db(), engine.dispose() 等 await cleanup_db()
app = FastAPI(lifespan=lifespan)
- Uvicorn 启动时加
--forward-signal SIGTERM（v0.29+），确保信号透传到 lifespan - 注意：若用 gunicorn + uvicorn worker，gunicorn 主进程会先收 SIGTERM，此时要通过 IPC 或共享状态通知各 worker 执行 shutdown，不能只靠单个进程的 signal handler
真正容易被忽略的是：数据库连接是否真的“断开”，不取决于 Python 层有没有 close()，而取决于 TCP 连接是否发送 FIN 包。很多驱动（如 psycopg2）在 close() 后仍可能复用底层 socket，除非显式设置 close_all=True 或调用 connection.close() 并确认无引用残留。
