Uvicorn：Python ASGI Web 服务器-马育民老师

# 介绍
**Uvicorn** 是一款**高性能、轻量级 Python ASGI Web 服务器**。
名称由来：UV（Ultra-Violet 紫外线）+ unicorn（独角兽），寓意极速异步服务器。

- 作者：Tom Christie（Starlette、ASGI 规范发起者）
- 协议：**ASGI（异步服务器网关接口）**，对标同步世界的 WSGI
- 底层核心依赖：
  - `uvloop`：Cython 实现的高性能事件循环，替代 Python 标准 `asyncio`
  - `httptools`：C 实现的 HTTP 解析器（Node.js 同款解析内核）

### 适用框架

FastAPI、Starlette、Django Channels、Litestar 等异步 Web 框架。

### ASGI vs WSGI 区别

| 类型 | 同步/异步 | 长连接(WebSocket) | 适用服务器 |
|------|-----------|------------------|------------|
| WSGI | 纯同步 | ❌ 原生不支持 | Gunicorn、uWSGI |
| ASGI | 支持async/await | ✅ WebSocket、SSE、长轮询 | Uvicorn、Hypercorn、Daphne |

简单理解：
WSGI 只能一次性处理短 HTTP 请求；
**ASGI 支持持续双向数据流，天然适配实时通信。**

# 特性

1. **原生异步高并发**
单进程单事件循环，可以同时维持成千上万连接，I/O 等待时不会阻塞。非常适合接口服务、实时推送、WebSocket 聊天。

2. **支持 HTTP/1.1 + WebSocket**
原生支持双向长连接，是开发实时应用首选。

3. **开发友好：代码热重载 `--reload`**
文件变更自动重启服务，仅限本地调试，**禁止生产使用**。

4. **同时兼容异步/同步接口**
可以运行 `async def` 接口，也能正常执行普通同步函数（内部自动线程池调度）。

5. **支持多进程、Unix Socket、SSL HTTPS、反向代理头部解析**
6. **轻量、启动速度快，配置简洁**

> 局限：目前官方尚不原生支持 HTTP/2、HTTP/3；如需 HTTP/3 可以选择 Hypercorn。

# 安装
```bash
# 最简安装（不含uvloop、httptools，性能较低）
pip install uvicorn

# 推荐完整版，包含性能依赖【生产必选】
pip install uvicorn[standard]
```
要求 Python ≥3.10（新版本uvicorn）

# 基础使用方式

### 1. 命令行启动（最常用）
文件 `main.py`
```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def hello():
    return {"msg":"hello uvicorn"}
```

启动命令格式：`uvicorn 模块名:实例名`
```bash
# 基础启动，仅本机访问
uvicorn main:app

# 允许外部访问，端口8000
uvicorn main:app --host 0.0.0.0 --port 8000

# 开发模式：开启热重载
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

### 2. 代码内编程启动（`uvicorn.run()`）
```python
# main.py
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"hello": "uvicorn program start"}

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=False,
        workers=1
    )
```
> ⚠️ 坑：Windows下，多进程模式 `workers>1` 不能搭配 `reload=True`，会报错。

# 常用参数详解
```bash
uvicorn main:app \
--host 0.0.0.0 \                # 监听地址，0.0.0.0允许外网访问
--port 8000 \                   # 端口
--workers 4 \                   # 工作进程数量（多进程多核利用）
--loop uvloop \                 # 事件循环，可选 uvloop / asyncio
--log-level info \              # 日志级别 critical/error/warning/info/debug
--access-log \                  # 开启访问日志（生产可关闭提升性能）
--timeout-keep-alive 10 \       # HTTP长连接空闲超时
--graceful-timeout 30 \         # 优雅关闭等待时长
--limit-concurrency 2000 \      # 限制最大并发连接，防止雪崩
--proxy-headers \               # 解析Nginx反向代理传递的真实客户端IP
--ssl-certfile cert.pem \
--ssl-keyfile key.pem           # HTTPS证书
```

##### 参数说明
1. `--reload`
开发专用；启动额外监控进程，文件变动重启worker；**生产环境必须关闭！严重损耗性能。**
2. `--workers N`
uvicorn 内置多进程模式。
- Linux/macOS：推荐 `CPU核心数 ~ 2*核心数`
- Windows：uvicorn 的多进程稳定性较差，Windows生产环境建议**单worker**，或者改用 Gunicorn。
> 注意：多进程之间内存隔离，全局变量不共享！

3. `--loop`
- `uvloop`（默认）：性能最高
- `asyncio`：兼容性模式，部分第三方库不兼容uvloop时使用

## 六、部署模式（重点区分开发 / 生产）
### 模式1：本地开发（简单）
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

### 模式2：生产方案A —— 原生uvicorn多进程（简单部署）
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```
优点：一条命令搞定；缺点：进程监控、平滑重启能力弱。

### 模式3：生产方案B —— Gunicorn + UvicornWorker【业界标准推荐】
**Gunicorn 作为主进程管理器，管理多个 Uvicorn 异步 worker**
```bash
pip install gunicorn
# 启动
gunicorn main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000
```
- `-w 4`：4个worker进程
- `-k uvicorn.workers.UvicornWorker`：使用uvicorn异步worker（支持ASGI/WebSocket）
✅ 优势：
成熟进程管理、自动重启崩溃进程、支持平滑重启、日志管理完善；Linux服务器首选。

> 架构标准链路：
> Client → Nginx(反向代理、ssl、限流) → Gunicorn → UvicornWorker → FastAPI应用

## 七、Uvicorn 常见坑 & 最佳实践
### 1. 不要生产开启 `--reload`
自动重载会产生额外进程开销，存在安全风险。

### 2. 同步阻塞代码会拖垮整个事件循环
```python
# ❌ 错误！同步耗时代码阻塞事件循环
import time
@app.get("/block")
async def test():
    time.sleep(5)

# ✅ 正确：使用异步sleep
import asyncio
@app.get("/ok")
async def test():
    await asyncio.sleep(5)
```
如果必须调用同步阻塞IO（数据库、请求），使用 `asyncio.to_thread()` 放到线程运行。

### 3. 多进程环境全局状态不共享
`--workers>1` 每个进程独立内存，不要依赖内存缓存；改用Redis等外部缓存。

### 4. Docker容器部署建议
容器中**推荐单worker**，由K8s/Docker Compose横向扩容，不要在容器内部开启多workers。

### 5. 反向代理必须开启 `--proxy-headers`
搭配Nginx时启用，才能正确获取客户端真实IP、请求协议。

## 八、同类 ASGI 服务器横向对比
1. **Uvicorn**
性能最优，生态最好，FastAPI官方默认；仅支持HTTP/1.1 + WebSocket。
2. **Hypercorn**
支持 HTTP/2、HTTP/3；性能略低于uvicorn。
3. **Daphne**
Django Channels官方配套，纯Python解析，性能偏弱。

## 九、常见问题
### Q：Uvicorn 和 Gunicorn 是什么关系？
- Gunicorn **原生是WSGI同步服务器，不支持ASGI**
- 通过 `UvicornWorker` 适配器，Gunicorn可以调度uvicorn进程，实现「进程管理+异步处理」组合。

### Q：单进程uvicorn能利用多核CPU吗？
不能！asyncio事件循环**单线程运行**，一个worker只能占用一个CPU核心。
想要利用多核，必须启动多个worker进程（`--workers` 或gunicorn托管）。

## 十、极简生产标准启动模板（Linux）
```bash
# 搭配nginx反向代理
gunicorn main:app \
-w 3 \
-k uvicorn.workers.UvicornWorker \
--bind 127.0.0.1:8000 \
--proxy-headers \
--log-level warning
```

如果你需要，我可以给你一份配套的 **Nginx 配置文件 + systemd 服务托管脚本**，直接用于服务器上线部署。

原文出处：http://www.malaoshi.top/show_1GW3mzWNFdjM.html