生产环境必须用Gunicorn+UvicornWorker组合:Gunicorn负责进程管理、优雅关闭、内存回收和日志统一,UvicornWorker专注ASGI异步处理;裸Uvicorn或多worker模式缺乏健康检查与隔离能力,Gunicorn默认不支持ASGI需显式指定worker类。

别用 Gunicorn 直接跑 FastAPI,也别只靠 uvicorn --workers 上生产 —— 这两种做法都会在高并发或 CPU 密集场景下翻车。
Uvicorn 的 --workers 参数不是“Gunicorn 那种 worker”
很多人看到 uvicorn main:app --workers 4 就以为和 Gunicorn 一样是多进程负载均衡,其实不是:
- Uvicorn 的每个
--workers是独立进程 + 独立事件循环,靠内核SO_REUSEPORT实现连接分发,没有 master 进程协调 - 它不提供进程健康检查、优雅重启、内存泄漏自动回收等能力 —— 某个 worker 崩了,你就得手动杀掉再拉起
- 所有 worker 共享同一个日志输出、同一个信号处理逻辑,容易互相干扰(比如 SIGTERM 被多个进程同时响应)
- 如果你的应用里用了全局变量(比如缓存字典
cache = {}),不同 worker 之间完全不共享,容易导致数据不一致
Gunicorn 默认根本启动不了 FastAPI 应用
直接运行 gunicorn main:app 会报错:
TypeError: 'coroutine' object is not callable
原因很直接:Gunicorn 默认用的是 WSGI 协议,而 FastAPI 输出的是 ASGI callable。它试图同步调用一个 async def 函数,自然失败。
必须显式指定 worker 类型才能让 Gunicorn “转译”请求给 Uvicorn:
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 正确写法:
gunicorn main:app --worker-class uvicorn.workers.UvicornWorker - 这个
UvicornWorker是 Gunicorn 提供的薄封装,本质是每个 Gunicorn worker 进程里启动一个完整 Uvicorn 实例 - 此时 Gunicorn 只干一件事:管进程(fork、监控、重启、平滑 reload),真正的 HTTP 解析、ASGI 调度、异步 I/O 全由 Uvicorn 完成
- 注意:不能混用
--workers和--preload——--preload会让 Uvicorn 在 fork 前就初始化 app,可能引发数据库连接复用或异步 event loop 错误
生产环境必须用 Gunicorn + UvicornWorker 组合
这不是“多此一举”,而是补足 Uvicorn 缺失的关键生产能力:
- 进程级隔离:一个 Uvicorn worker 崩溃,Gunicorn 自动拉起新进程,不影响其他 worker
- 优雅关闭支持:
gunicorn收到 SIGTERM 后会先停止接收新连接,等正在处理的请求完成再退出;裸 Uvicorn 没这机制 - 内存限制可控:Gunicorn 可配
--max-requests和--max-requests-jitter强制 worker 定期重启,防内存泄漏累积 - 日志统一归口:Gunicorn 负责 access log 和 error log 的格式、轮转、权限控制,Uvicorn 只需专注业务日志
- 配置收敛:端口绑定、超时、keepalive 等参数由 Gunicorn 统一管理,避免 Uvicorn 多 worker 下配置分散
开发阶段用 Uvicorn 单进程就够了
开发时你真正需要的是热重载、清晰错误堆栈、快速启动 —— 这些 Gunicorn 全都不支持,反而拖慢迭代节奏:
-
uvicorn main:app --reload --reload-dir ./src是开发事实标准,--reload基于文件系统 inotify,改完保存立刻生效 - 出错时堆栈直接指向你的
async def视图函数,而不是嵌套在 Gunicorn 的 fork 流程里 - 调试器(如 VS Code 的 Python debugger)能无缝 attach 到单进程 Uvicorn,加断点、看变量毫无障碍
- 别在开发时提前引入 Gunicorn —— 它会掩盖真实部署问题(比如你本地没测过
UvicornWorker初始化顺序,上线才发现数据库连接失败)
最常被忽略的一点:Gunicorn 的 --worker-class 必须写全路径 uvicorn.workers.UvicornWorker,少一个点或大小写错误(比如写成 Uvicornworker)就会静默 fallback 到默认 WSGI worker,然后报那个经典的 coroutine object is not callable 错误 —— 它不会提示你 worker 类加载失败,只会默默走错协议。










