必须用Gunicorn调用Uvicorn ASGI worker部署FastAPI，因FastAPI是ASGI应用而Gunicorn默认仅支持WSGI；启动命令需含--worker-class uvicorn.workers.UvicornWorker，Nginx反代须转发Host、X-Forwarded-For、X-Forwarded-Proto请求头并配合FastAPI启用trust_headers。
直接用 gunicorn 启动 FastAPI 必须搭配 uvicorn.workers.UvicornWorker，否则会报错或退化为同步模式——这是最常被忽略的前提。
为什么不能只用 Gunicorn 默认 worker？
FastAPI 是 ASGI 框架，而 Gunicorn 默认的 sync worker 只支持 WSGI 协议。强行用它跑 FastAPI 会导致：
- 异步路由（
@app.get("/async")）被阻塞执行，await不生效 - 出现
RuntimeWarning: coroutine 'xxx' was never awaited或直接 500 错误 - 并发能力掉回单线程水平，压测 QPS 可能只有 uvicorn 单进程的 1/3
必须显式指定 -k uvicorn.workers.UvicornWorker，让 Gunicorn 启动的是 Uvicorn 实例，而非自己解析请求。
启动命令里 app:app 到底指什么？
冒号前是 Python 模块路径（不含 .py），冒号后是模块内定义的 FastAPI 实例变量名。常见错误包括：
立即学习“Python免费学习笔记（深入）”；
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
-
main.py文件里写的是fastapi_app = FastAPI()，但命令写了main:app→ 应该是main:fastapi_app - 入口文件在子目录如
src/app/main.py，却没加src到PYTHONPATH→ 启动报ImportError: No module named 'app' - 用了
if __name__ == "__main__":包裹app = FastAPI()→ Gunicorn 导入时找不到变量，必须顶层定义
worker 数量设多少才合理？
不是越多越好，关键看 CPU 核心数和应用类型：
- CPU 密集型（如图像处理、模型推理）：设为
$(nproc) + 1，避免上下文切换开销 - I/O 密集型（如调外部 API、数据库查询）：可设为
2 * $(nproc) + 1，Uvicorn worker 本身能异步处理多个连接 - 内存受限环境（如 2GB RAM）：每个 Uvicorn worker 占约 80–120MB，4 个 worker 就可能吃光内存
推荐先用 -w 2 跑通，再根据 htop 观察 CPU 和 RSS 内存增长趋势调整。
配置文件比命令行参数更可靠
把参数硬编码在 gunicorn 命令里容易漏掉超时、日志等关键项。直接建 gunicorn.conf.py：
bind = "0.0.0.0:8000" workers = 4 worker_class = "uvicorn.workers.UvicornWorker" timeout = 120 keepalive = 5 accesslog = "./access.log" errorlog = "./error.log" loglevel = "info" reload = False # 生产环境必须关掉
然后只运行 gunicorn -c gunicorn.conf.py app:app。配置文件还能 git 管理、不同环境切分支，比一堆 shell 脚本健壮得多。
真正容易出问题的是 worker_class 的拼写——少个字母、大小写错（比如写成 uvicornworker 而非 UvicornWorker）、引号用中文标点，都会导致 Gunicorn 静默 fallback 到 sync 模式，表面能跑，实则性能崩盘。
