【Python】Uvicorn：Python 异步 ASGI 服务器详解

Uvicorn 是一个为 Python 设计的 ASGI（异步服务器网关接口）Web 服务器。它填补了 Python 在异步框架中缺乏一个最小化低层次服务器/应用接口的空白。Uvicorn 支持 HTTP/1.1 和 WebSockets，是构建现代异步Web应用的强大工具。

⭕️宇宙起点

🎬 什么是 Uvicorn？

Uvicorn 是一个轻量级、高性能的 ASGI（Asynchronous Server Gateway Interface） 服务器，专为支持 Python 异步框架（如 FastAPI 和 Starlette）而设计。与传统的 WSGI 服务器（如 Gunicorn）不同，Uvicorn 旨在提供对异步 Web 框架的完全支持，并在性能和灵活性方面进行了大量优化。

🔨 Uvicorn 的主要功能和特性

• 高性能：Uvicorn 使用 uvloop 作为默认的事件循环和 httptools 进行 HTTP 解析，因此比传统的 Python 服务器更快。
• 支持多种协议：支持 HTTP 和 WebSocket 协议，并可配置 ASGI 2 或 ASGI 3 接口。
• 配置灵活：支持通过命令行参数、环境变量或配置文件进行详细的服务器配置。

📦 Uvicorn 的常用启动参数

在使用 Uvicorn 启动 ASGI 应用时，通常通过命令行传递各种参数以控制其行为。下面列出了几个常用的启动参数及其用途：
参数作用示例

--host

指定绑定的主机地址

--host 127.0.0.1

--port

指定端口号

--port 8000

--workers

指定工作进程数

--workers 4

--reload

启用自动重载，在开发时自动检测文件变动并重启服务器

--reload

--log-level

日志等级（

info

、

debug

、

error

）

--log-level debug

--ssl-keyfile

SSL 密钥文件路径

--ssl-keyfile ./path/to/key.pem

--ssl-certfile

SSL 证书文件路径

--ssl-certfile ./path/to/cert.pem

--backlog

设置连接请求的最大等待队列数

--backlog 2048

--limit-max-requests

限制单个进程在重启前可处理的最大请求数

--limit-max-requests 1000

这些参数可以灵活地组合使用，根据需要配置 Uvicorn 的运行行为。特别是对于生产环境，可以搭配

--workers

参数来启动多个进程，提高并发处理能力。

♨️ 示例：使用

uvicorn.run

启动 ASGI 应用

Uvicorn 既可以从命令行启动，也可以通过 Python 代码进行启动。以下是几种不同的启动方式：

**1）使用

uvicorn.run()

启动**

import uvicorn

asyncdefapp(scope, receive, send):assert scope['type']=='http'await send({'type':'http.response.start','status':200,'headers':[[b'content-type',b'text/plain'],],})await send({'type':'http.response.body','body':b'Hello, Uvicorn!',})if __name__ =="__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info")

**2）使用

Config

和

Server

实例**

当需要更细粒度的控制时，可以使用

Config

和

Server

实例：

import uvicorn

asyncdefapp(scope, receive, send):assert scope['type']=='http'await send({'type':'http.response.start','status':200,'headers':[[b'content-type',b'text/plain'],],})await send({'type':'http.response.body','body':b'Hello, Uvicorn!',})if __name__ =="__main__":
    config = uvicorn.Config("main:app", host="127.0.0.1", port=5000, log_level="info")
    server = uvicorn.Server(config)
    server.run()

3）异步环境中启动 Uvicorn

如果要在已有的异步事件循环中启动，可以使用

uvicorn.Server.serve()

：

import asyncio
import uvicorn

asyncdefapp(scope, receive, send):assert scope['type']=='http'await send({'type':'http.response.start','status':200,'headers':[[b'content-type',b'text/plain'],],})await send({'type':'http.response.body','body':b'Hello, Uvicorn!',})asyncdefmain():
    config = uvicorn.Config("main:app", host="127.0.0.1", port=5000, log_level="info")
    server = uvicorn.Server(config)await server.serve()if __name__ =="__main__":
    asyncio.run(main())

⚙️ 运行 Uvicorn 的高级配置

Uvicorn 提供了多种高级配置选项来满足不同应用的需求，包括 HTTP 流量控制、SSL 设置、资源限制等。常用配置如下：
配置选项描述默认值

--limit-concurrency

限制最大并发连接数，超出时返回 HTTP 503

None

--timeout-keep-alive

Keep-Alive 超时时间，超过该时间未收到请求则断开连接

5

--timeout-graceful-shutdown

优雅关闭服务器的最大等待时间

None

--ssl-version

SSL 协议版本（参考标准库

ssl

模块）

17

--log-config

日志配置文件路径

None

--ws-ping-interval

WebSocket 心跳包发送间隔时间

20.0

--ws-ping-timeout

WebSocket 心跳包超时时间

20.0

这些参数可以在开发和生产环境中进行不同的调整，以提升服务器的响应速度和安全性。

🔧 使用 Gunicorn 部署 Uvicorn

在生产环境中，通常推荐使用 Gunicorn 搭配 Uvicorn 的工作进程模式来部署。这样可以充分利用多进程的优势，并且享有 Gunicorn 稳定的进程管理功能。

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

此命令会启动 4 个工作进程，并使用

UvicornWorker

管理 ASGI 应用的多进程环境。

📥 下载地址

Uvicorn 最新版 下载地址

💬 结语

Uvicorn 是一个功能强大、配置灵活且易于使用的异步 Web 服务器，非常适合现代 Python 异步框架的开发和部署。通过合理配置和结合 Gunicorn，可以充分利用其高性能和稳定性来处理各种 Web 请求。

📒 参考文献

• Uvicorn 官网
• Uvicorn GitHub仓库