uvicorn 详细介绍

一句话概括uvicorn 是 Python 的 ASGI 异步 Web 服务器专门用来运行 FastAPI、Starlette、Quart 这类异步 Web 框架相当于异步版的 gunicorn底层用 C 实现的uvloop和httptools性能很高PyPI。ASGI异步服务器网关接口是 WSGI同步的下一代标准原生支持 async/await、WebSocket、HTTP/2、长连接。 WSGI 只能处理一次性 HTTP 请求不支持 WebSocket。一、核心底层依赖uvloop高性能事件循环基于 libuvNode.js 底层替换 Python 默认 asyncio 循环大幅提升 IO 并发httptoolsC 语言编写的 HTTP 解析器解析请求速度远快于纯 Python 实现安装完整版pip install uvicorn[standard]会自动带上 uvloophttptools 极简安装pip install uvicorn只装纯 Python 版本性能弱一点二、核心能力✅ 支持协议HTTP/1.1、HTTP/2、WebSocket长连接、实时推送、聊天服务 ✅ 原生异步协程I/O 密集场景数据库、调用第三方接口并发能力极强 ✅ 开发自动重载--reload改代码自动重启 ✅ 支持 HTTPS、Unix 域套接字、代理头解析Nginx 反向代理拿真实客户端 IP ✅ 支持命令行启动也支持代码内用uvicorn.run()编程启动 ✅ 可以独立运行也可以作为 gunicorn 的 worker 进程生产常用⚠️ 短板单 worker 是单事件循环同一个 worker 内 CPU 密集任务会阻塞整个事件循环适合 IO 密集 API不适合大量计算型接口三、基础使用示例1. 最简单的 ASGI 应用main.py# main.py from starlette.applications import Starlette from starlette.responses import PlainTextResponse from starlette.routing import Route async def homepage(request): return PlainTextResponse(Hello Uvicorn) app Starlette(routes[Route(/, homepage)])2. 命令行启动# 开发模式代码修改自动重启监听本地127.0.0.1:8000 uvicorn main:app --reload # 对外暴露服务监听所有网卡端口8000 uvicorn main:app --host 0.0.0.0 --port 8000main:app含义main main.py 模块app 模块里的 ASGI 实例变量名3. 在 Python 代码内部启动import uvicorn if __name__ __main__: uvicorn.run(main:app, host0.0.0.0, port8000, reloadTrue)四、高频参数清单表格参数说明--host监听地址0.0.0.0 允许外部访问默认127.0.0.1仅本机访问--port端口默认 8000--reload开发专用代码变更自动重启生产禁止开启不能和 --workers 一起用--workers N多进程N 进程数一般推荐CPU核心数 * 2 1--loop uvloop强制使用 uvloop 事件循环性能更高--log-level日志级别debug /info/warning /error--ssl-certfile / --ssl-keyfileHTTPS 证书和私钥开启 https--proxy-headers开启代理头Nginx 反向代理时获取真实客户端 IP五、部署模式重点区分开发 / 生产① 开发环境直接 uvicornuvicorn main:app --host 0.0.0.0 --port 8000 --reload优点简单改代码自动重启缺点性能弱不适合正式线上。② 生产推荐方案gunicorn uvicorn worker最主流FastAPI 官方推荐gunicorn 做进程管理器master 主进程负责监控、拉起、重启多个 worker每个 worker 是一个 uvicorn 实例处理异步请求。gunicorn main:app \ --workers 4 \ --worker-class uvicorn.workers.UvicornWorker \ --bind 0.0.0.0:8000master 进程不处理 http只管理 workerworker 崩溃自动重启workeruvicorn处理异步请求、websocket前面一般再加一层 Nginx 反向代理处理静态资源、ssl、限流、负载均衡架构客户端 → Nginx → Gunicorn(master) → UvicornWorker(ASGI)③ 直接用 uvicorn 多进程简单生产不推荐高并发uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4uvicorn 自带简易主进程管理但是进程管理能力不如 gunicorn 健壮。六、uvicorn vs Gunicorn 对比表格项目uvicorngunicorn接口标准ASGI异步默认 WSGI同步可加载 uvicorn worker 支持 ASGI适用框架FastAPI、Starlette、QuartFlask、Django同步并发模型单进程内协程异步支持多进程多进程预分叉模型WebSocket✅原生支持❌原生不支持要 uvicorn worker定位ASGI 请求处理器成熟的进程管理器七、适用场景✅ 适合FastAPI 异步 API 服务WebSocket 实时通信聊天、消息推送、实时监控高并发 IO 接口大量数据库 / HTTP 调用流式响应 SSE❌ 不适合纯 CPU 密集型计算接口单 worker 会阻塞事件循环大量老旧同步代码、阻塞型数据库驱动会卡住协程八、同类 ASGI 服务器uvicorn最流行FastAPI 默认Hypercorn支持 HTTP/3功能更全DaphneDjango Channels 官方 ASGI 服务器九、常见踩坑点--reload不能上生产会额外开监控进程安全和性能差--reload和--workers不能同时使用单 uvicorn worker 遇到同步阻塞代码time.sleep、同步 mysql 驱动会卡死整个服务要用 async 版本驱动Nginx 反向代理时必须加--proxy-headers否则拿到的 IP 是 127.0.0.1如果你需要我可以给你uvicorn gunicorn Nginx 完整部署配置文件或者 生产环境 systemd 托管 uvicorn/gunicorn 的 service 脚本。