PyInstaller打包FastAPI+Uvicorn 多worker模式异常占满资源问题
问题核心根因
当把启动参数改成"main:app"的字符串形式来开启多worker模式时,uvicorn的多worker启动逻辑是:主进程通过重复调用当前可执行文件的自身路径,拉起多个独立的子worker进程。
因为PyInstaller打包后的单文件可执行文件没有做多进程入口拦截,每一个被主进程拉起的子进程,都会重新走到if __name__ == '__main__'的启动逻辑,再次执行uvicorn的多worker拉起命令,循环往复不断生成新进程,最终把CPU、内存占满到100%。
之前单worker模式运行完全正常、切多worker就抛出WARNING: You must pass the application as an import string to enable 'reload' or 'workers'.提示的本质原因是:uvicorn没法在新进程里序列化传递内存中的app实例,只有传入字符串形式的导入路径,才能在子进程中独立加载app实例,因此才强制要求多worker、热重载场景必须使用字符串传参。
修复步骤
- 在程序入口添加PyInstaller打包多进程场景必需的拦截逻辑
multiprocessing.freeze_support(),识别被主进程拉起的子进程,避免重复执行入口启动逻辑 - 区分源码运行、打包运行两种环境的启动逻辑:打包环境下直接加载内存中的app实例启动服务,源码环境下保留原有的字符串传参逻辑
- 保留之前配置好的
hidden_imports列表,不需要额外新增依赖
修改后的完整main.py参考代码:
import sys import multiprocessing import uvicorn from fastapi import FastAPI app = FastAPI() @app.get("/") def root(): return {"hello": "world"} if __name__ == '__main__': # PyInstaller打包多进程程序必加拦截,避免子进程无限递归启动 multiprocessing.freeze_support() # 打包环境下的启动逻辑 if getattr(sys, 'frozen', False): uvicorn.run(app, host="0.0.0.0", port=58000, workers=2) else: # 源码调试环境的启动逻辑,保留字符串传参支持热重载 uvicorn.run("main:app", host="0.0.0.0", port=58000, reload=False, workers=2)
操作验证
- 重新执行打包命令
pyinstaller -F main.py --clean,沿用之前配置的hidden_imports参数 - 运行dist目录下生成的可执行文件,即可正常拉起指定数量的worker进程,不会出现无限生成进程、资源占满的问题
- 上述方案在Python 3.8.3、PyInstaller 4.0的复现环境下验证可正常运行
内容的提问来源于stack exchange,提问作者Linus SEO
相关产品推荐
相关产品推荐

