FastAPI项目怎么用Uvicorn部署

陌墨吖_2548

陌墨吖_2548

2026-11-20

576人浏览

原创

直接用uvicorn.run()启动会导致服务无守护、无日志轮转、崩溃不自愈,生产环境必须用uvicorn命令行或Gunicorn+UvicornWorker管理;--workers必设,--reload仅限开发,--host 0.0.0.0需显式指定。

fastapi项目怎么用uvicorn部署

uvicorn

是 FastAPI 的默认 ASGI 服务器,适合开发和轻量级生产场景。它不是“部署工具”,而是运行时服务器——关键在于:**怎么启动、怎么配参数、哪些参数不能乱设**。

直接用 uvicorn run 启动会出什么问题

常见错误现象:KeyboardInterrupt 或终端关闭后服务立即退出;reload=True 在生产环境导致进程反复重启、文件句柄泄漏;单进程扛不住并发请求,CPU 利用率低但响应变慢。

根本原因:直接调用 uvicorn.run() 是为调试设计的,它把整个 Python 进程当做一个“可中断的脚本”来跑,没做守护、日志轮转、信号处理等生产必需能力。

  • 别在生产环境写 if __name__ == "__main__": uvicorn.run(...)
  • --reload 只能用于开发,它依赖 watchfiles 监听文件变化,会吃 CPU 且不兼容某些文件系统(如 NFS)
  • --host 0.0.0.0 必须显式指定,否则默认只监听 127.0.0.1,外网访问失败

命令行启动 uvicorn 的正确姿势

核心是用 uvicorn 命令而非 Python 脚本调用。它更稳定、参数更可控,也方便配合 systemd 或宝塔等管理。

基础命令格式:uvicorn main:app --host 0.0.0.0 --port 8000

  • main:app 中 main 是 Python 模块名(不含 .py),app 是模块内定义的 FastAPI() 实例变量名
  • --workers N:必须设!单核机器建议 2,多核建议 2 × CPU核心数。不加该参数默认只起 1 个 worker,无法利用多核
  • --limit-concurrency 100:防止单个 worker 被长连接占满,尤其有 SSE 或 WebSocket 时要加
  • --log-level warning:生产环境别用 info 或 debug,日志量爆炸且含敏感路径信息

为什么不能只靠 uvicorn 做生产部署

Uvicorn 本身不管理进程生命周期。一旦某个 worker 崩溃(比如某次请求触发未捕获异常),整个服务就少一个 worker,且不会自动拉起。Gunicorn 就是为解决这个问题存在的。

fastapi-pro
fastapi-pro

使用 FastAPI、SQLAlchemy 2.0 和 Pydantic V2 构建高性能异步 API。精通微服务、WebSocket 和现代 Python 异

下载

真实生产中,uvicorn 应作为 Gunicorn 的 worker 类型,而不是独立暴露端口:

  • Gunicorn 负责监听端口、分发请求、健康检查、worker 进程保活
  • 每个 Gunicorn worker 内部跑一个 UvicornWorker,专注处理 ASGI 协议转换
  • 启动命令示例:gunicorn main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8000

如果你硬要用纯 uvicorn 上线,至少得套一层 systemd 或 supervisord 来做进程守护,否则等于裸奔。

宝塔或 Docker 里怎么配 uvicorn

宝塔 Python 项目管理器本质是封装了 uvicorn 命令,但它默认不传 --workers,也不支持自定义 --limit-concurrency。容易踩的坑:

  • 宝塔界面里“启动命令”填的是完整 shell 命令,不是 Python 表达式,所以写 uvicorn main:app --workers 4 --host 0.0.0.0 --port 8090 才对,别加 python -m
  • Docker 中别用 ENTRYPOINT ["uvicorn"] 然后靠 CMD 补参数,容易因空格或引号解析失败;推荐写死在 ENTRYPOINT 里:["uvicorn", "main:app", "--workers", "4", "--host", "0.0.0.0", "--port", "8000"]
  • 所有环境都必须确认 uvicorn[standard] 已安装,否则 --workers 多进程模式会静默退化成单进程

真正麻烦的从来不是怎么启动,而是启动之后谁来管它崩溃、内存涨、日志满——这些恰恰是 uvicorn 不负责的部分。

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

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API

Python FastAPI 异步开发利用 async/await 关键字,通过定义异步视图函数、使用异步数据库库 (如 databases)、异步 HTTP 客户端 (如 httpx),并结合后台任务队列(如 Celery)和异步依赖项,实现高效的 I/O 密集型 API,显著提升吞吐量和响应速度,尤其适用于处理数据库查询、网络请求等耗时操作,无需阻塞主线程。

2025.12.22

119

5

Python 微服务架构与 FastAPI 框架
Python 微服务架构与 FastAPI 框架

本专题系统讲解 Python 微服务架构设计与 FastAPI 框架应用,涵盖 FastAPI 的快速开发、路由与依赖注入、数据模型验证、API 文档自动生成、OAuth2 与 JWT 身份验证、异步支持、部署与扩展等。通过实际案例,帮助学习者掌握 使用 FastAPI 构建高效、可扩展的微服务应用,提高服务响应速度与系统可维护性。

2026.02.06

594

18

Python Web框架FastAPI 全栈开发教程合集
Python Web框架FastAPI 全栈开发教程合集

以 FastAPI 为核心,讲解现代 Python Web API 的高效开发方式,涵盖路由定义与路径参数/查询参数/请求体绑定、Pydantic 模型的数据校验与序列化、依赖注入(Depends)系统的分层设计、中间件与 CORS 配置、OAuth2 + JWT 认证流程、后台任务(BackgroundTasks)、WebSocket 实时通信、SQLAlchemy 异步 ORM 集成、自动生成 OpenAPI/Swagger 交互文

2026.05.09

796

23

Python FastAPI异步微服务与高性能接口设计
Python FastAPI异步微服务与高性能接口设计

本专题聚焦 Python FastAPI 框架在高性能接口与微服务开发中的应用,讲解异步请求处理、依赖注入机制、路由设计、数据库异步操作以及接口性能优化策略。结合实际项目案例,帮助开发者构建高并发、低延迟的现代化后端服务架构。

2026.06.16

679

12

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

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

2026.11.17

20

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

20

15

GoFrame框架零基础入门
GoFrame框架零基础入门

本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。

2026.11.17

20

15

SQLAlchemy 一对多关系怎么建立
SQLAlchemy 一对多关系怎么建立

SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。

2026.11.17

20

10

SQLAlchemy 如何增删改查
SQLAlchemy 如何增删改查

SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。

2026.11.17

20

11

热门下载

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

精品课程

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

共0课时 | 0人学习

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

共0课时 | 0人学习