Uvicorn 入门指南：安装、配置与使用 – wiki基地

作者： /

Uvicorn 入门指南：安装、配置与使用

Uvicorn 是一个闪电般快速的 ASGI（Asynchronous Server Gateway Interface）服务器，基于 uvloop 和 httptools 构建。它旨在成为 Python Web 框架（如 FastAPI、Starlette 和 Quart）的生产级服务器。与传统的 WSGI 服务器（如 Gunicorn）相比，Uvicorn 利用异步 I/O 提供了显著的性能提升，特别是在处理大量并发连接和长轮询/WebSocket 应用时。

本文将深入探讨 Uvicorn 的各个方面，包括安装、配置选项、使用方法、与其他工具的集成以及常见问题的解决方案。无论你是 ASGI 的新手还是希望优化现有应用的性能，本指南都将为你提供全面的指导。

1. 为什么选择 Uvicorn？

在深入了解 Uvicorn 的细节之前，让我们先了解一下为什么它在众多 ASGI 服务器中脱颖而出：

  • 高性能： Uvicorn 的核心是 uvloop，它是 libuv 的一个快速、直接替代品（libuv 是 Node.js 性能的关键）。uvloop 使用 Cython 编写，使其能够与底层操作系统事件循环进行高效交互。此外，Uvicorn 使用 httptools，一个快速的 HTTP 协议解析器，进一步提升了性能。

  • ASGI 标准支持： Uvicorn 完全符合 ASGI 规范，这意味着它可以与任何遵循 ASGI 标准的 Web 框架无缝协作。这提供了极大的灵活性，你可以轻松切换框架而无需更改服务器配置。

  • 易于使用： Uvicorn 的命令行界面（CLI）非常简单直观，即使是初学者也能快速上手。它提供了丰富的配置选项，可以满足各种应用场景的需求。

  • 生产就绪： Uvicorn 被广泛认为是生产级 ASGI 服务器，许多大型项目都在使用它。它具有高度的稳定性和可靠性，可以处理高负载和复杂的应用。

  • 活跃的社区和维护： Uvicorn 拥有一个活跃的社区和积极的维护团队，这意味着你可以获得及时的支持和更新。

2. 安装 Uvicorn

安装 Uvicorn 非常简单，可以使用 pip 或你喜欢的 Python 包管理器：

bash
pip install uvicorn

如果你计划使用 Uvicorn 的某些高级功能（如 WebSocket 支持），建议安装“标准”版本的 Uvicorn：

bash
pip install uvicorn[standard]

这将安装额外的依赖项，如 websockets 和 httptools。

验证安装：

安装完成后，你可以通过在终端中运行以下命令来验证 Uvicorn 是否正确安装：

bash
uvicorn --version

如果安装成功，你将看到 Uvicorn 的版本号。

3. 基本使用

Uvicorn 的基本用法非常简单。假设你有一个名为 main.py 的 ASGI 应用，其中包含一个名为 app 的 ASGI 可调用对象：

“`python

main.py

from fastapi import FastAPI

app = FastAPI()

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

你可以使用以下命令启动 Uvicorn 服务器：

bash
uvicorn main:app --reload

让我们分解一下这个命令：

  • uvicorn: 这是 Uvicorn 的命令行入口点。
  • main:app: 这是你的 ASGI 应用的导入路径。main 是 Python 模块的名称（不带 .py 扩展名），app 是模块中 ASGI 可调用对象的名称。
  • --reload: 这是一个非常有用的开发选项。启用后，Uvicorn 将监视你的代码文件，并在检测到更改时自动重新加载服务器。这极大地提高了开发效率，因为你无需手动重启服务器。

访问你的应用：

默认情况下，Uvicorn 将在 http://127.0.0.1:8000 上启动服务器。你可以在浏览器中打开此地址，或者使用 curl 等工具来访问你的应用。

4. 常用配置选项

Uvicorn 提供了许多配置选项，允许你根据需要自定义服务器的行为。以下是一些最常用的选项：

  • --host: 指定服务器监听的 IP 地址。默认值为 127.0.0.1（仅限本地访问）。要允许来自任何 IP 地址的连接，请使用 --host 0.0.0.0。

  • --port: 指定服务器监听的端口。默认值为 8000。

  • --reload: 启用自动代码重载（如前所述）。

  • --workers: 指定要启动的工作进程数。默认情况下，Uvicorn 将启动一个工作进程。增加工作进程数可以提高服务器处理并发请求的能力，但也会增加服务器的资源消耗。通常，建议将工作进程数设置为 CPU 核心数。

  • --log-level: 设置日志级别。可选值包括 debug、info、warning、error 和 critical。默认值为 info。

  • --proxy-headers: 当 Uvicorn 运行在反向代理（如 Nginx）后面时，启用此选项以信任 X-Forwarded-For 和 X-Forwarded-Proto 等代理标头。

  • --ssl-keyfile 和 --ssl-certfile: 如果要启用 HTTPS，请使用这些选项指定 SSL 密钥和证书文件的路径。

  • --lifespan: 控制应用程序的启动和关闭事件。选项有auto(默认),on和off。

  • --interface: 指定使用的 ASGI 接口，可以是auto, asgi3, 或者asgi2。

示例：

以下命令将启动 Uvicorn 服务器，监听所有 IP 地址的 8080 端口，启用自动代码重载，并启动 4 个工作进程：

bash
uvicorn main:app --host 0.0.0.0 --port 8080 --reload --workers 4

5. 高级配置

除了上述常用选项外，Uvicorn 还提供了一些高级配置选项，用于更精细地控制服务器行为：

  • HTTP/2 支持： Uvicorn 支持 HTTP/2 协议，可以提供更好的性能和更低的延迟。要启用 HTTP/2，你需要安装 h2 包：

    bash
    pip install h2

    然后，在启动 Uvicorn 时使用 --http2 选项：

    bash
    uvicorn main:app --http2

  • WebSocket 支持： Uvicorn 通过 websockets 包提供 WebSocket 支持。如果你安装了 uvicorn[standard]，则已经包含了此依赖项。

    要使用 WebSocket，你的 ASGI 应用需要处理 WebSocket 连接。例如，使用 FastAPI：

    “`python

    main.py

    from fastapi import FastAPI, WebSocket

    app = FastAPI()

    @app.websocket(“/ws”)
    async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
    data = await websocket.receive_text()
    await websocket.send_text(f”Message text was: {data}”)
    “`

  • 自定义 ASGI 应用工厂： 如果你的 ASGI 应用不是一个简单的可调用对象，而是一个工厂函数（例如，用于创建具有特定配置的应用实例），你可以使用 --factory 选项来指定工厂函数的导入路径：

    “`python

    main.py

    from fastapi import FastAPI

    def create_app(config: dict):
    app = FastAPI()
    # … 根据 config 配置 app …
    return app

    app = create_app({“debug”: True}) # 示例用法，通常不会这样直接调用
    “`

    启动 Uvicorn 时：

    bash
    uvicorn main:create_app --factory

  • 配置事件循环:
    Uvicorn 默认使用uvloop,如果不可用会退化到asyncio。可以通过--loop选项手动指定：
    uvicorn main:app --loop asyncio

6. 与 Gunicorn 集成

虽然 Uvicorn 本身就是一个功能强大的 ASGI 服务器，但在某些情况下，你可能希望将它与 Gunicorn 集成。Gunicorn 是一个成熟的 WSGI 服务器，具有进程管理、信号处理和守护进程化等功能。

通过将 Uvicorn 作为 Gunicorn 的工作类，你可以结合两者的优势：Gunicorn 提供进程管理和稳定性，而 Uvicorn 提供 ASGI 的高性能。

要将 Uvicorn 与 Gunicorn 集成，你需要安装 Gunicorn：

bash
pip install gunicorn

然后，使用 uvicorn.workers.UvicornWorker 作为 Gunicorn 的工作类启动 Gunicorn：

bash
gunicorn main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8000

在这个命令中：

  • main:app: 你的 ASGI 应用的导入路径。
  • -k uvicorn.workers.UvicornWorker: 指定 Uvicorn 工作类。
  • -w 4: 启动 4 个 Uvicorn 工作进程。
  • -b 0.0.0.0:8000: 绑定到所有 IP 地址的 8000 端口。

注意： 当使用 Gunicorn 时，Uvicorn 的 --reload 选项将不起作用，因为 Gunicorn 会处理进程管理和代码重载。

如果你需要使用h11和websockets之外的协议，需要使用UvicornH11Worker或者UvicornWebsocketsWorker。

7. 部署

将 Uvicorn 应用部署到生产环境时，有几个重要的注意事项：

  • 反向代理： 强烈建议在 Uvicorn 前面使用反向代理服务器（如 Nginx 或 Apache）。反向代理可以处理静态文件、SSL 终止、负载均衡和请求路由等任务，从而提高应用的性能和安全性。

  • 进程管理器： 使用进程管理器（如 systemd 或 Supervisor）来管理 Uvicorn 进程。进程管理器可以确保 Uvicorn 在服务器重启后自动启动，并在发生故障时自动重启。

  • 安全性： 确保你的服务器和应用都已正确配置和保护。这包括使用强密码、定期更新软件包、配置防火墙以及遵循安全最佳实践。

  • 监控： 使用监控工具（如 Prometheus 或 Grafana）来监控你的应用的性能和健康状况。这可以帮助你及时发现和解决问题。

示例 Nginx 配置：

以下是一个简单的 Nginx 配置示例，用于将请求代理到运行在本地 8000 端口的 Uvicorn 应用：

“`nginx
server {
listen 80;
server_name example.com;

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

}
“`

8. 常见问题与解决方案

  • ImportError: cannot import name 'app'： 这通常表示 Uvicorn 无法找到你的 ASGI 应用。请确保你提供了正确的导入路径（module:attribute），并且你的应用文件和可调用对象名称拼写正确。

  • Address already in use： 这表示你尝试使用的端口已被其他进程占用。你可以使用 --port 选项指定一个不同的端口，或者停止占用该端口的进程。

  • Connection refused： 这通常表示 Uvicorn 服务器未运行，或者你的防火墙阻止了连接。请确保 Uvicorn 已启动，并且你的防火墙允许来自你尝试连接的 IP 地址的流量。

  • 性能问题： 如果你的应用性能不佳，请考虑以下因素：

    • 工作进程数： 确保你启动了足够的工作进程来处理并发请求。
    • 数据库连接： 使用连接池来管理数据库连接，避免频繁创建和销毁连接。
    • 异步代码： 确保你的代码充分利用了异步 I/O，避免阻塞操作。
    • 资源限制： 检查服务器的 CPU、内存和网络资源是否充足。

  • 代码重载问题： 如果 --reload 选项无法正常工作，请确保你已安装了 watchgod 包（它是 Uvicorn 的可选依赖项）。 如果您使用的是容器化环境（例如 Docker），则代码重新加载可能无法按预期工作，因为文件系统更改可能不会传播到容器中。

9. 总结

Uvicorn 是一个强大且易于使用的 ASGI 服务器，为 Python Web 应用提供了出色的性能和可靠性。通过本文的详细介绍，你应该已经掌握了 Uvicorn 的安装、配置、使用、与其他工具的集成以及部署方面的知识。

无论你是构建新的 ASGI 应用还是优化现有应用，Uvicorn 都是一个值得考虑的优秀选择。它与 FastAPI、Starlette 和 Quart 等现代 Web 框架的无缝集成，以及对 HTTP/2 和 WebSocket 的支持，使其成为构建高性能、可扩展的 Web 应用的理想选择。

希望这篇指南对你有所帮助！如果你有任何问题或反馈，请随时提出。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部