app.Run() 无法支撑优雅重启,因其封装了 http.Server.ListenAndServe() 并阻塞主 goroutine,不暴露 *http.Server 引用、不接受 context,导致收到 SIGTERM 或 Ctrl+C 时直接退出,中断活跃请求。

不能靠 app.Run() 或 app.Listen() 直接触发重启,必须手动接管 *http.Server 并配合信号监听与超时 Shutdown() —— 否则所有活跃请求都会被 RST 中断。
为什么 app.Run() 无法支撑优雅重启
它本质是封装了 http.Server.ListenAndServe() 并阻塞主 goroutine,既不暴露 *http.Server 引用,也不接受 context.Context。一旦调用,控制权就交出去了:收到 SIGTERM(Kubernetes 默认发的)或 Ctr+C 时,进程立即退出,正在写响应的 SSE 连接、长事务 DB 操作、未 flush 的日志全被砍断。
-
app.Shutdown()不是app.Run()的补丁,它只在你显式构造并启动*http.Server后才有效 - 常见报错:
connection reset by peer、客户端收不到完整 JSON、502 Bad Gateway(LB 转发进来但监听器已关) - 别信网上抄的
app.Run(iris.WithoutInterruptHandler)+ 手动监听信号——它仍依赖app.Shutdown(),而后者底层还是得有*http.Server实例
如何从 Iris “抠出” *http.Server 并启动
放弃 app.Run(),改用标准库方式启动,并保留服务实例引用。关键点:Handler 必须设为 app.Handler()(不是 app),且启动必须放 goroutine 中,否则主 goroutine 阻塞,收不到信号。
- 构造时
Addr和Handler是必填项:srv := &http.Server{Addr: ":8080", Handler: app.Handler()} - 启动必须异步:
go srv.ListenAndServe(),否则后续信号监听逻辑永不执行 - 忽略
http.ErrServerClosed:这是Shutdown()正常完成的标志,不是错误,别当异常 panic - 别提前调
ln.Close():Iris 不暴露 listener,若需自定义 listener(如复用端口、TLS 配置),要用srv.Serve(ln)方式,而不是srv.ListenAndServe()
信号监听与 Shutdown() 的正确姿势
Go 程序无法响应 SIGKILL(kill -9),所以优雅重启只依赖 SIGINT(Ctrl+C)和 SIGTERM(K8s 发送)。注册必须明确指定这两个信号,不能只监听 SIGHUP。
- 用
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)注册,sigChan类型为chan os.Signal - 收到信号后,立刻 调
srv.Shutdown(ctx),中间不要加日志 flush、指标上报等逻辑——这会延长关闭窗口,导致 LB 还没摘流新请求就进来了 -
ctx必须带超时:ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second);别用context.Background(),否则可能无限等待卡住 - 别
defer cancel():超时后要主动 cancel,但要在Shutdown()返回后调,否则 ctx 提前取消会导致还在处理的请求被误中断
Kubernetes 环境下必须配齐三要素
preStop、readinessProbe、Shutdown() 超时三者缺一不可。应用层 Shutdown() 只负责“等请求做完”,不负责“拒收新请求”——那得靠 K8s 流量治理机制在请求抵达前拦截。
-
preStop要两步:先让readinessProbe失败(比如 touch /tmp/not-ready),再 sleep 几秒等 Kube-Proxy 刷新 iptables 规则 -
readinessProbe必须可动态失效,例如检查/tmp/not-ready文件是否存在,或调用内部/health/ready接口返回 503 -
Shutdown()超时建议 15–30 秒,具体看业务最长请求耗时;HTTP/2 或 WebSocket 连接需额外注意,它们可能比普通 HTTP 请求更难“自然结束” - 确保容器 PID 1 是你的 Go 进程,不是 shell 脚本;否则
SIGTERM根本收不到——Dockerfile 里用exec ./your-binary启动
真正容易被忽略的是 handler 内部对 ctx.Done() 的响应:DB 查询、RPC 调用、后台 goroutine 全得显式接收并退出,否则 Shutdown() 会一直等下去。别以为只要调了 srv.Shutdown() 就万事大吉。


















