uvicorn在kubernetes中必须适配asgi生命周期与容器编排逻辑，否则将导致健康检查失败、pod反复重启、资源不匹配及请求被静默丢弃；需禁用--reload/--debug、使用uv替代uvicorn、正确配置探针路径与端口、协同设置worker数与内存限制，并启用--limit-concurrency应对高并发。
Uvicorn在Kubernetes中不是“能跑就行”，而是必须按ASGI生命周期和容器编排逻辑来设计——否则你会遇到健康检查失败、Pod反复重启、CPU/内存请求不匹配、甚至请求被Service silently drop掉。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
Uvicorn启动命令必须适配K8s容器生命周期
Kubernetes要求容器主进程（PID 1）能响应SIGTERM并优雅退出，而默认的uvicorn main:app --reload 在生产环境会启动多个进程（watchdog + workers），且 --reload 会监听文件变化——这在只读容器文件系统里不仅无效，还会触发错误日志甚至崩溃。
- 必须禁用
--reload和--debug - 主进程应为单线程、无fork、可接收SIGTERM（
uvicorn默认满足，但需确认未被Gunicorn包装） - 推荐使用
uv（uv工具链）替代pip install uvicorn，它更轻、启动更快、信号处理更可靠 - 示例CMD：
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0:8000", "--port", "8000", "--workers", "4"]
- 若用Gunicorn + Uvicorn worker（
gunicorn -k uvicorn.workers.UvicornWorker），需额外配置--graceful-timeout和--timeout，否则K8s terminationGracePeriodSeconds超时后直接kill -9
liveness/readiness探针路径和参数必须与Uvicorn实际行为一致
很多部署失败源于探针配置和Uvicorn路由不匹配：比如探针访问/health，但应用没定义该路由；或用了 httpGet 却没暴露端口；或 initialDelaySeconds 设太小，Uvicorn还没完成模型加载就判定失败。
-
readinessProbe应指向真实轻量健康端点（如FastAPI的@app.get("/health")），且返回200必须快于periodSeconds -
livenessProbe可复用同一端点，但initialDelaySeconds建议 ≥30（尤其含大模型加载时） - 不要省略
port字段，即使只暴露一个端口——K8s不会自动推断 - 若Uvicorn监听
0.0.0.0:8000，则containerPort必须为8000，且httpGet.port也得是8000，三者不一致会导致探针始终503
资源限制和worker数必须协同设置，否则OOMKilled频发
Uvicorn的--workers 数不是越多越好。每个worker是独立Python进程，共享同一份内存映射（如大模型权重），但各自持有独立的异步事件循环、连接池和临时对象。若不限制，K8s会因内存超限杀掉Pod。
- 先固定
resources.limits.memory（例如"512Mi"），再反推worker数：一般1个worker约占用100–150Mi基础内存 + 模型常驻部分 -
UVICORN_WORKERS环境变量优先级高于命令行参数，建议统一用env传入，便于Helm/Kustomize管理 - CPU request设为
"250m"时，不要设--workers 8——调度器可能把多个worker塞进同一个CPU核，造成争抢和延迟毛刺 - 实测经验：对FastAPI+Uvicorn常规API服务，
--workers 4+limits.memory: "512Mi"是较稳起点；含模型推理的，worker数建议 ≤2，并提升memory limit
真正容易被忽略的是：Uvicorn本身不管理连接队列长度，K8s Service的默认 sessionAffinity: None 和 kube-proxy 的iptables模式，在高并发短连接场景下可能造成连接堆积，此时需配合 max-connections（通过 --limit-concurrency）和Ingress层限流一起调优。
