asgi-server
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUvicorn ASGI Server
Uvicorn ASGI 服务器
Overview
概述
Uvicorn is a lightning-fast ASGI server implementation for Python. Built on top of and , 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 extras), WebSockets, and lifespan protocol events out of the box.
uvloophttptools[standard]Key characteristics:
- High-throughput async I/O powered by (when installed)
uvloop - 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 extras bundle includes , , (for reload), and .
[standard]uvloophttptoolswatchfileswebsocketsUvicorn 是一款为Python打造的极速ASGI服务器实现。它基于和构建,为FastAPI、Starlette等异步Web框架及其他兼容ASGI的应用提供了轻量、高性能的运行接口。Uvicorn默认支持HTTP/1.1、HTTP/2(需安装扩展包)、WebSocket,以及生命周期协议事件。
uvloophttptools[standard]核心特性:
- 由(安装后启用)驱动的高吞吐量异步I/O
uvloop - 对FastAPI和Starlette应用的一等支持
- 开发流程中内置热重载功能
- 生产部署可用的多进程工作模式
- SSL/TLS终止支持
- WebSocket与HTTP/2协议支持
- 处理ASGI生命周期事件以实现启动/关闭逻辑
安装包含生产级性能的标准扩展包:
bash
uv add "uvicorn[standard]"[standard]uvloophttptoolswatchfileswebsocketsDevelopment Mode
开发模式
Run a FastAPI application in development with automatic code reloading:
bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Integrate with uv for virtual environment management:
bash
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Restrict reload watching to specific directories to avoid unnecessary restarts:
bash
uvicorn app.main:app --reload --reload-dir src --reload-dir templatesThe flag uses (if installed via ) for efficient filesystem monitoring. Avoid using in production -- it is intended only for development.
--reloadwatchfiles[standard]--reload启动带自动代码重载的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--reloadwatchfiles[standard]--reloadCLI Options Reference
CLI选项参考
| Option | Default | Description |
|---|---|---|
| | Bind address. Use |
| | Port number to listen on. |
| off | Enable auto-reload on code changes. |
| | Directory to watch for changes (repeatable). |
| | Number of worker processes (multiprocess mode). |
| | Log verbosity: |
| on | Enable access log. Use |
| off | Trust |
| | Comma-separated IPs trusted for proxy headers. Use |
| none | Path to SSL private key file. |
| none | Path to SSL certificate file. |
| 选项 | 默认值 | 描述 |
|---|---|---|
| | 绑定地址。使用 |
| | 监听端口号。 |
| 关闭 | 启用代码变更自动重载。 |
| | 监控变更的目录(可重复指定)。 |
| | 工作进程数量(多进程模式)。 |
| | 日志详细程度: |
| 开启 | 启用访问日志。使用 |
| 关闭 | 信任 |
| | 信任代理头信息的IP列表(逗号分隔)。使用 |
| 无 | SSL私钥文件路径。 |
| 无 | 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 () when using so that uvicorn can re-import the module on changes. Pass the application object directly only when reload is disabled.
"app.main:app"reload=True在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",
)当使用时,需将应用以导入字符串()传入,以便Uvicorn在变更时重新导入模块。仅当禁用重载时,才可直接传入应用对象。
reload=True"app.main:app"Programmatic Configuration Object
程序化配置对象
For more control, use and :
uvicorn.Configuvicorn.Serverpython
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.Configuvicorn.Serverpython
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 flag when the application is created by a factory function rather than being a module-level object:
--factorybash
uvicorn app.main:create_app --factoryThe factory function must be a zero-argument callable that returns an ASGI application:
python
undefined当应用由工厂函数而非模块级对象创建时,使用标志:
--factorybash
uvicorn app.main:create_app --factory工厂函数必须是无参数的可调用对象,返回ASGI应用:
python
undefinedapp/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 flag to spawn multiple processes:
--workersbash
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000Each worker runs its own event loop and handles requests independently. The flag cannot be combined with .
--workers--reloadCalculate the optimal worker count based on available CPU cores:
workers = (2 * CPU_CORES) + 1For 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.
在多核机器上进行生产部署时,使用标志启动多个进程:
--workersbash
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 debugAvailable levels in increasing verbosity: , , , , , .
criticalerrorwarninginfodebugtrace通过CLI或程序化配置设置日志级别:
bash
uvicorn app.main:app --log-level debug可用级别(按详细程度递增):、、、、、。
criticalerrorwarninginfodebugtraceAccess 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-logCustom 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 on the CLI for externalized log configuration.
--log-config提供自定义日志配置字典以实现结构化或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上通过传入YAML或JSON文件路径,实现外部化日志配置。
--log-configLifespan 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
生命周期模式
| Mode | Behavior |
|---|---|
| Always send lifespan events. Fail if the app does not handle them. |
| Never send lifespan events. |
| Send lifespan events if the app supports them; ignore otherwise. Default. |
Set via CLI:
bash
uvicorn app.main:app --lifespan auto| 模式 | 行为 |
|---|---|
| 始终发送生命周期事件。如果应用不处理这些事件则失败。 |
| 从不发送生命周期事件。 |
| 如果应用支持则发送生命周期事件;否则忽略。默认值。 |
通过CLI设置:
bash
uvicorn app.main:app --lifespan autoFastAPI 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 extras and providing SSL certificates:
[standard]bash
uvicorn app.main:app --ssl-keyfile key.pem --ssl-certfile cert.pem --http h2HTTP/2 requires TLS. For local development, generate self-signed certificates with or .
mkcertopenssl安装扩展包并提供SSL证书,以启用HTTP/2支持:
[standard]bash
uvicorn app.main:app --ssl-keyfile key.pem --ssl-certfile cert.pem --http h2HTTP/2需要TLS。对于本地开发,可使用或生成自签名证书。
mkcertopensslWebSockets
WebSocket
WebSocket support is included by default when or is installed (bundled in ). Select the implementation explicitly:
websocketswsproto[standard]bash
uvicorn app.main:app --ws websockets当安装或(包含在扩展包中)时,默认支持WebSocket。可显式选择实现方式:
websocketswsproto[standard]bash
uvicorn app.main:app --ws websocketsor
或
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
undefinedUse 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 443For 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- tells Uvicorn to trust
--proxy-headersandX-Forwarded-Forheaders.X-Forwarded-Proto - restricts which upstream IPs are trusted. Set to
--forwarded-allow-ipsonly in fully trusted network environments.*
Without these flags, will always report the proxy's IP rather than the actual client IP.
request.client.host当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- 告知Uvicorn信任
--proxy-headers和X-Forwarded-For头信息。X-Forwarded-Proto - 限制可信任的上游IP。仅在完全可信的网络环境中设置为
--forwarded-allow-ips。*
如果没有这些标志,将始终报告代理的IP,而非实际客户端IP。
request.client.hostResource 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| Option | Default | Description |
|---|---|---|
| none | Maximum number of concurrent connections before rejecting new ones. |
| none | Maximum requests per worker before restarting (guards against memory leaks). |
| | Seconds to wait for a new request on a keep-alive connection. |
| | Seconds to wait for graceful shutdown of a worker. |
| | Maximum length of the pending connections queue. |
Set in production to guard against gradual memory leaks. Combine with so that restarting one worker does not drop all traffic.
--limit-max-requests--workers在生产环境中控制连接和请求限制,防止资源耗尽:
bash
uvicorn app.main:app \
--limit-concurrency 100 \
--limit-max-requests 10000 \
--timeout-keep-alive 5 \
--host 0.0.0.0 --port 8000| 选项 | 默认值 | 描述 |
|---|---|---|
| 无 | 拒绝新连接前的最大并发连接数。 |
| 无 | 每个工作进程在重启前处理的最大请求数(防止内存泄漏)。 |
| | 在长连接上等待新请求的秒数。 |
| | 等待工作进程优雅关闭的秒数。 |
| | 待处理连接队列的最大长度。 |
在生产环境中设置以防止渐进式内存泄漏。结合使用,以便重启一个工作进程不会中断所有流量。
--limit-max-requests--workersCommon Patterns
常见模式
Integration with uv
与uv集成
Run Uvicorn through uv to ensure the correct virtual environment and dependencies:
bash
undefined通过uv运行Uvicorn,确保使用正确的虚拟环境和依赖:
bash
undefinedDevelopment
开发环境
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
undefineduv run uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000
undefinedEnvironment-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.sockEnsure 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 and 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.
--reload-include--reload-exclude在开发期间,限制触发重载的文件扩展名,避免因无关文件变更导致重启:
bash
uvicorn app.main:app --reload --reload-include "*.py" --reload-include "*.yaml" --reload-exclude "test_*"--reload-include--reload-excludeCross-References
交叉引用
- For Docker deployment, consult the skill.
docker-build - For FastAPI app configuration, consult the skill.
fastapi - For production deployment patterns with Gunicorn and Nginx, consult the deployment reference.
- For dependency management with uv, consult the skill.
uv
- 有关Docker部署,请参考技能。
docker-build - 有关FastAPI应用配置,请参考技能。
fastapi - 有关使用Gunicorn和Nginx的生产部署模式,请参考部署参考文档。
- 有关使用uv进行依赖管理,请参考技能。
uv