必须设--workers的三种情况：CPU利用率低但QPS卡顿、存在无法避免的同步阻塞调用、GPU推理服务显存闲置；数值需据物理核心数、内存/GPU显存容量及请求模式综合确定，忌套用“2×CPU+1”公式。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
什么时候必须设 --workers？
单进程 Uvicorn 靠 async/await 就能处理数千 I/O 请求，加 --workers 不是默认动作，而是应对明确瓶颈：
- 压测时 htop 显示 CPU 利用率持续低于 60%，但 QPS 卡住、延迟飙升
- 代码里存在无法避免的同步阻塞，比如 time.sleep(1)、requests.get()、pandas.read_csv() 或未封装进 run_in_executor 的 numpy 计算
- 部署 GPU 推理服务（如 LLM 前处理），单 worker 只能串行发 batch，显存和算力大量闲置
--workers 数值怎么定？别套公式
“2×CPU 核心数 + 1” 在真实生产中经常翻车，因为没考虑资源约束和负载类型：
- 查物理核心数：nproc 输出为 4，--workers 4 是安全起点；超过 8 后吞吐增长通常趋缓
- 看内存/GPU 显存：每个 worker 是独立 Python 进程，加载一次大模型就占一份内存；RTX 3060（12GB）实测最多稳住 4 个 worker
- 观察请求模式：流量极不均匀（例如每分钟集中来 100 个大 batch），worker 数宁少勿多，避免冷启动和空转开销
- 混合型负载（如 FastAPI + 同步 DB 查询 + 小量 CPU 计算），8 核机器推荐从 --workers 10 起步，上线后用 ps aux | grep uvicorn 和压测验证
设了 --workers 却只看到 1 个进程？常见失效原因
启动后 ps aux | grep uvicorn 只返回 1 行？大概率掉进这些坑：
- 同时启用了 --reload：二者互斥，--reload 强制降级为单进程，且 fork 失败时静默回退
- 用 Gunicorn 做前置但漏写 -k uvicorn.workers.UvicornWorker：Gunicorn 默认起的是同步 worker，async def 路由直接报 TypeError: 'coroutine' object is not callable
- Docker 容器未配 CPU quota：docker run --cpus=2 却设 --workers 4，内核调度失灵，部分 worker 启动即被 kill
- Windows 下 spawn 方式导致模块顶层代码重复执行，触发初始化冲突（如重复创建 event loop）
多 worker 下共享资源必须重设计
每个 worker 进程完全隔离，模块级全局变量、数据库连接池、Redis 客户端都不是共享的：
- lifespan 的 startup 和 shutdown 会在每个 worker 里各执行一次 —— 别在这里初始化全局 cache 或发通知
- 内存缓存（如 dict 或 @lru_cache）在多 worker 下必然不一致，必须换成 Redis 或其他跨进程存储
- 数据库连接池要按 worker 数倍增配置，否则容易出现连接耗尽（psycopg2.OperationalError: too many clients already）
