不能只用uvicorn或gunicorn：uvicorn缺进程管理与平滑重启，gunicorn不原生支持async；需用gunicorn调度+uvicornworker处理，且必须安装uvicorn[standard]、正确配置worker-class和端口参数。
为什么不能只用 Uvicorn 或只用 Gunicorn？
Uvicorn 是纯异步服务器，单进程就能高效处理大量并发请求，但没法自动管理多进程、健康检查、平滑重启；Gunicorn 是老牌 WSGI 服务器，自带进程管理、负载均衡和信号处理，但它原生不支持 async —— 直接跑 async 应用会卡死或报 RuntimeWarning: coroutine 'app' was never awaited。
混合部署不是“叠 Buff”，而是让 Gunicorn 做进程调度，Uvicorn 做实际请求处理。关键在：Gunicorn 必须以 uvicorn.workers.UvicornWorker 为工作类，否则就退化成同步模式。
- 必须安装
uvicorn[standard]（带gunicorn依赖的版本），否则UvicornWorker找不到 - Gunicorn 配置里不能设
--worker-class sync或漏掉--worker-class uvicorn.workers.UvicornWorker -
uvicorn自身的命令行参数（如--host、--port）在 Gunicorn 模式下失效，得用 Gunicorn 的-b 0.0.0.0:8000
如何写一个能被 Gunicorn 正确加载的 ASGI 应用入口？
很多报错如 ImportError: cannot import name 'application' 或启动后 500 且日志里出现 TypeError: 'coroutine' object is not callable，根源都在入口模块没按 ASGI 协议暴露可调用对象。
ASGI 要求入口是一个可调用的 app（函数或实例），接受 scope, receive, send 三个参数。FastAPI/Starlette 默认满足，但手写时容易错。
立即学习“Python免费学习笔记（深入）”；
- 入口文件（如
main.py）末尾必须有app = ...这样的赋值，且不能是async def app(...)—— 那是协程函数，不是 ASGI 应用实例 - 如果用
async def写了路由处理函数，没问题；但顶层app必须是 Starlette/FastAPI 实例或兼容 ASGI 的 callable - 别在入口里直接调
uvicorn.run()，Gunicorn 会自己调用app，重复启动会端口冲突
示例（app.py）：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Gunicorn + Uvicorn 启动时最关键的几个配置项
参数配错会导致 CPU 空转、内存暴涨、无法响应 SIGTERM，甚至静默失败。重点不在“多”而在“准”。
-
-w 4：推荐设为CPU 核心数 × 2，Uvicorn Worker 本身是异步的，每个 worker 可处理大量并发，盲目加 worker 数反而增加上下文切换开销 -
--worker-class uvicorn.workers.UvicornWorker：唯一合法的异步 worker 类，拼错（如少个U或写成uvicorn_worker）会导致回退到同步模式 -
--timeout 120：Uvicorn 默认超时是 60 秒，Gunicorn 默认是 30 秒，建议统一设高些，避免长连接或文件上传中断 -
--graceful-timeout 120：平滑重启时给正在处理的请求留够时间，低于--timeout可能导致请求被强制切断 - 不要加
--preload：它会让每个 worker 进程都提前导入应用，可能引发异步事件循环冲突（如RuntimeError: There is no current event loop in thread）
常见错误现象和定位方法
出问题时别急着改配置，先看日志源头——Gunicorn 日志和 Uvicorn Worker 日志混在一起，但错误类型有规律。
- 启动就报
ModuleNotFoundError: No module named 'uvicorn.workers'：说明uvicorn没装对，运行pip install "uvicorn[standard]"重装 - 请求返回 500 且日志里有
TypeError: object NoneType can't be used in 'await' expression：通常是入口app没正确定义，或中间件里写了await None - CPU 100% 但无请求进来：大概率是
--worker-class错了，Gunicorn 在用默认的syncworker 跑异步应用，死锁了 - 发
SIGTERM后进程不退出：检查--graceful-timeout是否太短，或应用里有没有没 await 的长任务（比如忘了await db.execute()）
调试时加 --log-level debug 和 --capture-output，把 Uvicorn Worker 的日志也打出来，不然只看 Gunicorn 主进程日志会漏关键信息。
真正麻烦的从来不是怎么配，而是哪个环节悄悄绕过了异步——比如某个同步数据库驱动、某段没 await 的 HTTP 调用、或者日志里一闪而过的 Task was destroyed but it is pending!。这些地方不会报错，但会让整个服务变得不可预测。
