Uvicorn ASGI 服务器¶

一句话概述：Uvicorn 是一个闪电般快速的 ASGI 服务器，用于运行 Python 异步 Web 应用（FastAPI、Starlette、Django Channels 等）。

核心知识点速查表¶

知识点	说明
为什么要学 Uvicorn	见对应章节
核心概念	见对应章节
安装配置	见对应章节
快速上手	见对应章节
进阶用法	见对应章节
常见问题	见对应章节
参考资源	见对应章节

为什么要学 Uvicorn¶

Uvicorn 是一个闪电般快速的 ASGI 服务器，用于运行 Python 异步 Web 应用（FastAPI、Starlette、Django Channels 等）。它基于 uvloop 和 httptools，是 Python 生态中性能最优的 ASGI 服务器之一。理解 Uvicorn 的配置和部署对于将 Python Web 应用推向生产环境至关重要。

核心概念¶

概念	白话解释	用途
ASGI	异步服务器网关接口	Python 异步 Web 标准
Worker	工作进程	处理请求的进程
uvloop	高性能事件循环	替代 asyncio 默认事件循环
Reload	热重载	代码修改后自动重启
SSL	安全连接	HTTPS 支持
Lifespan	生命周期	启动/关闭事件

安装配置¶

pip install uvicorn[standard]
# standard 包含 uvloop, httptools, watchfiles

快速上手¶

# 基本启动
uvicorn main:app

# 开发模式（热重载）
uvicorn main:app --reload --port 8000

# 生产模式（多 Worker）
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# 常用参数
uvicorn main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --log-level info \
  --access-log \
  --proxy-headers \
  --forwarded-allow-ips "*"

编程式启动¶

import uvicorn

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True,
        workers=4,
        log_level="info",
    )

进阶用法¶

SSL/HTTPS¶

uvicorn main:app \
  --ssl-keyfile ./key.pem \
  --ssl-certfile ./cert.pem \
  --port 443

与 Gunicorn 配合（生产推荐）¶

# Gunicorn 管理进程，Uvicorn 作为 Worker 类
pip install gunicorn

gunicorn main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile - \
  --timeout 120

自定义日志¶

import uvicorn

log_config = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "default": {
            "fmt": "%(asctime)s %(levelname)s %(message)s",
            "datefmt": "%Y-%m-%d %H:%M:%S",
        },
    },
    "handlers": {
        "default": {
            "formatter": "default",
            "class": "logging.StreamHandler",
            "stream": "ext://sys.stderr",
        },
    },
    "loggers": {
        "uvicorn": {"handlers": ["default"], "level": "INFO"},
    },
}

uvicorn.run("main:app", log_config=log_config)

Docker 部署¶

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

systemd 服务¶

# /etc/systemd/system/myapp.service
[Unit]
Description=My FastAPI App
After=network.target

[Service]
User=www-data
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

常见问题¶

Q: Worker 数量设多少？¶

推荐 2 * CPU核心数 + 1。4 核 CPU 设 9 个 Worker。

Q: 与 Hypercorn、Daphne 对比？¶

Uvicorn：最快、最流行、FastAPI 默认
Hypercorn：支持 HTTP/2 和 HTTP/3
Daphne：Django Channels 默认

Q: 热重载在生产中能用吗？¶

不建议。--reload 会监控文件变化，带来额外开销。生产环境使用 --workers 多进程模式。

参考资源¶

GitHub：https://github.com/encode/uvicorn
文档：https://www.uvicorn.org/
部署指南：https://www.uvicorn.org/deployment/
ASGI 规范：https://asgi.readthedocs.io/