asgi-server

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Uvicorn ASGI Server

Uvicorn ASGI 服务器

Overview

概述

Uvicorn is a lightning-fast ASGI server implementation for Python. Built on top of
uvloop
and
httptools
, it provides a minimal, high-performance interface for running asynchronous web frameworks such as FastAPI, Starlette, and other ASGI-compatible applications. Uvicorn supports HTTP/1.1, HTTP/2 (via the
[standard]
extras), WebSockets, and lifespan protocol events out of the box.
Key characteristics:
  • High-throughput async I/O powered by
    uvloop
    (when installed)
  • First-class support for FastAPI and Starlette applications
  • Built-in hot reload for development workflows
  • Multiprocess worker mode for production deployments
  • SSL/TLS termination support
  • WebSocket and HTTP/2 protocol support
  • ASGI lifespan event handling for startup/shutdown logic
Install with standard extras for production-grade performance:
bash
uv add "uvicorn[standard]"
The
[standard]
extras bundle includes
uvloop
,
httptools
,
watchfiles
(for reload), and
websockets
.
Uvicorn 是一款为Python打造的极速ASGI服务器实现。它基于
uvloop
httptools
构建,为FastAPI、Starlette等异步Web框架及其他兼容ASGI的应用提供了轻量、高性能的运行接口。Uvicorn默认支持HTTP/1.1、HTTP/2(需安装
[standard]
扩展包)、WebSocket,以及生命周期协议事件。
核心特性:
  • uvloop
    (安装后启用)驱动的高吞吐量异步I/O
  • 对FastAPI和Starlette应用的一等支持
  • 开发流程中内置热重载功能
  • 生产部署可用的多进程工作模式
  • SSL/TLS终止支持
  • WebSocket与HTTP/2协议支持
  • 处理ASGI生命周期事件以实现启动/关闭逻辑
安装包含生产级性能的标准扩展包:
bash
uv add "uvicorn[standard]"
[standard]
扩展包包含
uvloop
httptools
watchfiles
(用于重载)和
websockets

Development Mode

开发模式

Run a FastAPI application in development with automatic code reloading:
bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Integrate with uv for virtual environment management:
bash
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Restrict reload watching to specific directories to avoid unnecessary restarts:
bash
uvicorn app.main:app --reload --reload-dir src --reload-dir templates
The
--reload
flag uses
watchfiles
(if installed via
[standard]
) for efficient filesystem monitoring. Avoid using
--reload
in production -- it is intended only for development.
启动带自动代码重载的FastAPI应用开发服务:
bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
与uv集成以管理虚拟环境:
bash
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
限制重载监控的特定目录,避免不必要的重启:
bash
uvicorn app.main:app --reload --reload-dir src --reload-dir templates
--reload
标志使用
watchfiles
(通过
[standard]
安装后)实现高效文件系统监控。请勿在生产环境中使用
--reload
——它仅适用于开发场景。

CLI Options Reference

CLI选项参考

OptionDefaultDescription
--host
127.0.0.1
Bind address. Use
0.0.0.0
to accept external connections.
--port
8000
Port number to listen on.
--reload
offEnable auto-reload on code changes.
--reload-dir
.
Directory to watch for changes (repeatable).
--workers
1
Number of worker processes (multiprocess mode).
--log-level
info
Log verbosity:
critical
,
error
,
warning
,
info
,
debug
,
trace
.
--access-log
onEnable access log. Use
--no-access-log
to disable.
--proxy-headers
offTrust
X-Forwarded-For
and
X-Forwarded-Proto
headers.
--forwarded-allow-ips
127.0.0.1
Comma-separated IPs trusted for proxy headers. Use
*
for all.
--ssl-keyfile
nonePath to SSL private key file.
--ssl-certfile
nonePath to SSL certificate file.
选项默认值描述
--host
127.0.0.1
绑定地址。使用
0.0.0.0
以接受外部连接。
--port
8000
监听端口号。
--reload
关闭启用代码变更自动重载。
--reload-dir
.
监控变更的目录(可重复指定)。
--workers
1
工作进程数量(多进程模式)。
--log-level
info
日志详细程度:
critical
error
warning
info
debug
trace
--access-log
开启启用访问日志。使用
--no-access-log
关闭。
--proxy-headers
关闭信任
X-Forwarded-For
X-Forwarded-Proto
头信息。
--forwarded-allow-ips
127.0.0.1
信任代理头信息的IP列表(逗号分隔)。使用
*
允许所有IP。
--ssl-keyfile
SSL私钥文件路径。
--ssl-certfile
SSL证书文件路径。

Programmatic Usage

程序化使用

Run Uvicorn programmatically within a Python script. This pattern is useful for debugging, testing, and IDE-based launch configurations.
python
import uvicorn

from app.main import app

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        reload=True,
        log_level="info",
    )
Pass the application as an import string (
"app.main:app"
) when using
reload=True
so that uvicorn can re-import the module on changes. Pass the application object directly only when reload is disabled.
在Python脚本中程序化运行Uvicorn。这种模式适用于调试、测试和基于IDE的启动配置。
python
import uvicorn

from app.main import app

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        reload=True,
        log_level="info",
    )
当使用
reload=True
时,需将应用以导入字符串(
"app.main:app"
)传入,以便Uvicorn在变更时重新导入模块。仅当禁用重载时,才可直接传入应用对象。

Programmatic Configuration Object

程序化配置对象

For more control, use
uvicorn.Config
and
uvicorn.Server
:
python
import uvicorn

config = uvicorn.Config(
    "app.main:app",
    host="0.0.0.0",
    port=8000,
    log_level="info",
    access_log=True,
    workers=1,
)
server = uvicorn.Server(config)
server.run()
This approach is useful when embedding uvicorn inside a larger application or when fine-grained control over server lifecycle is required.
如需更多控制,可使用
uvicorn.Config
uvicorn.Server
python
import uvicorn

config = uvicorn.Config(
    "app.main:app",
    host="0.0.0.0",
    port=8000,
    log_level="info",
    access_log=True,
    workers=1,
)
server = uvicorn.Server(config)
server.run()
这种方法适用于将Uvicorn嵌入更大的应用中,或需要对服务器生命周期进行精细控制的场景。

Factory Pattern

工厂模式

Use the
--factory
flag when the application is created by a factory function rather than being a module-level object:
bash
uvicorn app.main:create_app --factory
The factory function must be a zero-argument callable that returns an ASGI application:
python
undefined
当应用由工厂函数而非模块级对象创建时,使用
--factory
标志:
bash
uvicorn app.main:create_app --factory
工厂函数必须是无参数的可调用对象,返回ASGI应用:
python
undefined

app/main.py

app/main.py

from fastapi import FastAPI
def create_app() -> FastAPI: app = FastAPI(title="My API")
# Register routes, middleware, event handlers
from app.api import router
app.include_router(router)

return app

The factory pattern is preferred for larger applications because it avoids import side effects and enables cleaner testing and configuration.
from fastapi import FastAPI
def create_app() -> FastAPI: app = FastAPI(title="My API")
# 注册路由、中间件、事件处理器
from app.api import router
app.include_router(router)

return app

对于大型应用,工厂模式更受青睐,因为它避免了导入副作用,使测试和配置更清晰。

Worker Configuration

工作进程配置

For production deployments on multi-core machines, use the
--workers
flag to spawn multiple processes:
bash
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000
Each worker runs its own event loop and handles requests independently. The
--workers
flag cannot be combined with
--reload
.
Calculate the optimal worker count based on available CPU cores:
workers = (2 * CPU_CORES) + 1
For I/O-bound applications (typical for FastAPI), this formula provides a good starting point. Tune based on actual load testing results.
For more robust multiprocess deployments, consider using Gunicorn with Uvicorn workers. Consult the deployment reference for Gunicorn integration patterns.
在多核机器上进行生产部署时,使用
--workers
标志启动多个进程:
bash
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000
每个工作进程运行独立的事件循环,独立处理请求。
--workers
标志不能与
--reload
组合使用。
根据可用CPU核心数计算最优工作进程数:
workers = (2 * CPU核心数) + 1
对于I/O密集型应用(FastAPI的典型场景),此公式提供了良好的起点。可根据实际负载测试结果进行调整。
如需更稳健的多进程部署,可考虑将Gunicorn与Uvicorn工作进程结合使用。有关Gunicorn集成模式,请参考部署参考文档

Logging Configuration

日志配置

Basic Log Levels

基础日志级别

Set the log level via CLI or programmatic configuration:
bash
uvicorn app.main:app --log-level debug
Available levels in increasing verbosity:
critical
,
error
,
warning
,
info
,
debug
,
trace
.
通过CLI或程序化配置设置日志级别:
bash
uvicorn app.main:app --log-level debug
可用级别(按详细程度递增):
critical
error
warning
info
debug
trace

Access Log Control

访问日志控制

Disable access logs in production when a reverse proxy already handles request logging:
bash
uvicorn app.main:app --no-access-log
当反向代理已处理请求日志时,在生产环境中禁用访问日志:
bash
uvicorn app.main:app --no-access-log

Custom Log Configuration

自定义日志配置

Provide a custom logging configuration dictionary for structured or JSON logging:
python
import uvicorn

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

uvicorn.run("app.main:app", host="0.0.0.0", port=8000, log_config=log_config)
Pass a YAML or JSON file path to
--log-config
on the CLI for externalized log configuration.
提供自定义日志配置字典以实现结构化或JSON日志:
python
import uvicorn

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

uvicorn.run("app.main:app", host="0.0.0.0", port=8000, log_config=log_config)
在CLI上通过
--log-config
传入YAML或JSON文件路径,实现外部化日志配置。

Lifespan Handling

生命周期处理

Uvicorn supports the ASGI lifespan protocol, which allows applications to run initialization and teardown logic on server start and stop.
Uvicorn支持ASGI生命周期协议,允许应用在服务器启动和停止时运行初始化和清理逻辑。

Lifespan Modes

生命周期模式

ModeBehavior
on
Always send lifespan events. Fail if the app does not handle them.
off
Never send lifespan events.
auto
Send lifespan events if the app supports them; ignore otherwise. Default.
Set via CLI:
bash
uvicorn app.main:app --lifespan auto
模式行为
on
始终发送生命周期事件。如果应用不处理这些事件则失败。
off
从不发送生命周期事件。
auto
如果应用支持则发送生命周期事件;否则忽略。默认值。
通过CLI设置:
bash
uvicorn app.main:app --lifespan auto

FastAPI Lifespan Context Manager

FastAPI生命周期上下文管理器

Define startup and shutdown logic with the FastAPI lifespan context manager:
python
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator

from fastapi import FastAPI


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    # Startup: initialize resources
    app.state.db_pool = await create_db_pool()
    app.state.redis = await create_redis_client()
    yield
    # Shutdown: release resources
    await app.state.db_pool.close()
    await app.state.redis.close()


app = FastAPI(lifespan=lifespan)
Use lifespan for database connection pools, cache clients, ML model loading, and other resources that require explicit initialization and cleanup.
使用FastAPI生命周期上下文管理器定义启动和关闭逻辑:
python
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator

from fastapi import FastAPI


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    # 启动:初始化资源
    app.state.db_pool = await create_db_pool()
    app.state.redis = await create_redis_client()
    yield
    # 关闭:释放资源
    await app.state.db_pool.close()
    await app.state.redis.close()


app = FastAPI(lifespan=lifespan)
生命周期适用于数据库连接池、缓存客户端、ML模型加载等需要显式初始化和清理的资源。

HTTP/2 and WebSocket Support

HTTP/2与WebSocket支持

HTTP/2

HTTP/2

Enable HTTP/2 support by installing the
[standard]
extras and providing SSL certificates:
bash
uvicorn app.main:app --ssl-keyfile key.pem --ssl-certfile cert.pem --http h2
HTTP/2 requires TLS. For local development, generate self-signed certificates with
mkcert
or
openssl
.
安装
[standard]
扩展包并提供SSL证书,以启用HTTP/2支持:
bash
uvicorn app.main:app --ssl-keyfile key.pem --ssl-certfile cert.pem --http h2
HTTP/2需要TLS。对于本地开发,可使用
mkcert
openssl
生成自签名证书。

WebSockets

WebSocket

WebSocket support is included by default when
websockets
or
wsproto
is installed (bundled in
[standard]
). Select the implementation explicitly:
bash
uvicorn app.main:app --ws websockets
当安装
websockets
wsproto
(包含在
[standard]
扩展包中)时,默认支持WebSocket。可显式选择实现方式:
bash
uvicorn app.main:app --ws websockets

or

uvicorn app.main:app --ws wsproto

No additional configuration is required -- FastAPI `WebSocket` endpoints work automatically.
uvicorn app.main:app --ws wsproto

无需额外配置——FastAPI的`WebSocket`端点可自动工作。

Protocol Selection

协议选择

Select the HTTP implementation explicitly when needed:
bash
undefined
必要时可显式选择HTTP实现:
bash
undefined

Use httptools (default with [standard], fastest)

使用httptools([standard]默认,速度最快)

uvicorn app.main:app --http httptools
uvicorn app.main:app --http httptools

Use h11 (pure Python, no C dependencies)

使用h11(纯Python,无C依赖)

uvicorn app.main:app --http h11
uvicorn app.main:app --http h11

Use h2 for HTTP/2

使用h2实现HTTP/2

uvicorn app.main:app --http h2 --ssl-keyfile key.pem --ssl-certfile cert.pem

The `httptools` implementation is recommended for production due to its superior throughput. The `h11` implementation is useful when C extensions are unavailable or when debugging protocol-level issues.
uvicorn app.main:app --http h2 --ssl-keyfile key.pem --ssl-certfile cert.pem

推荐在生产环境中使用`httptools`实现,因为它具有更高的吞吐量。当无法使用C扩展或需要调试协议级问题时,`h11`实现非常有用。

SSL/TLS Configuration

SSL/TLS配置

Terminate TLS directly at Uvicorn when not running behind a TLS-terminating reverse proxy:
bash
uvicorn app.main:app \
    --ssl-keyfile /etc/ssl/private/server.key \
    --ssl-certfile /etc/ssl/certs/server.crt \
    --ssl-ca-certs /etc/ssl/certs/ca-bundle.crt \
    --host 0.0.0.0 \
    --port 443
For most production deployments, terminate TLS at the reverse proxy (Nginx, Caddy, or a cloud load balancer) and run Uvicorn on plain HTTP behind it. Consult the deployment reference for Nginx TLS termination patterns.
当不运行在TLS终止反向代理之后时,直接在Uvicorn终止TLS:
bash
uvicorn app.main:app \
    --ssl-keyfile /etc/ssl/private/server.key \
    --ssl-certfile /etc/ssl/certs/server.crt \
    --ssl-ca-certs /etc/ssl/certs/ca-bundle.crt \
    --host 0.0.0.0 \
    --port 443
对于大多数生产部署,建议在反向代理(Nginx、Caddy或云负载均衡器)处终止TLS,然后在其后方运行HTTP协议的Uvicorn。有关Nginx TLS终止模式,请参考部署参考文档

Running Behind a Reverse Proxy

反向代理后运行

When Uvicorn runs behind Nginx, Caddy, or a cloud load balancer, enable proxy header forwarding to preserve client IP addresses and protocol information:
bash
uvicorn app.main:app \
    --proxy-headers \
    --forwarded-allow-ips "127.0.0.1,10.0.0.0/8" \
    --host 0.0.0.0 \
    --port 8000
  • --proxy-headers
    tells Uvicorn to trust
    X-Forwarded-For
    and
    X-Forwarded-Proto
    headers.
  • --forwarded-allow-ips
    restricts which upstream IPs are trusted. Set to
    *
    only in fully trusted network environments.
Without these flags,
request.client.host
will always report the proxy's IP rather than the actual client IP.
当Uvicorn运行在Nginx、Caddy或云负载均衡器之后时,启用代理头转发以保留客户端IP地址和协议信息:
bash
uvicorn app.main:app \
    --proxy-headers \
    --forwarded-allow-ips "127.0.0.1,10.0.0.0/8" \
    --host 0.0.0.0 \
    --port 8000
  • --proxy-headers
    告知Uvicorn信任
    X-Forwarded-For
    X-Forwarded-Proto
    头信息。
  • --forwarded-allow-ips
    限制可信任的上游IP。仅在完全可信的网络环境中设置为
    *
如果没有这些标志,
request.client.host
将始终报告代理的IP,而非实际客户端IP。

Resource Limits

资源限制

Control connection and request limits to prevent resource exhaustion in production:
bash
uvicorn app.main:app \
    --limit-concurrency 100 \
    --limit-max-requests 10000 \
    --timeout-keep-alive 5 \
    --host 0.0.0.0 --port 8000
OptionDefaultDescription
--limit-concurrency
noneMaximum number of concurrent connections before rejecting new ones.
--limit-max-requests
noneMaximum requests per worker before restarting (guards against memory leaks).
--timeout-keep-alive
5
Seconds to wait for a new request on a keep-alive connection.
--timeout-notify
30
Seconds to wait for graceful shutdown of a worker.
--backlog
2048
Maximum length of the pending connections queue.
Set
--limit-max-requests
in production to guard against gradual memory leaks. Combine with
--workers
so that restarting one worker does not drop all traffic.

在生产环境中控制连接和请求限制,防止资源耗尽:
bash
uvicorn app.main:app \
    --limit-concurrency 100 \
    --limit-max-requests 10000 \
    --timeout-keep-alive 5 \
    --host 0.0.0.0 --port 8000
选项默认值描述
--limit-concurrency
拒绝新连接前的最大并发连接数。
--limit-max-requests
每个工作进程在重启前处理的最大请求数(防止内存泄漏)。
--timeout-keep-alive
5
在长连接上等待新请求的秒数。
--timeout-notify
30
等待工作进程优雅关闭的秒数。
--backlog
2048
待处理连接队列的最大长度。
在生产环境中设置
--limit-max-requests
以防止渐进式内存泄漏。结合
--workers
使用,以便重启一个工作进程不会中断所有流量。

Common Patterns

常见模式

Integration with uv

与uv集成

Run Uvicorn through uv to ensure the correct virtual environment and dependencies:
bash
undefined
通过uv运行Uvicorn,确保使用正确的虚拟环境和依赖:
bash
undefined

Development

开发环境

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Production

生产环境

uv run uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000
undefined
uv run uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000
undefined

Environment-Based Configuration

基于环境的配置

Use environment variables or pydantic-settings to drive server configuration:
python
import uvicorn
from app.config import settings

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host=settings.server_host,
        port=settings.server_port,
        reload=settings.debug,
        workers=settings.server_workers,
        log_level=settings.log_level,
    )
使用环境变量或pydantic-settings驱动服务器配置:
python
import uvicorn
from app.config import settings

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host=settings.server_host,
        port=settings.server_port,
        reload=settings.debug,
        workers=settings.server_workers,
        log_level=settings.log_level,
    )

Health Check Endpoint

健康检查端点

Pair Uvicorn with a health check endpoint for load balancer and orchestrator integration:
python
@app.get("/health")
async def health_check():
    return {"status": "healthy"}
将Uvicorn与健康检查端点配对,用于负载均衡器和编排器集成:
python
@app.get("/health")
async def health_check():
    return {"status": "healthy"}

Binding to a Unix Socket

绑定到Unix套接字

Bind Uvicorn to a Unix domain socket instead of a TCP port for communication with a local reverse proxy. This eliminates TCP overhead:
bash
uvicorn app.main:app --uds /tmp/uvicorn.sock
Ensure the reverse proxy (Nginx or Caddy) is configured to proxy to the same socket path. Unix sockets are not accessible over the network and are only suitable when the proxy runs on the same host.
将Uvicorn绑定到Unix域套接字而非TCP端口,与本地反向代理通信。这消除了TCP开销:
bash
uvicorn app.main:app --uds /tmp/uvicorn.sock
确保反向代理(Nginx或Caddy)配置为代理到相同的套接字路径。Unix套接字无法通过网络访问,仅适用于代理与服务器运行在同一主机的场景。

Restricting Reload File Types

限制重载文件类型

During development, limit the file extensions that trigger a reload to avoid restarting on irrelevant file changes:
bash
uvicorn app.main:app --reload --reload-include "*.py" --reload-include "*.yaml" --reload-exclude "test_*"
The
--reload-include
and
--reload-exclude
options accept glob patterns and can be repeated. This is particularly useful in projects with large static asset directories or generated files that should not trigger server restarts.
在开发期间,限制触发重载的文件扩展名,避免因无关文件变更导致重启:
bash
uvicorn app.main:app --reload --reload-include "*.py" --reload-include "*.yaml" --reload-exclude "test_*"
--reload-include
--reload-exclude
选项接受glob模式,可重复指定。这在包含大型静态资源目录或生成文件的项目中特别有用,这些文件不应触发服务器重启。

Cross-References

交叉引用

  • For Docker deployment, consult the
    docker-build
    skill.
  • For FastAPI app configuration, consult the
    fastapi
    skill.
  • For production deployment patterns with Gunicorn and Nginx, consult the deployment reference.
  • For dependency management with uv, consult the
    uv
    skill.
  • 有关Docker部署,请参考
    docker-build
    技能。
  • 有关FastAPI应用配置,请参考
    fastapi
    技能。
  • 有关使用Gunicorn和Nginx的生产部署模式,请参考部署参考文档
  • 有关使用uv进行依赖管理,请参考
    uv
    技能。