Heroku WebSocket 关闭时 H15 错误的真相与应对指南-Golang-PHP中文网

heroku 中 websocket 连接正常关闭时触发的 h15（idle connection）日志仅为路由层的“伪错误”，并非服务异常；它源于 heroku router 对长连接终止状态的误判，实际不影响功能，但需正确认知与日志过滤。

heroku 中 websocket 连接正常关闭时触发的 h15（idle connection）日志仅为路由层的“伪错误”，并非服务异常；它源于 heroku router 对长连接终止状态的误判，实际不影响功能，但需正确认知与日志过滤。

在 Heroku 上部署 Go（或其他语言）WebSocket 服务时，开发者常被如下日志困扰：

2024-04-10T08:22:35.123456+00:00 heroku[router]: at=error code=H15 desc="Idle connection" method=GET path="/ws" 
host=your-app.herokuapp.com request_id=abc123 fwd="203.0.113.42" dyno=web.1 connect=1ms service=300000ms status=503 bytes=147

乍看之下，service=300000ms（即 5 分钟）与 status=503 容易被误读为超时崩溃或后端响应迟缓。但事实恰恰相反：这是一个健康、持续了 5 分钟的 WebSocket 连接，在客户端主动断开瞬间被 Heroku Router 记录为 H15 —— 它不是故障，而是设计使然。

? 为什么 H15 在 WebSocket 关闭时必然出现？

Heroku Router 的 HTTP 超时机制（默认 55 秒）仅适用于传统 HTTP 请求，不适用于已升级为 WebSocket 协议的连接。然而，Router 日志系统仍会将整个生命周期（从 Upgrade 请求开始到 TCP 连接终结）视为单个“HTTP 事务”。其行为逻辑如下：

✅ 连接建立阶段：客户端发起 GET /ws HTTP/1.1 + Upgrade: websocket 请求 → Router 记录初始时间戳；
✅ 心跳维持阶段：WebSocket 握手成功后，客户端/服务端定期发送 ping/pong 帧（如每 20 秒一次）→ 数据帧持续流动 → Router 内部超时计时器不断重置（符合文档所述）；
❗ 连接终止阶段：当用户关闭标签页、刷新页面或网络中断，TCP 连接静默断开 → Router 检测到连接终结 → 回溯计算“该请求总存活时长”（例如 300s），并因连接“空闲结束”而非“主动响应”，标记为 H15 Idle connection，状态码记为 503（历史兼容行为，非真实错误）。

? 关键结论：H15 日志 = WebSocket 连接已成功运行 N 秒 + 客户端优雅/非优雅断开。只要你的服务未报错、连接期间消息收发正常、无 H13（Connection closed without response）或 H14（No web processes running），即可完全忽略该条日志。

? 实操建议：降低干扰，保障可观测性

1. 日志层面：过滤 H15（推荐）

在日志聚合工具（如 Papertrail、Datadog、Logplex）中添加排除规则，避免噪声干扰：

# Papertrail 示例过滤语法
NOT "code=H15"
# 或更精准：仅排除 WebSocket 路径的 H15
NOT ("code=H15" AND "path=\"/ws\"")

2. 代码层面：增强连接生命周期感知（Go 示例）

在 Go WebSocket 服务（如 gorilla/websocket）中，显式处理 Close 事件并打点日志，与 Router 日志形成对照：

func handleWS(w http.ResponseWriter, r *http.Request) {
    conn, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        log.Printf("WS upgrade failed: %v", err)
        return
    }
    defer conn.Close()

    // 启动心跳读取（防止连接被中间件误杀）
    go func() {
        ticker := time.NewTicker(20 * time.Second)
        defer ticker.Stop()
        for range ticker.C {
            if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
                return
            }
        }
    }()

    // 主循环：监听消息 & 捕获关闭
    for {
        _, message, err := conn.ReadMessage()
        if err != nil {
            if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
                log.Printf("WS unexpected close from %s: %v", r.RemoteAddr, err)
            } else {
                log.Printf("WS client disconnected gracefully from %s", r.RemoteAddr) // ✅ 此处才是真实业务断开点
            }
            return
        }
        // 处理业务消息...
    }
}