Gin 优雅下线需手动构建 http.Server 并监听 SIGTERM/SIGINT,先调用注册中心注销接口,再执行带超时的 srv.Shutdown(),最后关闭数据库、WebSocket 及后台 goroutine;同时配合 Nginx 健康检查或权重调整避免流量涌入。

用 http.Server.Shutdown() 配合信号监听实现基础优雅下线
Gin 本身不提供内置的下线逻辑,它依赖 Go 标准库的 http.Server。关键动作是:在收到 SIGTERM 或 SIGINT(如 kill -15 或 Ctrl+C)后,调用 srv.Shutdown(),而不是直接 os.Exit() 或让主 goroutine 退出。
这个方法会做三件事:停止接受新连接、等待正在处理的请求完成(默认无超时)、关闭监听器。但注意:Shutdown() 不会自动等待你自定义的后台任务(比如未完成的定时 job、gRPC 客户端注销、数据库事务提交),这些必须手动协调。
-
srv.Shutdown()必须传入带超时的context.Context,否则可能永久阻塞;建议设 30–60 秒,足够处理多数长请求 - 不要在
Shutdown()前关闭数据库连接池或注销注册中心——应放在Shutdown()的defer或WaitGroup后执行 - 若使用
gin.Engine.Run()启动,它内部会新建一个http.Server,但你无法拿到实例引用;必须手动构建&http.Server{Handler: router}才能控制生命周期
与注册中心联动:下线前主动通知 Eureka / Nacos / Consul
仅靠进程内优雅关闭不够。如果服务已注册到 Eureka 或 Nacos,客户端仍可能在几秒甚至几十秒内继续发请求过来——因为注册中心有缓存(Eureka 三级缓存、Nacos 客户端本地缓存)、心跳续约延迟、健康检查间隔等。
所以真正“优雅”的下线必须分两步:先从注册中心注销,再执行 Shutdown()。顺序不能反,否则会出现“已关服务还在注册列表里”的状态。
- 调用注册中心 SDK 的注销方法(如
nacosClient.DeregisterInstance()或consul.Agent().ServiceDeregister()),并同步等待返回成功 - 注销成功后,再启动
Shutdown()流程;如果注销失败,应记录错误并考虑是否中止下线 - Spring Cloud 场景下,
/actuator/shutdown端点会触发注销+关闭,但 Gin 没这机制,需自己封装类似POST /ops/down接口,在 handler 中调用注销 + 发送信号给主 goroutine
避免 Nginx 层流量打到正在下线的节点
Nginx 作为反向代理,不会感知你的 Go 进程是否在 Shutdown()。如果你用 upstream 直接写死 IP+端口,或者没配健康检查,它会在你调用 Shutdown() 后继续转发新请求,导致 502/504 或连接拒绝。
必须让 Nginx 主动“知道”这个节点要下线了。常见做法不是等它探测失败,而是提前干预:
- 把节点的
weight=0(需配合nginx -s reload或 Lua 动态更新),Nginx 就不再选它处理新请求 - 暴露
/health?ready=false接口,返回 503,并在 Nginx 配置中启用health_check,让它自动剔除 - 在 Gin 的
/health接口里加个字段"status": "DOWN",并在下线流程开始时切换该响应;Nginx 的max_fails=1 fail_timeout=1s能在 1 秒内把它踢出 upstream
容易被忽略的长连接和后台 goroutine
HTTP 请求结束 ≠ 所有工作完成。Gin 应用常伴随 WebSocket、定时任务、消息消费 goroutine、数据库连接池中的空闲连接等。它们不会因 Shutdown() 自动终止。
例如:一个后台 time.Tick() 每 5 秒拉一次配置,若没显式 stop,它会一直跑,甚至在进程退出后 panic;又比如 gRPC client 连接没 Close(),可能导致 fd 泄漏或下次启动端口占用。
- 所有长期运行的 goroutine 应接收
context.Context并在Done()触发时退出 - 数据库连接池(
*sql.DB)需显式调用db.Close(),且应在Shutdown()返回后再执行,否则可能中断正在执行的查询 - WebSocket 连接需在
Shutdown()开始后主动发送 close frame,并等待客户端确认,不能只靠 TCP FIN











