跳转至

Uvicorn 教程

Uvicorn 是一个基于 ASGI（Asynchronous Server Gateway Interface）的超快速的 Python Web 服务器，常用于运行像 FastAPI 或 Starlette 这样的异步框架。本文将从基础介绍到高级用法，带你逐步深入了解 Uvicorn。

目录

  1. Uvicorn 简介
  2. 安装 Uvicorn
  3. 基本用法
  4. 配置与启动选项
  5. 热重载与开发环境配置
  6. 日志与监控
  7. 使用 HTTPS
  8. 生产环境最佳实践
  9. 高级配置
  10. 常见问题与优化

1. Uvicorn 简介

Uvicorn 是基于 ASGI 规范的高性能 Web 服务器，旨在处理异步操作。相比传统的 WSGI（如 Gunicorn），Uvicorn 更适合异步框架，并且支持 WebSockets、Server-Sent Events 等实时通信协议。

主要特点：

  • 高性能，适合生产环境
  • 支持异步框架（如 FastAPI, Starlette）
  • 兼容 WebSockets
  • 支持 HTTP/2 和 HTTPS
  • 高度可配置

2. 安装 Uvicorn

Uvicorn 可以通过 pip 安装：

pip install uvicorn

如果要安装带有性能优化的版本，可以使用如下命令：

pip install "uvicorn[standard]"

此版本包含更多的依赖，如 uvloop、httptools、websockets 等，能够进一步提高性能。

3. 基本用法

安装完 Uvicorn 后，启动一个简单的 ASGI 应用非常简单。我们先创建一个简单的 FastAPI 应用，然后通过 Uvicorn 来运行它。

创建 app.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"Hello": "World"}

启动 Uvicorn：

uvicorn app:app --reload

解释：

  • app:app：第一个 app 是文件名，第二个 app 是 FastAPI 应用实例。
  • --reload：开启自动热重载，当文件发生变化时，服务器会自动重启。

打开浏览器访问 http://127.0.0.1:8000，可以看到返回的 JSON 响应。

4. 配置与启动选项

Uvicorn 提供了很多可配置的启动选项，你可以在命令行中传递不同的参数来修改其行为：

常用参数：

  • --host：指定服务器监听的 IP 地址，默认为 127.0.0.1（本地），如果你想让其他设备访问，可以使用 0.0.0.0。
  • --port：指定监听端口，默认是 8000。
  • --reload：启用代码修改后的自动重启（适合开发环境）。
  • --workers：启动多个进程（适合生产环境）。
  • --log-level：设置日志级别（可选值：critical, error, warning, info, debug, trace），默认是 info。

示例：

uvicorn app:app --host 0.0.0.0 --port 8080 --log-level debug

这样，服务器会在 0.0.0.0:8080 启动，并使用 debug 日志级别。

5. 热重载与开发环境配置

在开发时，我们可以使用 --reload 参数，这样每次代码有变动时，Uvicorn 会自动重新启动服务器。

uvicorn app:app --reload

这是开发环境的常用配置，但请注意在生产环境中禁用这个选项。

6. 日志与监控

Uvicorn 通过 --log-level 和 --access-log 参数提供了详细的日志配置：

  • --log-level：指定日志级别，如 info, debug, error 等。
  • --access-log：默认启用，记录每个请求的访问日志。可以通过 --no-access-log 禁用。

你也可以将日志输出到文件中。使用 uvicorn --log-config 指定自定义的日志配置文件。

7. 使用 HTTPS

要启用 HTTPS，需要指定 SSL 证书和私钥文件：

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

其中，key.pem 是私钥文件，cert.pem 是 SSL 证书文件。

8. 生产环境最佳实践

在生产环境中，通常会结合 Gunicorn 和 Uvicorn 来提高稳定性和性能。Gunicorn 是一个 WSGI HTTP 服务器，可以管理多个 Uvicorn 进程。

安装 Gunicorn：

pip install gunicorn

然后结合 Uvicorn 使用：

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

参数解释： - -w 4：启动 4 个工作进程。 - -k uvicorn.workers.UvicornWorker：指定 Uvicorn 作为 Gunicorn 的工作进程类型。

这样，你可以同时享受到 Gunicorn 的进程管理和 Uvicorn 的异步处理能力。

9. 高级配置

Uvicorn 支持更多的高级选项，通过命令行或配置文件实现：

  • --loop：选择事件循环类型（asyncio 或 uvloop），默认是 auto。
  • --http：选择 HTTP 协议实现（如 h11 或 httptools）。
  • --timeout-keep-alive：设置连接保持活跃的超时时间，默认是 5 秒。

如果你希望将配置集中化管理，可以创建一个 .ini 文件或者使用 Python 代码构建配置。

10. 常见问题与优化

1. 为什么不使用 --reload 在生产环境中？

--reload 适合开发环境，生产中使用会导致性能下降和不必要的重启行为。

2. 如何提高 Uvicorn 的性能？

  • 使用 uvloop 提高事件循环的性能。
  • 使用 Gunicorn 配合多进程。
  • 在高并发场景下，调整 workers 和 threads 的数量以优化 CPU 资源利用。

总结

Uvicorn 是一个轻量、灵活且强大的 ASGI 服务器，非常适合现代异步 Python Web 应用的部署。从入门到生产，它都提供了丰富的配置选项和高性能特性。希望这篇教程能帮助你掌握从基础到高级的 Uvicorn 使用技巧！