Gin服务在Kubernetes等多容器环境中实现可靠优雅下线，仅调用srv.Shutdown()不够，必须配合SIGTERM监听、超时控制、readinessProbe、preStop hook及terminationGracePeriodSeconds配置。
直接说结论：Gin 服务在多容器环境下（如 Kubernetes）要实现真正可靠的优雅下线，srv.Shutdown() 只是必要条件，不是充分条件；必须配合 SIGTERM 信号监听、超时控制、健康探针配置和 preStop hook 才算闭环。
为什么单纯调用 srv.Shutdown() 在容器里会失效
在 Docker 或 Kubernetes 中，当你执行 docker stop 或滚动更新时，容器运行时默认发送 SIGTERM，然后等 10 秒（Docker 默认）或 terminationGracePeriodSeconds（K8s 默认）后发 SIGKILL 强制终止。但如果你没显式监听 SIGTERM，Go 进程会直接退出，srv.Shutdown() 根本没机会执行。
- 现象：日志里看不到 “shutting down server…”，连接被粗暴断开，客户端收到
connection reset或502 Bad Gateway - 根本原因：Go 程序默认不捕获信号，
http.Server.Shutdown()是同步阻塞调用，必须由你主动触发 - 常见错误写法：只在
main()结尾调用srv.Shutdown()—— 此时进程已准备退出，无意义
signal.Notify 必须绑定 os.Interrupt 和 syscall.SIGTERM
这是容器环境唯一有效的退出入口。Kubernetes 的 preStop hook 触发后，kubelet 会向容器主进程发 SIGTERM；本地 docker stop 同理。只监听 os.Interrupt（Ctrl+C）在容器里完全无效。
- 正确写法：
signal.Notify(quit, os.Interrupt, syscall.SIGTERM) - 不要漏掉
syscall.SIGTERM—— 它是容器生命周期管理的“官方语言” - channel 容量设为 1 即可：
quit := make(chan os.Signal, 1)，避免信号丢失 - 启动监听 goroutine 后，必须用
<-quit阻塞等待，否则程序可能提前退出
超时时间必须小于容器平台的终止宽限期
你的 context.WithTimeout 时间必须严格短于 K8s 的 terminationGracePeriodSeconds（默认 30s）或 Docker 的 stop timeout（默认 10s），否则 Shutdown() 还没完成就被 SIGKILL 终止。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 推荐值：K8s 场景设为 25s，Docker 场景设为 8s
- 超时后
srv.Shutdown()返回context.DeadlineExceeded，此时应记录日志并让进程自然退出 - 别用
context.Background()—— 它永不超时，等于放弃可控性 - 注意：超时仅影响 Shutdown 等待，不影响已进入 handler 的请求；它们仍会跑完（除非你自己加了 context 超时）
Kubernetes 必须配 readinessProbe + preStop
光靠代码优雅关闭还不够。K8s 需要主动配合：先摘流量，再发信号。否则新请求还在打进来，旧实例就 shutdown 了。
-
readinessProbe：确保 Pod 不再接收新流量才开始终止流程。路径建议用/healthz，失败阈值设为 1 -
preStophook：推荐用exec执行sleep 2（给 kube-proxy 更新 iptables 规则留缓冲），不是必须但很稳妥 - Deployment 中必须设
terminationGracePeriodSeconds: 30，且 ≥ 你代码里的 Shutdown 超时 - 没配 readinessProbe 时，K8s 默认认为 Pod 一直 ready，滚动更新时会出现“新旧实例同时收流量”的竞争
最容易被忽略的一点：Gin 中间件里启动的 goroutine（比如日志 flush、指标上报）如果没做 cancel 控制，会在 Shutdown() 返回后继续运行，导致进程 hang 住无法退出。所有长期运行的 goroutine 都得接受同一个 context.Context 并监听 Done。
