宝塔面板部署Uvicorn应优先选用「网站+反向代理」方案:SSH运行nohup uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips="*" > uvicorn.log 2>&1 &,再在宝塔添加反向代理指向http://127.0.0.1:8000,并确保Nginx配置无listen冲突、SSL已启用、proxy_set_header Host $host已配置。

宝塔面板部署 Uvicorn 服务不能直接当成普通 Python 脚本运行,必须明确区分「项目管理器」和「网站+反向代理」两种路径——前者只适合纯 ASGI 入口、结构规整的 FastAPI/Starlette 项目;后者才是通用解法,尤其当你用 uvicorn.run() 启动、或项目含模型加载/异步初始化逻辑时。
Uvicorn 启动命令在宝塔里怎么填才不报错
宝塔「Python 项目管理器」默认执行 python app.py 或 python wsgi.py,但它不识别 uvicorn main:app --host 0.0.0.0 --port 8000 这类命令行启动方式。直接填会卡在“启动中”或日志里反复报 ModuleNotFoundError。
- 若你坚持用项目管理器:入口文件(如
main.py)末尾必须加if __name__ == "__main__": uvicorn.run("main:app", host="0.0.0.0", port=8000),且「启动文件」选main.py、「启动命令」填python main.py - 若你用
gunicorn+UvicornWorker:启动命令写成gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker --bind 127.0.0.1:8000 --timeout 120,注意端口别和 Nginx 冲突 - 千万别在启动命令里加
--reload:生产环境不支持热重载,会导致进程反复重启
为什么反向代理比项目管理器更可靠
因为宝塔「Python 项目管理器」底层依赖 Supervisor + gunicorn,对项目结构敏感:它要求入口模块可直接 import、不能有阻塞式初始化(比如加载大模型)、不处理 async def on_startup() 钩子。而手动启 uvicorn 并配反向代理,完全由你控制生命周期。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 先 SSH 登录,cd 到项目目录,执行
nohup uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1 --proxy-headers --forwarded-allow-ips="*" > uvicorn.log 2>&1 & - 进宝塔「网站」→「反向代理」→「添加反向代理」,目标 URL 填
http://127.0.0.1:8000,不要填公网 IP 或域名 - 务必删掉网站配置文件里的
listen 8888;行(否则端口被 Nginx 自己占着,反向代理连不上) -
--proxy-headers和--forwarded-allow-ips="*"必须加上,否则request.url.scheme会是 http,request.base_url无法正确识别 HTTPS
常见错误现象和对应检查点
部署后访问 502 或白屏,90% 出在这几个地方:
-
connect refused:Uvicorn 没起来,或监听地址不是0.0.0.0(写了127.0.0.1就只能本机访问) -
502 Bad Gateway:反向代理目标 URL 端口和 Uvicorn 实际监听端口不一致,或 Nginx 配置里漏了proxy_set_header Host $host; - 接口返回
http://却走 HTTPS 域名:没加--proxy-headers,或宝塔 SSL 证书没在「网站」→「SSL」里启用(反向代理不会自动透传 HTTPS) - 日志里反复出现
Address already in use:端口被其他进程占了,用lsof -i :8000查,或换端口再试
最易被忽略的是 Uvicorn 的 --forwarded-allow-ips 参数——哪怕你只用一台服务器,也得设成 "*" 或 "127.0.0.1",否则所有 request.client.host 都会变成 127.0.0.1,健康检查、IP 限流、Websocket 协议升级全失效。










