必须用gunicorn调用uvicorn.workers.uvicornworker，否则fastapi异步路由退化为同步、await失效、qps降至单进程uvicorn的1/3；因fastapi是asgi应用而gunicorn默认syncworker仅支持wsgi协议，无法解析asgi的scope/receive/send三元组。

必须用 gunicorn 调用 uvicorn.workers.UvicornWorker，否则 FastAPI 的异步路由会退化成同步执行，await 失效，QPS 可能只剩单进程 uvicorn 的 1/3。

为什么不能直接用 gunicorn 默认 worker 启动 FastAPI

FastAPI 是 ASGI 应用，而 gunicorn 默认的 syncworker 只支持 WSGI 协议。强行使用会导致：

• RuntimeWarning: coroutine 'xxx' was never awaited 或直接返回 500 错误
• 所有 @app.get("/async") 路由被阻塞执行，await 不起作用
• 并发能力掉回单线程水平，压测时连接堆积、响应延迟飙升

根本原因：Gunicorn 主进程把请求交给 syncworker 后，worker 自己解析、分发、执行——它根本不认识 ASGI 的 scope/receive/send 三元组。只有 uvicorn.workers.UvicornWorker 才会在每个子进程中真正启动一个 Uvicorn 实例来处理 ASGI 生命周期。

gunicorn 启动命令里 main:app 到底怎么写

冒号前是 Python 模块路径（不含 .py），冒号后是模块内定义的 FastAPI 实例变量名。常见错误包括：

• 文件叫 main.py，但里面写的是 fastapi_app = FastAPI()，却运行 gunicorn main:app → 应该是 main:fastapi_app
• 入口在 src/app/main.py，没把 src 加进 PYTHONPATH → 启动报 ImportError: No module named 'app'
• 用了子包结构（如 app.main:app），但当前目录不是项目根目录，或没加 --chdir /path/to/project

验证方式：在 shell 中运行 python -c "from main import app; print(app)"，能成功 import 就说明路径和变量名是对的。

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

worker 数量和超时参数怎么设才不翻车

多进程不是越多越好，关键看 CPU 核心数和 I/O 特性。默认公式是 workers = (2 × CPU核心数) + 1，但需结合实际调整：

• 8 核服务器上设 -w 17 常见，但若应用重度依赖数据库或外部 HTTP 调用，反而应减少到 -w 8 避免上下文切换开销
• --timeout 120 必须设，否则慢查询或长轮询可能让 worker 卡死；但别设太短（如 30），否则正常上传大文件会中断
• --keep-alive 5 推荐保留，HTTP/1.1 持久连接能降低 TCP 握手开销；Kubernetes 环境下可酌情调低
• 禁用 --preload 除非你确认所有初始化逻辑是进程安全的（比如 DB 连接池在 fork 后会失效）

线上建议用配置文件而非命令行，避免参数遗漏：gunicorn -c gunicorn.conf.py main:app，其中 gunicorn.conf.py 至少包含 worker_class、workers、timeout 和 bind。

Nginx 反代时最容易漏掉的三个请求头

FastAPI 在 Gunicorn+Uvicorn 组合下，若没配对 Nginx 请求头，request.url 会变成 http://localhost:8000，app.url_path_for() 生成的链接全错，WebSockets 直接失败：

• 必须透传 X-Forwarded-For：否则 request.client.host 拿到的是 Nginx 内网 IP
• 必须透传 X-Forwarded-Proto：否则 HTTPS 环境下重定向变成 http://
• 必须透传 Host：否则 request.url 域名丢失，OpenAPI 文档里的 Try-it-out 按钮指向错误地址

对应 Nginx 配置段要包含：

proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;

同时 FastAPI 初始化时得加 trust_headers=True，例如 app = FastAPI(trust_headers=True)，否则 Uvicorn Worker 会忽略这些头。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！