Go HTTP 服务端Server Shutdown 后长连接不退出怎么办

Go HTTP 服务调用 Server.Shutdown 后，长连接仍不退出，通常不是 Shutdown 失效，而是连接还没有回到“空闲”状态，或者已经被处理器 Hijack 接管。Shutdown 会先关监听器、关闭空闲连接，再等待活动连接完成；它不会替你强制结束仍在运行的流式处理，也不会替你管理 WebSocket 这类 hijack 连接。

先判断：长连接到底卡在哪个状态

排查时先不要盲目把 context.Background() 换成更长的超时。Shutdown 处理的是 HTTP 服务仍然拥有的连接，关键区别在于连接当前是否空闲、是否正在执行 Handler，以及是否已经被移交给应用代码。

因此，“Shutdown 后进程还在”只能说明收尾链路没有完成，不能单凭现象判断是网络连接泄漏。把 ConnState 和业务连接数一起记录，才能知道等待对象。

用 ConnState 和处理器日志复现根因

ConnState 适合观察 HTTP 层状态变化，但它不会替你管理已经 hijack 的连接。下面的记录方式把连接状态和统一停止信号放在同一个故障现场里；代码是结构示例，图中关系也是静态说明图，不是运行截图。

// 统一停止长请求，并记录连接进入了哪个 HTTP 状态。
stopLongRequest := make(chan struct{})
var longRequestWG sync.WaitGroup

srv := &http.Server{
    Addr: ":8080",
    ConnState: func(conn net.Conn, state http.ConnState) {
        log.Printf("http connection=%v state=%s", conn.RemoteAddr(), state)
    },
}

srv.RegisterOnShutdown(func() {
    // 这里只发停止信号；长请求收到后仍要自行返回。
    close(stopLongRequest)
})

mux := http.NewServeMux()
mux.HandleFunc("/events", func(w http.ResponseWriter, r *http.Request) {
    longRequestWG.Add(1)
    defer longRequestWG.Done()
    flusher, _ := w.(http.Flusher)
    if flusher != nil {
        flusher.Flush()
    }
    select {
    case 

如果日志一直停在 StateActive，说明 Handler 仍在等待；如果连接是 WebSocket，则需要在自己的注册表里找到它。注意 RegisterOnShutdown 是通知钩子，不是等待器，关闭信号发出后仍要由应用维护完成计数。

修复：通知、关闭、等待要分成三步

比较稳妥的退出顺序是：先让新连接停止进入，再调用 Shutdown，由回调通知长任务和 hijack 管理器，最后等待应用自己的连接集合。对普通长请求，通知后让 Handler 返回；对 WebSocket，则在回调里调用连接管理器的 CloseAll，而不是期待 net/http 替你关闭。

// 退出时给所有长任务一个有限的收尾窗口。
sig := make(chan os.Signal, 1)
signal.Notify(sig, os.Interrupt, syscall.SIGTERM)

生产代码还应把“关闭通知”和“强制兜底”分开：通知阶段给长任务一个可观察的结束原因；超时后记录剩余连接数量、连接类型和最后一条状态日志，再由进程管理器完成最后的强制退出。这样既不会无限等待，也不会把正常的长请求误判成连接泄漏。

常见问题与边界

为什么 Shutdown 关闭监听端口后进程还不退出？

监听器关闭只阻止新连接，活动 Handler 和仍由应用持有的 hijack 连接仍可能存在。检查是否有 goroutine 在读写流、等待下游或等待客户端。

把 Shutdown 的超时改成一小时能解决吗？

不能。超时只改变等待上限，不会让缺少停止信号的 Handler 自动返回；应先补通知和连接管理，再设置合理的收尾窗口。

WebSocket 能靠 Request.Context 结束吗？

不能把它当成唯一方案。Hijack 后连接由应用负责关闭，应该登记连接、在退出时广播关闭，并等待写协程和读协程完成。

最后复查三件事：监听器是否停止接收、普通长请求是否收到停止信号、hijack 连接是否有独立的 CloseAll 与等待逻辑。三条都能落到日志或计数，Server.Shutdown 后长连接不退出的问题才算真正闭环。