Uvicorn 是一个基于 uvloop 和 httptools 构建的 ASGI（异步服务器网关接口）服务器，专为 FastAPI 等异步 Python Web 框架设计。

基本概念 #

1. ASGI 服务器：Uvicorn 实现了 ASGI 规范，支持异步 Python Web 应用
2. 高性能：使用 uvloop（基于 libuv）提供快速的事件循环
3. 轻量级：专注于提供核心的 ASGI 服务器功能
4. 兼容性：支持 HTTP/1.1 和 WebSockets

安装 #

pip install uvicorn[standard]  # 包含可选依赖项，性能更好
# 或
pip install uvicorn  # 最小安装

基本使用 #

运行 FastAPI 应用 #

假设有一个 main.py 文件，其中包含 FastAPI 应用实例 app：

uvicorn main:app --reload

• main: Python 模块名（文件名去掉 .py）
• app: FastAPI 应用实例变量名
• --reload: 开发时启用自动重载

常用命令行选项 #

选项	说明
--host	绑定主机 (默认: 127.0.0.1)
--port	绑定端口 (默认: 8000)
--reload	开发时自动重载
--workers	工作进程数
--log-level	日志级别 (debug, info, warning, error, critical)
--ssl-keyfile	SSL 密钥文件
--ssl-certfile	SSL 证书文件
--ws	WebSocket 实现 (auto, websockets, wsproto)

程序化运行 #

# 导入 uvicorn
import uvicorn

# 仅在直接运行本文件时执行
if __name__ == "__main__":
    # 运行 main.py 文件中的 app 实例，监听 0.0.0.0:8000，自动重载
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

配置选项详解 #

性能相关 #

1. 工作进程数 (--workers):
   • 默认为 1
   • 对于 CPU 密集型应用，可以设置为 CPU 核心数
   • 对于 I/O 密集型应用，可以设置更多

uvicorn main:app --workers 4

2. 事件循环 (--loop):
   • auto (默认): 自动选择
   • uvloop: 高性能事件循环 (基于 libuv)
   • asyncio: 标准 asyncio 事件循环

安全相关 #

1. HTTPS 支持:

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

2. 绑定地址:

uvicorn main:app --host 0.0.0.0  # 允许外部访问

开发相关 #

1. 自动重载 (--reload):

   • 监视代码变化并自动重启
   • 仅用于开发环境

2. 调试模式:

   • 设置 --debug 标志
   • 或设置 --log-level debug

生产部署建议 #

1. 使用进程管理器:
   • 如 Gunicorn + Uvicorn 工作进程
   • 提供更好的稳定性和进程管理

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

2. 反向代理:

   • 使用 Nginx 或 Apache 作为反向代理
   • 处理静态文件、SSL 终止等

3. 性能调优:

   • 根据应用类型调整工作进程数
   • 监控和调整连接限制

日志配置 #

# 导入 logging 模块
import logging
# 从 uvicorn.config 导入 LOGGING_CONFIG
from uvicorn.config import LOGGING_CONFIG
# 修改日志格式
LOGGING_CONFIG["formatters"]["default"]["fmt"] = "%(asctime)s - %(levelname)s - %(message)s"
# 导入 uvicorn
import uvicorn
# 运行 main.py 文件中的 app 实例，使用自定义日志配置
uvicorn.run("main:app", log_config=LOGGING_CONFIG)

与 FastAPI 的关系 #

• Uvicorn 是 FastAPI 官方推荐的 ASGI 服务器
• FastAPI 应用通过 ASGI 接口与 Uvicorn 通信
• Uvicorn 负责处理网络协议、并发等底层细节

常见问题解决 #

1. 端口占用:

   • 检查是否有其他进程占用了端口
   • 使用 --port 指定其他端口

2. 性能瓶颈:

   • 增加工作进程数
   • 检查应用是否有同步阻塞代码

3. WebSocket 问题:

   • 确保使用 --ws websockets 选项
   • 检查反向代理是否支持 WebSocket

Uvicorn 是构建现代 Python Web 应用的重要组件，特别适合与 FastAPI、Starlette 等异步框架配合使用。