必须监听SIGTERM并分两步shutdown:先srv.Shutdown(ctx)等待HTTP连接关闭,再client.Agent().ServiceDeregister(instanceID)确保Consul立即移除实例。

不加 SIGTERM 捕获和有序 shutdown,服务注销就是假的——Consul 里残留的实例会持续接收流量数小时,直到 TTL 过期。
为什么 defer client.Agent().ServiceDeregister() 不行
注册时调用 client.Agent().ServiceRegister() 是同步的,但注销不能靠 defer 或 main 函数末尾硬删。进程被 SIGTERM 中断时,defer 可能根本没机会执行;更常见的是 HTTP server 还在处理请求,连接未关闭,就直接退出,导致 Consul 认为服务“还在”,下游持续转发请求。
-
defer在函数返回时才触发,main() 里没有显式 return,它不会跑 - Go runtime 收到
SIGTERM后直接终止进程,不等 defer、不等 goroutine 完成 - 即使你手动写
client.Agent().ServiceDeregister("xxx"),也得确保它在 HTTP server 关闭之后、进程退出之前执行
必须监听 SIGTERM 并分两步 shutdown
Gin 本身不管理信号,得自己用 signal.Notify 接住退出信号,再按顺序关服务、注销实例。关键不是“有没有 deregister”,而是“什么时候 deregister”。
- 先调
srv.Shutdown(ctx),等待所有活跃 HTTP 连接完成(超时建议设 10–15 秒) - 再调
client.Agent().ServiceDeregister(instanceID),确保 Consul 立即移除该实例 - 整个流程要包在
select+context.WithTimeout里,防卡死 - 别用
os.Exit(0)强退——它绕过 defer 和 context cancel,注销直接失效
ServiceDeregister 调用前必须确认注册 ID 一致
Consul 注销依赖 ID 字段精确匹配,而这个 ID 往往是启动时动态生成的(比如 "user-service-192.168.1.10:8080")。如果注册时用的是随机字符串或固定值,多实例会覆盖,注销时可能删错、删漏。
- 注册时
AgentServiceRegistration.ID必须唯一且可复现,推荐格式:"{name}-{host}:{port}" - 注销时传入的
instanceID必须和注册时完全一致,大小写、冒号、端口都不能差 - 别从环境变量或 flag 里临时拼接 ID,容易因空格、换行、未 trim 导致不一致
- 可以在注册成功后立刻 log 出
ID,方便调试时比对
注销失败时没有 fallback,必须主动检查响应
client.Agent().ServiceDeregister() 返回 error,但很多人忽略它。Consul API 返回 404 或 500 时,错误不 panic,只是静默失败——你以为删了,其实还在。
- 检查返回 error 是否为
nil,非 nil 就该记录日志并考虑重试(最多 1–2 次) - 不要依赖
consul kv get /services/...手动验证,太慢;改用client.Health().Service(<code>serviceName, "", false, nil) 查当前节点是否已不在列表中 - 如果注销失败且进程即将退出,至少打一条
WARN日志,比如"Failed to deregister service {id}, zombie node may persist"
最容易被忽略的一点:注销逻辑必须和注册逻辑共享同一个 consul.Client 实例,且该 client 初始化时已配好超时(HttpTransport.Timeout 至少 3s),否则 ServiceDeregister 可能卡住,导致 shutdown 流程 hang 死,最终被 K8s 的 terminationGracePeriodSeconds 强杀——这时注销又没跑完。


















