mcpField
U
uvicorn

uvicorn

github.com/slanycukr开发263 次安装53 周前更新
代码仓库

关于 uvicorn

这是运行 Uvicorn 的技能指南，面向使用 Python 异步 Web 框架的开发者。内容涵盖从自动重载到生产部署的常见配置，包括多进程、SSL 和 Unix 套接字。

主要功能

  1. 01通过命令行运行 ASGI 应用
  2. 02配置主机、端口、日志和重载
  3. 03使用应用工厂和 Python API
  4. 04配置工作进程与 SSL

适用场景

  1. 01开发时启动 FastAPI 应用
  2. 02以多个工作进程运行 ASGI 应用
  3. 03通过 HTTPS 或 Unix 套接字提供服务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/slanycukr/riot-api-project --skill uvicorn

安装后在 Claude Code 中输入/uvicorn确认已加载。

详细介绍

Uvicorn 技能指南

Uvicorn 是一个速度极快的 ASGI 服务实现，使用 uvloop 和 httptools。它是现代 Python 异步 Web 框架的首选服务。

快速开始

基本用法
# 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

常见模式

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"}

uvicorn main:app --reload
3. 应用工厂模式
# main.py
from fastapi import FastAPI

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

app = create_app()

uvicorn --factory main:create_app
4. 以编程方式控制服务
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())
5. 使用环境变量进行配置
export UVICORN_HOST="0.0.0.0"
export UVICORN_PORT="8000"
export UVICORN_RELOAD="true"
uvicorn main:app

生产环境部署

多进程工作进程
# Use multiple worker processes
uvicorn main:app --workers 4

# Note: Can't use --reload with --workers
Gunicorn + Uvicorn
# Install gunicorn
pip install gunicorn

# Run with Gunicorn process manager
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
HTTPS/SSL
uvicorn main:app --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem
Unix 套接字
uvicorn main:app --uds /tmp/uvicorn.sock

配置选项

常用 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：将 app 视为应用工厂

Docker 集成

Dockerfile
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

故障排除

常见问题
  1. 端口已被占用：更换端口或终止现有进程
  2. 找不到模块：检查 PYTHONPATH 或使用 --app-dir
  3. 重新加载不起作用：确保使用 --reload-dir 监视正确的目录
  4. 工作进程数量：生产环境使用 --workers，避免与 --reload 同时使用
调试模式
uvicorn main:app --reload --log-level debug
健康检查
@app.get("/health")
async def health():
    return {"status": "healthy"}

评论

支持 Markdown