Uvicorn：Python ASGI Web 服务器

作者：马育民 • • 阅读：10056

介绍

Uvicorn 是一款高性能、轻量级 Python ASGI Web 服务器。
名称由来：UV（Ultra-Violet 紫外线）+ unicorn（独角兽），寓意极速异步服务器。

  • 作者：Tom Christie（Starlette、ASGI 规范发起者）
  • 协议：ASGI（异步服务器网关接口），对标同步世界的 WSGI
  • 底层核心依赖：
    • uvloop：Cython 实现的高性能事件循环，替代 Python 标准 asyncio
    • httptools：C 实现的 HTTP 解析器（Node.js 同款解析内核）

适用框架

FastAPI、Starlette、Django Channels、Litestar 等异步 Web 框架。

ASGI vs WSGI 区别

类型 同步/异步 长连接(WebSocket) 适用服务器
WSGI 纯同步 ❌ 原生不支持 Gunicorn、uWSGI
ASGI 支持async/await ✅ WebSocket、SSE、长轮询 Uvicorn、Hypercorn、Daphne

简单理解：
WSGI 只能一次性处理短 HTTP 请求；
ASGI 支持持续双向数据流，天然适配实时通信。

特性

  1. 原生异步高并发
    单进程单事件循环，可以同时维持成千上万连接，I/O 等待时不会阻塞。非常适合接口服务、实时推送、WebSocket 聊天。

  2. 支持 HTTP/1.1 + WebSocket
    原生支持双向长连接，是开发实时应用首选。

  3. 开发友好：代码热重载 --reload
    文件变更自动重启服务，仅限本地调试，禁止生产使用。

  4. 同时兼容异步/同步接口
    可以运行 async def 接口，也能正常执行普通同步函数（内部自动线程池调度）。

  5. 支持多进程、Unix Socket、SSL HTTPS、反向代理头部解析

  6. 轻量、启动速度快，配置简洁

局限：目前官方尚不原生支持 HTTP/2、HTTP/3；如需 HTTP/3 可以选择 Hypercorn。

安装

# 最简安装（不含uvloop、httptools，性能较低）
pip install uvicorn

# 推荐完整版，包含性能依赖【生产必选】
pip install uvicorn[standard]

要求 Python ≥3.10（新版本uvicorn）

基础使用方式

1. 命令行启动（最常用）

文件 main.py

from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def hello():
    return {"msg":"hello uvicorn"}

启动命令格式：uvicorn 模块名:实例名

# 基础启动，仅本机访问
uvicorn main:app

# 允许外部访问，端口8000
uvicorn main:app --host 0.0.0.0 --port 8000

# 开发模式：开启热重载
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

2. 代码内编程启动（uvicorn.run()）

# main.py
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"hello": "uvicorn program start"}

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=False,
        workers=1
    )

⚠️ 坑：Windows下，多进程模式 workers>1 不能搭配 reload=True，会报错。

常用参数详解

uvicorn main:app \
--host 0.0.0.0 \                # 监听地址，0.0.0.0允许外网访问
--port 8000 \                   # 端口
--workers 4 \                   # 工作进程数量（多进程多核利用）
--loop uvloop \                 # 事件循环，可选 uvloop / asyncio
--log-level info \              # 日志级别 critical/error/warning/info/debug
--access-log \                  # 开启访问日志（生产可关闭提升性能）
--timeout-keep-alive 10 \       # HTTP长连接空闲超时
--graceful-timeout 30 \         # 优雅关闭等待时长
--limit-concurrency 2000 \      # 限制最大并发连接，防止雪崩
--proxy-headers \               # 解析Nginx反向代理传递的真实客户端IP
--ssl-certfile cert.pem \
--ssl-keyfile key.pem           # HTTPS证书
参数说明
  1. --reload
    开发专用；启动额外监控进程，文件变动重启worker；生产环境必须关闭！严重损耗性能。
  2. --workers N
    uvicorn 内置多进程模式。
  • Linux/macOS：推荐 CPU核心数 ~ 2*核心数
  • Windows：uvicorn 的多进程稳定性较差，Windows生产环境建议单worker，或者改用 Gunicorn。

    注意：多进程之间内存隔离，全局变量不共享！

  1. --loop
  • uvloop（默认）：性能最高
  • asyncio：兼容性模式，部分第三方库不兼容uvloop时使用

六、部署模式（重点区分开发 / 生产）

模式1：本地开发（简单）

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

模式2：生产方案A —— 原生uvicorn多进程（简单部署）

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

优点：一条命令搞定；缺点：进程监控、平滑重启能力弱。

模式3：生产方案B —— Gunicorn + UvicornWorker【业界标准推荐】

Gunicorn 作为主进程管理器，管理多个 Uvicorn 异步 worker

pip install gunicorn
# 启动
gunicorn main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000
  • -w 4：4个worker进程
  • -k uvicorn.workers.UvicornWorker：使用uvicorn异步worker（支持ASGI/WebSocket）
    ✅ 优势：
    成熟进程管理、自动重启崩溃进程、支持平滑重启、日志管理完善；Linux服务器首选。

架构标准链路：
Client → Nginx(反向代理、ssl、限流) → Gunicorn → UvicornWorker → FastAPI应用

七、Uvicorn 常见坑 & 最佳实践

1. 不要生产开启 --reload

自动重载会产生额外进程开销，存在安全风险。

2. 同步阻塞代码会拖垮整个事件循环

# ❌ 错误！同步耗时代码阻塞事件循环
import time
@app.get("/block")
async def test():
    time.sleep(5)

# ✅ 正确：使用异步sleep
import asyncio
@app.get("/ok")
async def test():
    await asyncio.sleep(5)

如果必须调用同步阻塞IO（数据库、请求），使用 asyncio.to_thread() 放到线程运行。

3. 多进程环境全局状态不共享

--workers>1 每个进程独立内存，不要依赖内存缓存；改用Redis等外部缓存。

4. Docker容器部署建议

容器中推荐单worker，由K8s/Docker Compose横向扩容，不要在容器内部开启多workers。

5. 反向代理必须开启 --proxy-headers

搭配Nginx时启用，才能正确获取客户端真实IP、请求协议。

八、同类 ASGI 服务器横向对比

  1. Uvicorn
    性能最优，生态最好，FastAPI官方默认；仅支持HTTP/1.1 + WebSocket。
  2. Hypercorn
    支持 HTTP/2、HTTP/3；性能略低于uvicorn。
  3. Daphne
    Django Channels官方配套，纯Python解析，性能偏弱。

九、常见问题

Q：Uvicorn 和 Gunicorn 是什么关系？

  • Gunicorn 原生是WSGI同步服务器，不支持ASGI
  • 通过 UvicornWorker 适配器，Gunicorn可以调度uvicorn进程，实现「进程管理+异步处理」组合。

Q：单进程uvicorn能利用多核CPU吗？

不能！asyncio事件循环单线程运行，一个worker只能占用一个CPU核心。
想要利用多核，必须启动多个worker进程（--workers 或gunicorn托管）。

十、极简生产标准启动模板（Linux）

# 搭配nginx反向代理
gunicorn main:app \
-w 3 \
-k uvicorn.workers.UvicornWorker \
--bind 127.0.0.1:8000 \
--proxy-headers \
--log-level warning

如果你需要，我可以给你一份配套的 Nginx 配置文件 + systemd 服务托管脚本，直接用于服务器上线部署。

原文出处：/show_1GW3mzWNFdjM.html

吉ICP备15003043号