在分布式系统里，网关往往作为客户端与后端服务之间的统一入口，而集群长连接指的是客户端与网关之间维持了较久的 TCP 或 WebSocket 连接，用于实时消息、心跳保活或流式数据。当我们需要对网关集群做缩容、发版或故障转移时，如果不能合理处理这些长连接，就会造成大量客户端瞬时断开，影响业务连续性。
什么是集群长连接与网关优雅下线
集群长连接通常出现在 IM 聊天、直播弹幕、股票行情推送等场景中。与短请求不同，长连接可能持续几分钟甚至几天，连接上承载着会话状态与业务上下文。一旦网关节点被强行终止，操作系统会发送 RST 包或直接丢弃连接，客户端只能重新握手，这不仅浪费资源，还会带来明显的用户感知中断。
网关优雅下线是指节点在退出前，先通过一系列机制不再承接新流量，同时给存量长连接留出缓冲期，让它们被调度到其他节点或自然关闭。核心目标是“可控制的退出”而不是“突然的消失”。在 Kubernetes 环境里，这对应 preStop 钩子与 terminationGracePeriodSeconds 的配合；在虚拟机部署中，则依赖运维脚本与注册中心联动。
为什么长连接让优雅下线更困难
短连接的下线相对简单：负载均衡摘掉节点后，几秒内基本没有存量请求。但长连接是“占着茅坑不拉屎”的典型，连接数不会随流量停止而立刻下降。如果网关进程收到终止信号马上退出，所有 socket 被关闭，客户端会批量触发重连风暴，后端认证与推送服务可能被打挂。
另一个难点是会话粘滞。很多长连接业务在网关层缓存了用户状态，比如设备 ID 与订阅频道。节点消失后，这些状态若没有外部存储支撑，就只能由客户端重建。因此优雅下线方案必须考虑状态迁移成本，或者至少保证重连后能快速恢复，而不是单纯等待连接老化。
常见错误做法
- 直接 kill -9 网关进程，依赖客户端超时重连。
- 先从注册中心注销，但进程立刻退出，导致已连上的用户被切断。
- 设置极短的优雅期（如 2 秒），长连接根本来不及排空。
网关优雅下线的标准配置步骤
第一步是开启连接 draining 模式。网关在收到退出信号时，先把本地标记为“不可路由”，负载均衡或注册中心据此停止转发新连接。以 Nginx 为例，可以通过减小 worker 的 accept 锁或返回 502 给新请求来实现；以 Spring Cloud Gateway 为例，可借助 Actuator 的 /actuator/service-registry 将状态置为 DOWN，并配合熔断。
第二步是设定合理的宽限期。宽限期内，网关继续服务已建立的长连接，但拒绝新建。对于 WebSocket，可以发送关闭帧通知客户端主动重连到其他节点；对于 TCP 透传，可依赖客户端心跳失败后的退避重连。宽限期通常建议大于业务最大静默周期，比如设为 30 秒到 5 分钟。
健康检查与摘流顺序
正确的顺序应是：先改健康检查状态为失败，让上游 LB 摘流；再等一个心跳周期确认无新连接；然后进入 draining；最后才退出进程。如果反过来先杀进程，就会出现摘流不及时的问题。
| 步骤 | 动作 | 目的 |
|---|---|---|
| 1 | 注册中心状态置 DOWN | 阻止新流量进入 |
| 2 | 等待 LB 刷新与连接静默 | 确认无新建连接 |
| 3 | 发送长连接关闭帧或通知 | 客户端平滑迁移 |
| 4 | 进程退出 | 释放资源 |
集群层面的配合事项
网关前面的四层负载均衡（如 LVS、SLB）也需要支持连接 draining。有些云厂商的 CLB 在后端实例解绑时，默认会发送 FIN 包并保留旧连接一段时间，这时网关的退出宽限要与之匹配，避免 CLB 已断而网关还在等。此外，服务网格如 Istio 可通过 DestinationRule 的 trafficPolicy 配置连接池排空，对长连接同样有效。
后端业务服务也要容忍客户端重连。优雅下线后，客户端往往会集中重连到剩余网关节点，此时后端需做好限流与鉴权缓存，防止雪崩。实践中，可以在客户端侧加入指数退避与随机抖动，把重连分散到不同时间点，从而降低对网关集群的冲击。
配置示例与参数建议
以 Kubernetes 中的网关 Deployment 为例，可在容器定义里加入 preStop 执行摘流脚本，并把 terminationGracePeriodSeconds 设为 120。脚本内容可以是调用本地管理接口标记下线，然后 sleep 足够时间。注意 sleep 时长应小于宽限周期，否则 Pod 会被强制删除。
对于自研网关，建议在配置文件中暴露如下参数：draining_timeout（默认 60s）、reject_new_connection（布尔）、send_close_frame_on_draining（布尔）。运维在发版时只需滚动更新，平台自动按序执行摘流与退出，无需人工介入。这样即使在十节点集群中一次下线两三个，长连接用户也几乎无感。
优雅下线的本质，是把“机器消失”这件事包装成“用户无感知的调度”，长连接只是让这个包装更费工夫而已。
总结与排查思路
当发现网关下线时大量客户端掉线，优先检查注册中心注销与进程退出的时间差，再看 LB 是否支持连接 draining。通过监控长连接数曲线，可以直观判断宽限设置是否合理：如果退出瞬间连接数陡降为零，说明没走优雅流程；如果缓慢下滑并在宽限末尾归零，则为正常。
把集群长连接与网关优雅下线当作发版规范的一部分，而不是临时操作，才能保障实时业务的稳定性。从配置、平台到客户端策略全链路打通，才能真正做到缩容不闪断、升级不影响。
集群长连接网关优雅下线连接 draining修改时间：2026-08-11 20:03:37