uvicorn

ASGI 服务器 uvicorn：main:app、CLI 与 uvicorn.run、workers 与 reload、反向代理与生产部署；链回 FastAPI 与官方手册。

uvicorn 是常用的 ASGI 服务器：监听端口、接受连接，把 HTTP/WebSocket 交给 ASGI 可调用对象（如 FastAPI 的 app）。应用逻辑在框架层；uvicorn 管 进程、套接字、协议。与 WSGI 服务器（gunicorn sync worker 等）的区分见 Web 服务与常用框架。

pip install uvicorn

何时用 uvicorn

场景	建议
运行 FastAPI / Starlette 等 ASGI `app`	`uvicorn main:app` 为默认组合
开发本地热重载	`--reload`（单进程）
生产多核利用	`--workers N` 或 gunicorn + `UvicornWorker`
纯 WSGI（传统 Flask `app`）	用 gunicorn/uwsgi 等 WSGI 服务器，或 `asgiref` 适配后再用 uvicorn

main:app 含义：main 是模块名（main.py），app 是该模块里的 ASGI 对象变量名；不是「文件名:函数名」以外的特殊语法。

--reload 与 --workers 互斥：reload 为单进程监视文件；生产用 workers，不要开 reload。

模块成员总览

CLI 常用参数

参数	说明
`host`	监听地址；本机 `127.0.0.1`，对外 `0.0.0.0`
`port`	端口
`reload`	开发热重载；生产关闭
`workers`	工作进程数；与 `reload` 不能同开
`log-level`	`debug` / `info` / `warning` 等
`proxy-headers` / `forwarded-allow-ips`	在 Nginx/Caddy 后还原 HTTPS、客户端 IP

`uvicorn.run(...)` 常用参数

名称	CLI 对应	说明
`app`（首参）	`main:app`	`"模块:变量"` 字符串或 ASGI 对象
`host` / `port`	`--host` / `--port`	监听
`reload`	`--reload`	开发热重载
`workers`	`--workers`	进程数
`log_level`	`--log-level`	日志级别

启动应用：`main:app`

uvicorn main:app --reload --host 127.0.0.1 --port 8000

import uvicorn

if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

片段	含义
`main`	模块名（`main.py`）
`app`	模块内 ASGI 可调用对象
`"main:app"` 字符串	懒加载，便于 reload 子进程重新 import

生产示例：

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --log-level info

生产部署

单机多进程：uvicorn --workers N；或 gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app，由 gunicorn 管 worker，前置 Nginx/Caddy 做 TLS。
配置：pydantic-settings 或 os.environ 读密钥，勿写入仓库。
优雅停机：systemd / Docker / K8s 发 SIGTERM 时留足 in-flight 请求时间。

FastAPI 只提供 app；TLS、限流、静态文件多在反向代理或上层完成。

模块	关系
`fastapi` / `starlette`	常见 ASGI `app` 来源
`gunicorn`	多进程管理 + `UvicornWorker`
`httptools` / `uvloop`	可选加速依赖（平台相关）
`asyncio`	ASGI 应用运行在事件循环上

易错点（排错速记）

生产开 --reload：开销大且有文件监视安全风险。
workers 与 reload 同开：无效或报错。
只绑 127.0.0.1 却要外网访问：改 0.0.0.0 或走反向代理。
代理后仍是 http、IP 不对：配置 proxy-headers / forwarded-allow-ips。
把 WSGI 应用直接传入：协议不匹配；需 ASGI 或适配。

资料：uvicorn 文档 · FastAPI · Starlette