宝塔面板如何部署FastAPI应用？利用Gunicorn与Nginx反代协同工作-php教程-PHP中文网

可行，但gunicorn必须通过--worker-class uvicorn.workers.UvicornWorker调用Uvicorn ASGI worker，否则因FastAPI是ASGI应用而非WSGI callable而报错或静默失败；Nginx反向代理需正确配置proxy_set_header转发请求头，并在FastAPI中启用trust_headers参数以获取真实IP。

宝塔面板如何部署fastapi应用？利用gunicorn与nginx反代协同工作

宝塔面板部署 FastAPI，用 Gunicorn + Nginx 是可行的，但必须明确一点：gunicorn 本身不原生支持 ASGI，直接运行 gunicorn main:app 会报错或静默失败。正确方式是让 gunicorn 作为进程管理器，调用 uvicorn 的 ASGI worker —— 这才是生产环境里兼顾稳定性与异步能力的组合。

为什么不能直接用 gunicorn 运行 FastAPI？

FastAPI 是 ASGI 应用，而 gunicorn 默认只支持 WSGI（如 Flask/Django）。如果你在宝塔 Python 项目中填入类似 gunicorn main:app --bind 0.0.0.0:8000 的启动命令，日志里大概率会出现：

AssertionError: Expected a callable, but got <class></class>

或者直接卡住无响应。这是因为 gunicorn 尝试以 WSGI 模式加载 main:app，但 FastAPI 实例不是 WSGI callable。

解决路径只有一条：指定 --worker-class 为 uvicorn.workers.UvicornWorker，让每个 gunicorn worker 实际跑的是 uvicorn 实例。

宝塔中配置 Gunicorn + Uvicorn 启动命令

进入宝塔「Python项目管理器」→ 编辑你的项目 → 「运行配置」→ 「启动命令」，填入以下格式（注意空格和参数顺序）：

gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 --timeout 120 --keep-alive 5

main:app 中的 main 是你的 Python 文件名（如 main.py），app 是 FastAPI 实例变量名，需严格匹配
--workers 4 表示启动 4 个进程；若服务器内存 ≤ 2GB，建议设为 2，避免 OOM
--bind 端口（如 8000）不能与 Nginx 监听端口冲突，也别用 127.0.0.1 —— 宝塔内部网络走的是 0.0.0.0
--timeout 建议 ≥ 120，防止大文件上传或慢查询被误杀

保存后重启项目，看日志是否出现类似 Booting worker with pid: XXXX 和 Uvicorn running on http://0.0.0.0:8000 的输出，才算真正生效。

Nginx 反向代理必须加的 header 转发

仅靠 Gunicorn+Uvicorn 启动还不够。如果你绑定了域名、启用了 Cloudflare 或其他 CDN，不配好 Nginx 的请求头转发，request.client.host 或 X-Forwarded-For 拿到的永远是 127.0.0.1 或 CDN IP。

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

在宝塔网站设置 → 「反向代理」→ 编辑规则，在「目标URL」下方的「高级」区域，手动补全以下三行（不能少）：

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

同时确认该代理规则绑定的域名，在 Nginx 配置文件（如 /www/server/panel/vhost/nginx/your-domain.conf）中，location / 块里确实包含上述三行 —— 宝塔有时会漏掉 X-Forwarded-For，尤其你之前手动改过配置。

做完后务必「重载 Nginx」，而不是只点「保存」。

FastAPI 中获取真实客户端 IP 的写法

即使 Nginx 转发了 X-Forwarded-For，FastAPI 默认也不会自动解析它。你得显式启用信任代理：

from fastapi import FastAPI, Request

app = FastAPI(
    trust_headers=["X-Forwarded-For", "X-Real-IP"]
)

@app.get("/ip")
async def get_ip(request: Request):
    return {"client_host": request.client.host}

关键点：

trust_headers 参数必须显式传入，且值要跟 Nginx 发送的 header 名完全一致（大小写敏感）
如果用了 Cloudflare，还需在 Nginx 的 http 块加 set_real_ip_from 和 real_ip_header（参考宝塔 luawaf.conf 插入位置），否则 $remote_addr 仍是 Cloudflare 节点 IP
别依赖 request.headers.get("x-forwarded-for") 手动取 —— 它可能被伪造，request.client.host 经过 trust_headers 校验后才可信

最易被忽略的是：Gunicorn 的 --worker-class 必须带完整模块路径，少一个点（比如写成 uvicorn.worker.UvicornWorker）就会启动失败，且错误日志藏得很深 —— 宝塔项目日志里只显示 “worker timeout”，得去 /www/wwwroot/your-project/logs/gunicorn.error.log 找真正原因。