FastAPI + uvicorn 默认配置导致 K8s 滚动发布每次丢 30-50 请求的 5 天复盘:graceful shutdown 三件套配置 + ASGI lifespan drain 逻辑

2026 年 2 月某个周二上午,我们发现一个困扰团队 3 个月的"小问题"——每次 K8s 滚动发布 api-gateway,Grafana 监控面板都会出现一个清晰的 5xx 毛刺,持续 30-60 秒,大约 30-50 个请求被打回。因为这个网关日均 6 亿请求,几十个请求的损失相对很小,SRE 一直把它归类为"可接受的发布抖动"。但这次大客户对账时发现某次发布时间窗口里有 12 个支付请求 500,涉及金额 ¥4.8 万,客诉直接打到了 CTO。复盘必须做了——这次彻底搞清楚了为什么FastAPI + uvicorn 默认配置下,K8s SIGTERM 不能正确触发 graceful shutdown。

5 天的排查 + 修复让我们落地了一套"ASGI 服务优雅退出三件套":uvicorn 启动参数 + K8s preStop + 应用层 lifespan drain。改完之后连续 28 次滚动发布,5xx 毛刺彻底消失。这篇是完整复盘,涵盖 K8s Pod terminate 时序、uvicorn 默认 signal handling 行为、ASGI lifespan 协议怎么用、preStop + terminationGracePeriodSeconds 怎么配,以及一套可以直接抄走的零停机发布配置模板。如果你的 FastAPI / Starlette / Sanic 服务还没做过 graceful shutdown 测试,这篇能帮你提前堵住每次发布的请求损失。

背景:这个 API 网关

事故时间线:5 天定位

根因因果链:为什么默认配置会丢请求

把这次"每次发布丢 30-50 请求"用因果链画出来,可以看清楚 K8s Pod 终止流程与 ASGI 服务默认行为之间的错位:

这张图最关键的两个洞察:

• Endpoint 移除与 SIGTERM 是并行的,不是先后的。很多人以为 K8s 会"先把 Pod 从 Endpoint 摘掉,再发 SIGTERM",实际不是——两件事同时发生,kube-proxy 的更新需要 1-3 秒甚至更久才能传播到所有节点,这期间已经在收 SIGTERM 的 Pod 还在收新流量。
• uvicorn 默认配置下 SIGTERM 等于"立刻退出"。0.27 版本以前 uvicorn 的默认 --timeout-graceful-shutdown 是 None(也就是 0 秒),收到 SIGTERM 立刻关 accept socket 并强制结束 worker。正在处理的请求被无情打断。

这两个错位叠加在一起,就是"每次发布丢请求"的完整解释。要彻底修复必须同时处理这两个问题:第一,延迟 SIGTERM 让 Endpoint 移除有时间传播;第二,让 uvicorn 真正等 inflight 请求处理完再退出。

K8s Pod terminate 完整时序

修复前必须先搞清楚 K8s 的 Pod 终止时序,否则修了也白修:

核心规则要记牢:

• terminationGracePeriodSeconds 是从 preStop 开始计时的,不是从 SIGTERM。如果 preStop 跑了 10 秒,grace period 30 秒,那么进程最多有 20 秒处理 inflight。
• preStop 期间容器仍在收新流量(Endpoint 同步还没完成),但你可以用 preStop "sleep N" 制造一个延迟,让 Endpoint 同步先完成再 SIGTERM。
• SIGKILL 是无法捕获的,到 grace period 超时必杀。所以你的程序必须保证在 grace period 内自己退出。

修法 1:uvicorn 启动参数

第一道防线是让 uvicorn 自己懂 graceful shutdown:

# 默认(危险!)— SIGTERM 立刻退出
uvicorn app.main:app --workers 4

# 正确 — 明确指定 graceful shutdown 超时
uvicorn app.main:app \
    --workers 4 \
    --timeout-graceful-shutdown 30 \
    --timeout-keep-alive 5 \
    --limit-concurrency 1000

# 0.27+ 支持的参数,旧版本可能没有 — 必须确认 uvicorn >= 0.27

关键参数说明:

这里有个常被忽略的坑:uvicorn 在 multi-worker 模式下,master 进程收到 SIGTERM 后会向所有 worker 发 SIGTERM,但 worker 内部的 graceful shutdown 逻辑是各自跑的。如果某个 worker 的 inflight 请求特别多,可能 30 秒内 drain 不完;另外 worker 之间的 drain 状态彼此不可见,这也是为什么单靠 uvicorn 参数不够。

修法 2:K8s 配置 preStop + grace period

第二道防线在 K8s 层。完整的零停机 Deployment 配置:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-gateway
spec:
  replicas: 8
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0    # 关键!确保滚动发布期间总有足够 Pod
  minReadySeconds: 10      # Pod ready 后等 10 秒再标可用
  template:
    spec:
      terminationGracePeriodSeconds: 60   # 总 grace period
      containers:
      - name: api-gateway
        image: api-gateway:latest
        ports:
        - containerPort: 8000
        # 关键 1:readiness 和 liveness 分开
        readinessProbe:
          httpGet:
            path: /healthz/ready    # 业务级健康检查
            port: 8000
          periodSeconds: 3
          failureThreshold: 2
        livenessProbe:
          httpGet:
            path: /healthz/live     # 进程级健康检查 — 永远 200
            port: 8000
          periodSeconds: 10
          failureThreshold: 3
        # 关键 2:preStop 强制等待 Endpoint 移除传播
        lifecycle:
          preStop:
            exec:
              command:
              - /bin/sh
              - -c
              - "sleep 10"   # 给 kube-proxy 1-3 秒 + 余量

这套配置的核心逻辑:

1. terminationGracePeriodSeconds: 60 —— 总预算 60 秒,包含 preStop 的 10 秒 + uvicorn 的 30 秒 drain + 10 秒余量。
2. preStop sleep 10 —— 在收 SIGTERM 前先 sleep 10 秒,这 10 秒里 Endpoint 移除已经传播到所有节点,新流量不再进入此 Pod。但已经建立的 keep-alive 连接还在,这就是为什么 preStop 之后 uvicorn 还要 drain。
3. maxUnavailable: 0 —— 滚动发布期间一个 Pod 都不少,保证容量。配合 maxSurge: 25% 先扩再缩。
4. readiness 和 liveness 分开 —— readiness 检查业务依赖(DB / Redis / 下游服务),liveness 只检查进程是否活着。这俩混在一起的话,业务依赖一抖,K8s 会重启 Pod,放大故障。

需要警惕:preStop sleep N 看似"简单粗暴",但它是社区公认最稳的做法。Istio / Linkerd / 各种 service mesh 的官方推荐配置里都有这一招。原因是 K8s 没有一个机制能让你"等 Endpoint 移除完成再 SIGTERM",所以用 sleep 是最直接的。

那为什么不用更"聪明"的方法,比如 preStop 主动调一个 endpoint 让应用进入 draining 状态?我们试过,实际操作起来比 sleep 复杂得多:preStop 里要 curl 自己的 endpoint,但 curl 需要先装在容器里,Alpine 镜像默认没有;改用 wget 又要处理 exit code;最关键的是,即使 preStop 调用成功,Endpoint 移除该多久还是多久,你省不下那 1-3 秒等待时间。所以最终大家都回到了 sleep——它的优势是"零依赖、零配置、零失败可能"。这是分布式系统工程里很经典的"简单方案战胜复杂方案"案例,值得记住。

sleep 时间的选择也有讲究。我们最初设的是 5 秒,实际测试中发现某些大集群(节点数 200+)的 Endpoint 同步偶尔到 8 秒,导致仍有少量请求漏过来。最终落定 10 秒是"覆盖 P99 同步延迟 + 余量"的策略,这个值适合大部分集群。如果你的集群特别大(节点数 500+),建议先用 kube-proxy 监控量一下 Endpoint 同步 P99,按它定 sleep 时间。不要凭直觉拍脑袋,直觉永远偏短。

修法 3:应用层 lifespan + drain 中间件

第三道防线在应用层。即使有了 uvicorn 参数和 K8s preStop,某些场景仍可能丢请求——比如 inflight 请求处理时间不均匀(99% 请求 50ms 但偶发 25 秒),uvicorn 的 timeout-graceful-shutdown 一到就强杀。要真正零丢失,必须让应用主动等 inflight 归零:

from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from starlette.middleware.base import BaseHTTPMiddleware
import asyncio
from dataclasses import dataclass

@dataclass
class AppState:
    ready: bool = False
    shutting_down: bool = False
    inflight_count: int = 0

state = AppState()

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动阶段
    await init_db_pool()
    await warmup_caches()
    state.ready = True
    yield
    # 关闭阶段 — SIGTERM 触发 lifespan shutdown event
    state.ready = False           # 立刻让 readinessProbe 失败
    state.shutting_down = True

    # 等 inflight 归零,最长 25 秒(留 5 秒余量给 cleanup)
    deadline = asyncio.get_event_loop().time() + 25
    while state.inflight_count > 0:
        if asyncio.get_event_loop().time() >= deadline:
            print(f"drain timeout, force shutdown with {state.inflight_count} inflight")
            break
        await asyncio.sleep(0.1)

    # 关闭资源
    await close_db_pool()
    print(f"shutdown complete, drained {state.inflight_count} pending requests")

app = FastAPI(lifespan=lifespan)

class InflightCounterMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        if state.shutting_down:
            # drain 期间拒绝新请求(但实际上 readiness 已经 fail,几乎没有新请求)
            from fastapi.responses import JSONResponse
            return JSONResponse({"error": "shutting down"}, status_code=503)
        state.inflight_count += 1
        try:
            return await call_next(request)
        finally:
            state.inflight_count -= 1

app.add_middleware(InflightCounterMiddleware)

@app.get("/healthz/ready")
async def ready():
    if not state.ready or state.shutting_down:
        from fastapi.responses import JSONResponse
        return JSONResponse({"status": "not ready"}, status_code=503)
    return {"status": "ready"}

@app.get("/healthz/live")
async def live():
    # 只要进程活着就 200,不依赖任何外部资源
    return {"status": "alive"}

这套设计的关键巧妙之处:

• readiness 早 fail —— shutdown 一开始就把 state.ready = False,下次 readinessProbe(periodSeconds: 3)就会失败,K8s 立刻把 Pod 从 Endpoint 移除,新流量瞬间停止。比 preStop sleep 10 更主动。
• inflight 计数器 —— 用中间件精确追踪正在处理的请求数,drain 时等它归零。
• deadline 保护 —— 万一某些请求卡死,25 秒强制退出,不要把 K8s 的 grace period 用尽触发 SIGKILL。
• livenessProbe 独立 —— shutdown 期间 readiness fail 但 liveness 仍 200,K8s 不会以为进程挂了重启。

本地测试:你的 graceful shutdown 真的生效吗

修完一定要本地验证,不能上线再测:

# 启动服务
uvicorn app.main:app --port 8000 --timeout-graceful-shutdown 30 &
APP_PID=$!

# 同时发起 100 个并发请求(模拟 inflight)
for i in {1..100}; do
    curl -s "http://localhost:8000/slow-endpoint" &
done

# 等 2 秒,让请求都开始处理
sleep 2

# 发 SIGTERM
echo "Sending SIGTERM to $APP_PID..."
kill -TERM $APP_PID

# 等进程退出并记录时间
time wait $APP_PID
echo "Process exited"

# 期望:所有 100 个 curl 都得到 200,进程在 30 秒内退出

如果你看到有 curl 返回错误,或进程立刻退出,那 graceful shutdown 就没配对。常见排查点:

1. uvicorn 版本是否 >= 0.27 (旧版本 --timeout-graceful-shutdown 不存在或行为不对)
2. 是否在 multi-worker 下测试(单 worker 容易掩盖问题)
3. 请求处理时间是否 > timeout-graceful-shutdown(慢请求会被强杀)
4. 是否注册了自定义的 signal handler 覆盖了 uvicorn 的(常见错误)

ASGI 服务器对比:谁 graceful 做得最好

结论:没有一个 ASGI 服务器默认就是"完美 graceful"。无论你用哪个,都必须显式配置超时参数 + 应用层 drain。不要相信"默认应该没问题"的直觉,这条直觉在分布式系统里基本永远是错的。这跟我们之前 .NET Dictionary 死循环复盘 里的教训一致:"框架抽象是有边界的,边界之外仍然是裸的运行时,要遵守裸的运行时规则"。

修法 4:Prometheus drain 监控

修完之后必须有监控,否则下次悄悄退化你也不知道。我们加了三个关键指标:

from prometheus_client import Counter, Histogram, Gauge

inflight_gauge = Gauge("http_inflight_requests", "Current inflight requests")
drain_duration = Histogram(
    "shutdown_drain_duration_seconds",
    "Time taken to drain inflight requests on shutdown",
    buckets=[0.5, 1, 5, 10, 20, 30, 60]
)
drain_timeout_counter = Counter(
    "shutdown_drain_timeout_total",
    "Number of shutdowns that hit drain timeout"
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    await init_resources()
    state.ready = True
    yield

    state.ready = False
    state.shutting_down = True

    start = asyncio.get_event_loop().time()
    deadline = start + 25
    while state.inflight_count > 0:
        if asyncio.get_event_loop().time() >= deadline:
            drain_timeout_counter.inc()
            break
        await asyncio.sleep(0.1)
    drain_duration.observe(asyncio.get_event_loop().time() - start)

    await close_resources()

Grafana 告警规则:

• shutdown_drain_timeout_total 任何增长都告警 —— 说明 inflight 超时没 drain 完
• shutdown_drain_duration_seconds P99 > 20s 告警 —— drain 时间过长,接近 grace period 上限
• http_inflight_requests 持续 > limit-concurrency 的 80% 告警 —— 单 Pod 负载过高

修复前后效果对比

"发布耗时 +10 秒/Pod"是 preStop sleep 10 带来的代价,8 个 Pod 滚动发布大约多花 80 秒,但这是值得的——零丢请求 vs 多等 1 分钟,业务侧毫不犹豫选前者。如果发布频次极高(比如某些团队一天 50+ 次)觉得 80 秒累积起来太多,可以把 maxSurge 调到 50% 让并行度更高,总耗时反而比修复前还短——这是另一个常被忽略的优化点:K8s 滚动发布的耗时主要由"串行度"决定,不是单 Pod 的优雅退出时间决定。

从更长远的视角看,这次修复的真正价值不是"消除毛刺",而是"把发布这件事变成无脑动作"。修复前,每次大版本发布前 SRE 都要"看着监控发"——盯着 5xx 曲线、随时准备回滚。修复后,SRE 可以放心把发布交给 CI/CD 自动完成,真正释放了人力。这种"把高焦虑动作变成低焦虑动作"的工程改造,是 SRE 工作中最有价值的部分,远超任何性能优化。我们团队从这次修复之后,SRE 同学的"发布日加班"频次从每周 2-3 次降到几乎为零,这是真实的工程幸福感提升。

同类问题扫雷:其他需要 graceful 的场景

修完 API 网关后我们做了一轮"同类问题扫雷",发现以下场景也都有类似的优雅退出隐患:

这种"扫雷"是事故复盘最被低估的产出。一个具体场景的修法暴露的是整个工程栈对优雅退出的认知缺失,扫雷比单点修复价值大 10 倍。我们之前 LangChain Agent memory 复盘 里也强调过同样的道理——"修一个 bug 的产出远小于扫一类 bug"。

扫雷的具体执行方法我们也总结成了一个 SOP:事故止血后第二天必开"扫雷 meeting",参与人是事故相关的所有同事 + 1-2 个其他业务线的资深工程师(带来不同视角)。会议产出是一份"同类风险服务清单",按"高/中/低"风险分级,高风险服务限期 1 周修复,中风险 1 月,低风险纳入下季度规划。这种"事故 → 扫雷 → 系统性修复"的闭环,比传统的"事故 → 修这一个 bug → 拍胸脯保证下次不犯"高效得多,因为后者只是个人承诺,前者是组织能力。

修法 5:本地 chaos 测试自动化

光手动测试不够,我们把"graceful shutdown 验证"做成了 CI 流程:

# tests/test_graceful_shutdown.py
import asyncio
import signal
import subprocess
import httpx
import pytest

@pytest.mark.asyncio
async def test_graceful_shutdown_no_request_lost():
    # 启动服务
    proc = subprocess.Popen([
        "uvicorn", "app.main:app",
        "--port", "8001",
        "--timeout-graceful-shutdown", "30"
    ])
    await asyncio.sleep(2)  # 等服务就绪

    # 并发发起 50 个请求,每个 5 秒
    async def slow_request():
        async with httpx.AsyncClient() as client:
            return await client.get("http://localhost:8001/slow", timeout=60)

    tasks = [asyncio.create_task(slow_request()) for _ in range(50)]
    await asyncio.sleep(1)  # 让请求都开始

    # 发 SIGTERM
    proc.send_signal(signal.SIGTERM)

    # 等所有请求完成
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # 等进程退出
    proc.wait(timeout=35)

    # 断言:所有请求都成功
    success = sum(1 for r in results if not isinstance(r, Exception) and r.status_code == 200)
    assert success == 50, f"Lost {50 - success} requests during shutdown"

这个测试每次 PR 都跑,任何打破 graceful shutdown 的改动都会被立刻发现。比如有人改了 lifespan 或者忘了加 InflightCounterMiddleware,CI 立刻红。"测试驱动的优雅退出"比"事故驱动的优雅退出"成本低两个数量级。

立的《ASGI 服务优雅退出纪律》

1. uvicorn 必须 >= 0.27 并显式指定 --timeout-graceful-shutdown,不要相信"默认应该没问题"。
2. K8s Deployment 必须配 terminationGracePeriodSeconds + preStop sleep,值要协调:grace period > preStop + drain timeout + 余量。
3. readiness 和 liveness probe 必须分开:readiness 检查业务依赖,liveness 只检查进程。shutdown 时 readiness fail / liveness 仍 200。
4. 应用层必须有 inflight 计数 + lifespan drain,不能只依赖 uvicorn 的 timeout。
5. 每个新服务上线前必须本地 SIGTERM 测试,验证零请求丢失,作为发布卡点。
6. CI 流程必须有 graceful shutdown 测试,防止后续 PR 引入回退。
7. 生产环境必须监控 drain 时间 + drain timeout 计数,持续监控防止悄悄退化。
8. 所有"长任务"组件(Celery / Kafka / WebSocket / gRPC stream)必须各自审计 graceful shutdown,不是 HTTP 服务也有同样的问题。

给读者的几条自查清单

1. 你的 FastAPI / Starlette / Sanic 服务启动命令里有 --timeout-graceful-shutdown 吗?没有就有丢请求风险。
2. K8s Deployment 配置里有 preStop hook 吗?没有的话每次发布都丢请求。
3. readinessProbe 和 livenessProbe 用的是同一个 endpoint 吗?如果是,业务依赖一抖 K8s 会重启你的 Pod。
4. 本地试过 kill -TERM <pid> 同时发请求吗?如果没试过,你不知道 graceful 是否生效。
5. Grafana 上有"shutdown drain 时长"指标吗?没有的话退化你看不到。
6. 除了 HTTP 服务,Celery / Kafka consumer / WebSocket / gRPC 服务也都做过 graceful 测试吗?
7. CI 流程里有 graceful shutdown 测试吗?这是防止退化的根本保障。

更深一层:为什么"默认配置"在分布式系统里总是坑

这次事故让我反思一个更深的问题:为什么 uvicorn 这种成熟的开源项目,默认配置仍然不是"production ready"?根本原因是开源项目的"默认值"通常是面向开发者本地体验优化的——开发时按 Ctrl+C 立刻退出比"等 30 秒"舒服得多。但生产环境的诉求完全相反,生产希望"按 SIGTERM 后慢慢退,把活干完"。这种"开发优先 vs 生产优先"的张力在所有 framework / library 里都存在。

对抗"默认配置陷阱"的工程实践有三层:第一,新服务上线前必须做"production checklist" review,把所有 framework 默认值都明确审过一遍,该改的改,该加的加;第二,团队 wiki 里维护一份"我们公司的 production-ready 配置模板",所有项目从这个模板派生,保证基线一致;第三,定期(季度)做"配置审计",对照最新版本的 framework changelog,看有没有新参数需要采纳。我们这次 graceful shutdown 的修复就直接产出了一份 FastAPI + K8s production template,后续所有新服务从模板派生,再没有人忘记这事。

另一个心得:"零停机发布"是分布式系统工程的基本功,但它的实现比想象的复杂得多。表面上看就是"滚动发布",实际上涉及 K8s 时序、framework signal handling、应用层 drain 协议、监控告警等多个层次。每一层都有自己的陷阱,任何一层漏掉都会导致发布抖动。这就是为什么"零停机"在小公司经常做不到——不是技术上做不到,是没有把每一层都研究透。"零停机发布"是一种组织能力,不是一种技术能力,需要 SRE + 应用工程师 + 平台工程师协同才能实现。

最后一句给所有写 Python web 服务的同学:每次你部署一个 FastAPI / Flask / Sanic 服务到 K8s 时,在心里默念一句"我有没有配 graceful shutdown"——如果答案是"没有"或"不确定",立刻补上 uvicorn 参数 + K8s preStop + 应用层 drain 三件套。这三件套的成本是 30 分钟工作量,收益是无数次"无感发布",从此再不会因为发布丢请求被客户投诉。这笔账无论怎么算都极其划算。下次我们继续看其他 Python 生态的"默认配置坑"——比如 SQLAlchemy 默认连接池配置在高并发下的失常表现,那也是另一个常被忽略的 production 陷阱。

事故复盘结束后我跟团队 SRE 做了一次"知识传承":把"K8s Pod terminate 时序"画在白板上让每个新人都讲一遍,目的是把这种"分布式系统的核心时序"变成团队的共同语言。任何新加入的工程师在 onboarding 时都必须通过这个考核——口头解释 SIGTERM 与 Endpoint 移除的并行关系、preStop 的作用、grace period 的计时起点。这种"通过白板讲解作为入职考核"的做法看起来僵硬,但实际是把"踩坑成本"提前付给"培训成本"——前者一次事故几万元,后者一次培训几小时。这种"前置投入"在工程团队管理上被严重低估,大部分团队都是事后救火而非事前预防。希望读到这篇的同学能让自己的团队走到"前置预防"那一侧——不是被事故教育出来的,而是主动设计出来的分布式系统能力。优雅退出三件套今天就可以加,不需要等到下次客户投诉对账偏差才动手。

跨语言对照:其他生态的优雅退出方案

FastAPI + uvicorn 的优雅退出方案放在更大的视野里看,本质和其他生态完全一致——只是各自的 framework API 不同而已。横向对比一下能看出"优雅退出"这件事的通用模式:

从横向对比能看出几个洞察:Go 的标准库设计最完整——http.Server.Shutdown(ctx) 直接给了"等待 inflight 完成或 ctx 超时"的精确语义,这是 Go 设计哲学"显式优于隐式"的体现;Python 生态最分散——FastAPI / Flask / Sanic / aiohttp 各自的 graceful shutdown 实现差异巨大,新人要花很多时间分别理解;Spring Boot 的 graceful shutdown 直到 2.3 版本(2020 年)才默认支持,在那之前 Java 圈也是各种手撸,跟今天 Python 圈的状态很像。这个对比告诉我们,Python 生态的优雅退出标准化还有不少路要走,在标准化到来之前每个团队都得自己踩坑+建模板。"框架成熟度"的差距,本质就是"踩坑深度"的差距——成熟的框架是被无数事故砸出来的,你今天踩的坑就是十年后框架默认配置的合理性来源。

把这种"被事故喂大"的视角放回我们这次复盘,会发现 5 天的排查 + 一周的落地工作,其实是在给团队"加一道分布式系统认知"。事故来时我们只看见了"5xx 毛刺",事故走后我们留下了"K8s Pod 时序模型 + ASGI lifespan 协议理解 + production checklist 模板 + CI 守护测试"四项资产。这些资产会在未来的每一个新服务、每一次新人 onboarding、每一次架构 review 中持续兑现价值。所以事故复盘的关键不在于"修这一个 bug",而在于"把这次事故里学到的东西,沉淀成组织资产,让下次同类事故根本不会发生"。这一条心法,值得每一个 SRE 和后端工程师反复琢磨。

—— 别看了 · 2026