graceful-shutdown

Graceful Shutdown Skill — 优雅停机

何时使用

• 部署滚动更新时用户看到 502 / 连接重置
• 排查"deploy 后丢了几条请求 / 队列消息"
• 设计长连接服务（WebSocket / SSE / gRPC streaming）的发布
• 数据库 / 缓存连接没正确关闭，连接数堆积
• Kubernetes 滚动 deploy 配 preStop / terminationGracePeriodSeconds

一、为什么需要优雅停机

[时刻 T]   K8s 收到 deploy 命令
[T+0ms]    新 Pod 创建
[T+xms]    新 Pod ready → Service endpoint 加入新 IP
[T+xms]    Service endpoint 移除旧 IP（异步！可能延迟）
[T+xms]    旧 Pod 收到 SIGTERM
[T+30s]    grace period 默认 30s 后 SIGKILL

两个并发问题：

1. endpoint 摘流延迟：旧 Pod 收到 SIGTERM 但 LB 还在发流量进来 → 502 / 连接重置
2. in-flight 请求：旧 Pod 处理中的请求还没完成就被 kill → 数据不一致 / 客户端 retry

二、停机六步标准流程

1. 收到 SIGTERM
2. 标记 health check 为 unhealthy → LB / Service 摘流
3. 等若干秒（让 LB / DNS / kube-proxy 真正生效）
4. 关闭 HTTP listener（不接新连接）
5. 等待所有 in-flight 请求完成（带 timeout）
6. 关闭依赖（DB pool / Redis / message queue / OTel exporter flush）
7. 进程退出

三、Go 标准实现

func main() {
    srv := &http.Server{Addr: ":8080", Handler: router}
    go srv.ListenAndServe()

    // 1. 等信号
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGTERM, syscall.SIGINT)
    <-quit
    log.Info("shutdown signal received")

    // 2. 标记 unhealthy（让 LB 摘流）
    healthState.Store(false)
    time.Sleep(5 * time.Second)   // 等 LB 摘流（K8s readiness 周期 + 误差）

    // 3-4-5. 关闭 HTTP（带超时；server.Shutdown 等 in-flight 完成）
    ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
    defer cancel()
    if err := srv.Shutdown(ctx); err != nil {
        log.Error("forced shutdown", "err", err)
    }

    // 6. 关依赖
    db.Close()
    redis.Close()
    tracerProvider.Shutdown(context.Background())   // flush spans
    log.Info("shutdown complete")
}

四、Node.js (Express / Fastify)

const server = app.listen(8080)
let shuttingDown = false

// healthcheck 路由
app.get('/healthz', (req, res) => {
  res.status(shuttingDown ? 503 : 200).json({ ok: !shuttingDown })
})

async function shutdown() {
  if (shuttingDown) return
  shuttingDown = true
  console.log('SIGTERM received, shutting down')

  // 1. 等 LB 摘流
  await sleep(5000)

  // 2. 关 listener
  await new Promise<void>((resolve) => {
    server.close((err) => err ? console.error(err) : resolve())
    // server.close 等所有 keep-alive 连接关闭
    // 强制关 keep-alive：server.closeIdleConnections()  (Node 18+)
    server.closeIdleConnections?.()
  })

  // 3. 等 in-flight（自家计数器或外部 inflight 中间件）
  await waitForInflightToFinish(20_000)

  // 4. 关依赖
  await db.end()
  await redis.quit()
  await otelSdk.shutdown()

  process.exit(0)
}

process.on('SIGTERM', shutdown)
process.on('SIGINT', shutdown)