Uvicorn 技能指南

Uvicorn 是一个基于 uvloop 和 httptools 构建的极速 ASGI 服务器实现。它是现代 Python 异步 Web 框架的首选服务器。

快速开始

基本用法

# 运行 ASGI 应用
uv run uvicorn main:app

# 指定主机/端口
uv run uvicorn main:app --host 0.0.0.0 --port 8000

# 开发模式，带自动重载
uv run uvicorn main:app --reload

常用模式

1. 简单的 ASGI 应用程序

# main.py
async def app(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, World!',
    })

2. FastAPI 应用程序

# main.py
from fastapi import FastAPI

app = FastAPI()

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

uv run uvicorn main:app --reload

3. 应用工厂模式

# main.py
from fastapi import FastAPI

def create_app():
    app = FastAPI()
    # 配置应用
    return app

app = create_app()

uv run uvicorn --factory main:create_app

4. 编程式服务器控制

import uvicorn

# 简单运行
if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

import asyncio
import uvicorn

async def main():
    config = uvicorn.Config("main:app", port=5000, log_level="info")
    server = uvicorn.Server(config)
    await server.serve()

if __name__ == "__main__":
    asyncio.run(main())

5. 使用环境变量配置

export UVICORN_HOST="0.0.0.0"
export UVICORN_PORT="8000"
export UVICORN_RELOAD="true"
uv run uvicorn main:app

生产部署

多进程工作模式

# 使用多个工作进程
uv run uvicorn main:app --workers 4

# 注意：不能同时使用 --reload 和 --workers

Gunicorn + Uvicorn

# 安装 gunicorn
uv add gunicorn

# 使用 Gunicorn 进程管理器运行
uv run gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

HTTPS/SSL

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

Unix 套接字

uv run uvicorn main:app --uds /tmp/uvicorn.sock

配置选项

常用 CLI 参数

uv run uvicorn main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --reload \
  --reload-dir ./app \
  --log-level info \
  --access-log \
  --workers 4

关键设置

--host: 绑定主机（默认: 127.0.0.1）
--port: 绑定端口（默认: 8000）
--reload: 为开发启用自动重载
--workers: 工作进程数量
--log-level: 日志级别（critical, error, warning, info, debug）
--access-log: 启用访问日志
--factory: 将应用视为应用工厂

Docker 集成

Dockerfile

FROM python:3.12-slim
WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install -r requirements.txt

# 复制应用程序
COPY . .

# 使用 uvicorn 运行
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

带热重载的 Docker Compose

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - UVICORN_RELOAD=true
    volumes:
      - .:/app
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload

故障排除

常见问题

端口已被占用：更改端口或终止现有进程
模块未找到：检查 PYTHONPATH 或使用 --app-dir
重载不工作：确保使用 --reload-dir 监视正确的目录
工作进程数量：生产环境使用 --workers，避免与 --reload 同时使用

调试模式

uv run uvicorn main:app --reload --log-level debug

健康检查

@app.get("/health")
async def health():
    return {"status": "healthy"}