讲师中心 微信公众号

工具推荐

视频效率加速
AniShort
AniShort

AI短剧协同制作平台

剧云
剧云

中文短剧剧本制作平台

updream

一键生成高质量推广成片

Seko
Seko

AI短剧一键生成成片

宝塔面板怎么部署Uvicorn服务

云辰君_6502

云辰君_6502

发布时间:2026-11-18 10:19:09

|

210人浏览过

|

来源于php中文网

原创

宝塔面板部署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服务

宝塔面板部署 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
Uvicorn 0.52.1

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 协议升级全失效。

热门AI工具

更多
Loomy
Loomy Hot

一款AI工具,主要用于科大讯飞发布的桌面级 AI 助理,比 OpenClaw 更易用、更安全!,适合需要提升相关任务效率的用户。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

创客贴AI

创客贴AI是一款AI图像与设计工具,AI辅助的智能在线设计工具。

切问学术

切问学术是一款AI论文写作工具,复旦大学NLP团队推出的AI学术智能体。

码上飞
码上飞 Hot

一款基于自然语言的AI应用开发平台,可根据用户描述自动生成应用程序,帮助个人和团队快速完成应用原型与开发。

函子Zion

一款支持AI搭建、可视化编辑和多端发布的全栈无代码开发平台。

超级简历WonderCV

一款AI办公效率工具,主要用于免费求职简历模版下载制作,应届生职场人必备简历制作神器,适合需要提升相关任务效率的用户。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

相关专题

更多
python打包成可执行文件
python打包成可执行文件

本专题为大家带来python打包成可执行文件相关的文章,大家可以免费的下载体验。

1951

2023.07.20

python能做什么
python能做什么

python能做的有:可用于开发基于控制台的应用程序、多媒体部分开发、用于开发基于Web的应用程序、使用python处理数据、系统编程等等。本专题为大家提供python相关的各种文章、以及下载和课程。

5524

2023.07.25

format在python中的用法
format在python中的用法

Python中的format是一种字符串格式化方法,用于将变量或值插入到字符串中的占位符位置。通过format方法,我们可以动态地构建字符串,使其包含不同值。php中文网给大家带来了相关的教程以及文章,欢迎大家前来阅读学习。

1889

2023.07.31

python教程
python教程

Python已成为一门网红语言,即使是在非编程开发者当中,也掀起了一股学习的热潮。本专题为大家带来python教程的相关文章,大家可以免费体验学习。

33757

2023.08.03

python环境变量的配置
python环境变量的配置

Python是一种流行的编程语言,被广泛用于软件开发、数据分析和科学计算等领域。在安装Python之后,我们需要配置环境变量,以便在任何位置都能够访问Python的可执行文件。php中文网给大家带来了相关的教程以及文章,欢迎大家前来学习阅读。

3967

2023.08.04

python eval
python eval

eval函数是Python中一个非常强大的函数,它可以将字符串作为Python代码进行执行,实现动态编程的效果。然而,由于其潜在的安全风险和性能问题,需要谨慎使用。php中文网给大家带来了相关的教程以及文章,欢迎大家前来学习阅读。

3967

2023.08.04

scratch和python区别
scratch和python区别

scratch和python的区别:1、scratch是一种专为初学者设计的图形化编程语言,python是一种文本编程语言;2、scratch使用的是基于积木的编程语法,python采用更加传统的文本编程语法等等。本专题为大家提供scratch和python相关的文章、下载、课程内容,供大家免费下载体验。

1283

2023.08.11

python合并两个列表
python合并两个列表

Python是一种强大的编程语言,具有许多方便的功能和工具。在Python中,有多种方法可以合并两个列表。php中文网给大家带来了相关的教程以及文章,欢迎大家前来学习阅读。

636

2023.08.10

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

0

2026.11.17

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
Uvicorn官方部署指南
Uvicorn官方部署指南

共0课时 | 0人学习

Uvicorn官方安装与入门手册
Uvicorn官方安装与入门手册

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn