uvicorn

用途

Uvicorn 是一个 ASGI 服务器实现，使用 uvloop 和 httptools，用于运行现代 Python 异步 Web 框架。资料将其描述为快速、生产就绪的异步框架服务器。

主要能力

运行 ASGI 应用，例如通过 uvicorn main:app 启动。
支持指定主机与端口：uvicorn main:app --host 0.0.0.0 --port 8000。
开发模式下使用自动重载：uvicorn main:app --reload。
支持应用工厂模式，以 uvicorn --factory main:create_app 方式运行。
支持通过代码以编程方式控制服务器，可使用 uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)，或使用 uvicorn.Config 与 uvicorn.Server 配合 await server.serve()。
支持通过环境变量配置，例如 UVICORN_HOST、UVICORN_PORT、UVICORN_RELOAD。
生产部署支持多进程工作模式（--workers 4）、Gunicorn + UvicornWorker（gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker）、HTTPS/SSL（--ssl-keyfile、--ssl-certfile）以及 Unix Socket（--uds /tmp/uvicorn.sock）。
提供 Docker 集成示例，包括 Dockerfile 与 Docker Compose 热重载配置。

使用方式

基础运行：

# Run ASGI app
uvicorn main:app

# With host/port
uvicorn main:app --host 0.0.0.0 --port 8000

# Development with auto-reload
uvicorn main:app --reload

简单 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!',
    })

FastAPI 应用示例：

# main.py
from fastapi import FastAPI

app = FastAPI()

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

uvicorn main:app --reload

应用工厂模式示例：

# main.py
from fastapi import FastAPI

def create_app():
    app = FastAPI()
    # Configure app
    return app

app = create_app()

uvicorn --factory main:create_app

编程方式控制服务器示例：

import uvicorn

# Simple run
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())

环境变量配置示例：

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

常用 CLI 参数示例：

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。

生产部署示例：

# Use multiple worker processes
uvicorn main:app --workers 4

# Note: Can't use --reload with --workers

# Install gunicorn
pip install gunicorn

# Run with Gunicorn process manager
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

HTTPS/SSL 与 Unix Socket：

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

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

Docker 集成示例：

FROM python:3.12-slim
WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application
COPY . .

# Run with 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

适用场景

运行基于 ASGI 的 Python 异步 Web 应用与框架。
开发阶段需要自动重载的本地调试。
生产环境中的多进程部署，或借助 Gunicorn 作为进程管理器运行。
需要 HTTPS/SSL 或 Unix Socket 的服务部署。
容器化部署（Docker 与 Docker Compose）。

限制与注意事项

资料明确说明 --reload 不能与 --workers 同时使用。
常见问题包括：端口已被占用、模块找不到（检查 PYTHONPATH 或使用 --app-dir）、重载不生效（用 --reload-dir 确保监视正确目录）、worker 数量（生产使用 --workers，避免与 --reload 并用）。
调试模式可使用 uvicorn main:app --reload --log-level debug。
其他信息（如收费、价格、平台支持范围等）暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项