tracemalloc可快速定位内存增长源头,通过启动时调用tracemalloc.start()、暴露/debug/memory端点获取调用栈统计,结合objgraph分析对象类型与引用链,精准识别未释放对象所在行及持有者。

用 tracemalloc 快速定位内存增长源头
FastAPI 本身不直接导致内存泄漏,但异步逻辑、全局缓存、未关闭的资源(如数据库连接、文件句柄)或第三方库误用容易让对象长期驻留内存。最轻量且有效的初筛手段是启用 tracemalloc,它能在运行时记录内存分配的调用栈。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 在应用启动前(如
main.py最顶部)插入:import tracemalloc<br>tracemalloc.start(25) # 保存最多25层调用栈
- 暴露一个调试端点(仅限开发/测试环境),例如:
@app.get("/debug/memory")<br>async def get_memory():<br> current, peak = tracemalloc.get_traced_memory()<br> snapshot = tracemalloc.take_snapshot().filter_traces(<br> [tracemalloc.Filter(True, "*main.py"), tracemalloc.Filter(True, "*routes/*.py")]<br> )<br> top_stats = snapshot.statistics("lineno")[:10]<br> return {"current_kb": current / 1024, "peak_kb": peak / 1024, "top": [str(s) for s in top_stats]} - 持续压测后访问
/debug/memory,重点关注line number和增长快的size—— 很可能就是反复创建却未释放的对象所在行
检查 BackgroundTasks 和生命周期管理不当的依赖
FastAPI 的 BackgroundTasks 是常见泄漏温床:任务函数中若持有大对象引用、使用闭包捕获了请求上下文(如 request.state)、或内部启用了未清理的 asyncio 任务(如 asyncio.create_task() 无 await 或 cancel),都会阻止垃圾回收。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 避免在
BackgroundTasks中直接引用request或state;改用显式传参(只传必要字段) - 检查所有自定义依赖(
Depends())是否实现了__exit__或async def __aexit__,尤其涉及数据库连接池、HTTP 客户端(如httpx.AsyncClient)、或缓存实例 - 确认
lifespan事件中正确关闭了全局资源,例如:async def lifespan(app: FastAPI):<br> # 启动时<br> app.state.client = httpx.AsyncClient()<br> yield<br> # 关闭时必须显式调用<br> await app.state.client.aclose()
警惕 asyncpg、aiomysql 等异步驱动的连接泄漏
这类驱动默认使用连接池,但若在请求中手动调用 pool.acquire() 却忘记 pool.release(),或在异常路径下跳过了释放逻辑,连接对象会持续累积,最终耗尽内存和连接数。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 永远用
async with pool.acquire() as conn:,而不是裸调用acquire() - 检查所有
try/except块:确保finally或async with覆盖所有退出路径 - 开启驱动日志验证行为,例如 asyncpg:
import logging<br>logging.getLogger("asyncpg").setLevel(logging.WARNING)—— 若出现connection pool is full或大量Connection closed日志,基本可判定泄漏已发生
用 objgraph 查看存活对象类型分布
当 tracemalloc 显示某模块内存持续上涨,但找不到具体变量时,objgraph 可以列出当前存活对象的类型统计,并对比两次快照找出新增最多的类,这对识别“谁在偷偷 hold 住对象”非常关键。
实操建议:
立即学习“Python免费学习笔记(深入)”;
- 安装并初始化:
pip install objgraph<br>import objgraph
- 在怀疑泄漏前后各执行一次:
objgraph.show_most_common_types(limit=20)
,对比哪些类实例数激增(如dict、list、Request、自定义 Model 类) - 对激增类做引用链追踪:
objgraph.show_growth(limit=10) # 显示新增数量最多的类型<br># 找到某个可疑实例 ID 后:<br>objgraph.show_backrefs([obj], max_depth=3)
—— 这能暴露是谁在引用它,常发现是全局字典、未清空的缓存或 event loop 的 pending task
内存泄漏排查没有银弹,tracemalloc 给位置,objgraph 给关系,而真正修复往往卡在「那个本该被 await 却漏掉的 aclose()」或者「以为自动回收其实被闭包锁死的 request 对象」—— 多打几次快照,比猜更可靠。


















