ASGI 服务器Uvicorn介绍

一、Uvicorn 是什么？

• ASGI 服务器：用于运行异步 Web 应用。对比传统的 WSGI 服务器，比如 Gunicorn，Uvicorn 支持异步操作，适合 FastAPI 或 Starlette 这样的框架； 简言之，Uvicorn 是专为异步 Python Web 框架（如 FastAPI、Starlette）设计的高性能服务器。
• 核心特性：
  • 支持 HTTP/1.1 和 WebSocket。
  • 基于 uvloop 和 httptools 实现高效 I/O 处理。
  • 轻量级，适合开发和部署异步应用。

二、安装 Uvicorn

1. 基础安装

pip install uvicorn

2. 安装性能优化版（推荐）

包含 uvloop 和 httptools 依赖：

pip install uvicorn[standard]

三、快速启动 FastAPI 应用

1. 示例代码（main.py）

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
return {"message": "Hello World"}

2. 启动命令

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

• 参数解析：
  • main:app：main.py 文件中的 app 实例。
  • –host 0.0.0.0：允许所有 IP 访问。
  • –port 8000：监听端口号。
  • –reload：代码修改后自动重启（仅用于开发环境）。

四、常用命令行参数

参数

说明

五、生产环境部署

1. 单进程运行

uvicorn main:app –host 0.0.0.0 –port 8000

2. 多进程运行（结合 Gunicorn）

pip install gunicorn

gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

• 参数解析：
  • -w 4：启动 4 个工作进程（通常设为 CPU 核心数 × 2 + 1）。
  • -k uvicorn.workers.UvicornWorker：指定 Uvicorn 工作器。

3. 使用 HTTPS

uvicorn main:app –ssl-keyfile key.pem –ssl-certfile cert.pem

六、性能调优

1. 超时设置

# 减少空闲连接占用

uvicorn main:app –timeout-keep-alive 10

2. 调整日志级别

# 生产环境关闭 debug 日志

uvicorn main:app –log-level warning

3. 启用多核 CPU

uvicorn main:app –workers 4

七、常见问题解决

1. 端口冲突

Error: [Errno 98] Address already in use

• 解决方案：更换端口 –port 8001 或终止占用进程：

   

  lsof -i :8000

  kill -9 <PID>

2. 模块导入错误

Error: No module named 'main'

• 解决方案：检查文件路径和变量名，确保 main:app 指向正确的模块和应用实例。

3. SSL 证书错误

SSL error: [SSL] PEM lib (_ssl.c:4013)

• 解决方案：确保证书和私钥文件路径正确且格式为 PEM。

八、总结

• 开发环境：使用 –reload 实时调试。
• 生产环境：
  • 多进程模式（–workers 或 Gunicorn + Uvicorn）。
  • 启用 HTTPS（–ssl-keyfile 和 –ssl-certfile）。
  • 调整超时和日志级别优化性能。