HAProxy 如何配置 WebSocket 支持避免连接频繁断开？

核心结论：配置timeout tunnel 1h和timeout client-fin 30s可将 WebSocket 长连接保持时间从默认的 60-300 秒提升至 1 小时，有效避免连接过早关闭（来源：Racher Haproxy WebSocket 配置指南，2021 年 12 月 28 日）。

原因分析

WebSocket 连接频繁断开的根本原因在于代理层的超时机制与长连接特性不匹配。防火墙、负载均衡器（如 Nginx、HAProxy）或运营商网关通常会为闲置的 TCP 连接设置超时时间，典型范围为 60-300 秒。如果在这段时间内连接上没有数据流动，它们会主动断开连接以释放资源（来源：WebSocket 连接频繁断开？手把手教你用 Java 实现心跳机制保活，2026 年 2 月 26 日）。

操作系统的 TCP Keep-Alive 机制探测间隔默认往往 2 小时，且只在连接完全空闲时触发，对于 WebSocket 这种可能长时间没有业务数据但需要保持活跃的场景，它不够及时。典型的问题日志中会出现EOFException异常，这往往意味着连接被强制终止而非正常关闭（来源：WebSocket 连接频繁断开？Nginx 配置中的 proxy_read_timeout 和 keepalive_timeout 详解，2026 年 3 月 22 日）。

HAProxy 核心配置参数

HAProxy 支持 WebSocket 的关键在于正确配置超时参数，确保长连接不被意外中断。以下是经过验证的配置方案：

1. timeout tunnel 参数（最关键）

WebSocket 请求和一般的 Http 请求不一样，它会长时间保持一个 connection，HAProxy 反向代理 WebSocket 请求需要用到timeout tunnel参数，否则这个链接可能就会提前关闭。推荐配置：

defaults
    timeout tunnel 1h
    timeout client-fin 30s

（来源：Racher Haproxy WebSocket 的配置方法，2021 年 12 月 28 日）

2. 完整 defaults 配置示例

defaults
    log global
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms
    timeout tunnel 1h

其中timeout connect 5000ms设置连接超时为 5000 毫秒，timeout client/server 50000ms设置客户端/服务器端超时为 50 秒（来源：HAproxy 在 linux 和 docker 部署和优化，2024 年 11 月 15 日）。

3. 连接保持机制

通过option http-keep-alive和timeout tunnel配置项维持长连接，确保 WebSocket 连接不被意外中断（来源：7 步掌握 WebSocket 负载均衡，截至 2026 年 2 月 19 日）。

完整 HAProxy 配置文件示例

以下是支持 WebSocket 的完整 HAProxy 配置：

global
    log /dev/log local0
    maxconn 2000

defaults
    log global
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms
    timeout tunnel 1h
    timeout client-fin 30s

frontend ws_front
    bind *:80
    mode http
    option http-keep-alive
    default_backend ws_back

backend ws_back
    mode http
    option forwardfor
    option http-server-close
    balance roundrobin
    server ws1 192.168.1.10:8080 check
    server ws2 192.168.1.11:8080 check

配置说明：

maxconn 2000：设置最大连接数为 2000
option forwardfor：指定 HAProxy 在发送连接请求时包含一个X-Forward-For报头，该报头包含客户端的 IP 地址
option http-server-close：通过消除占用服务器资源的任何空闲连接来限制资源
balance roundrobin：使用循环调度来分配负载

（来源：如何为 WebSocket 连接配置 HAProxy，2024 年 3 月 20 日）

WebSocket 协议升级处理

WebSocket 以 HTTP 请求开始，最重要的部分是Connection: Upgrade报头，它让客户端告诉服务器它想要更改到其他协议。服务器响应状态码101 Switching Protocols用于确认协议切换（从 HTTP 切换到 websocket）（来源：使用 HAProxy 作为 Websockets 负载平衡，2023 年 2 月 16 日）。

典型握手请求：

GET / HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: avkFOZvLE0gZTtEyrZPolA==

注意事项与常见坑

1. 仅设置 proxy_read_timeout 是不够的

许多开发者只关注了proxy_read_timeout，却忽略了其他同样关键的配置项。即使配置了超长的proxy_read_timeout，WebSocket 连接仍然会莫名其妙断开（来源：WebSocket 连接频繁断开？Nginx 配置中的 proxy_read_timeout 和 keepalive_timeout 详解，2026 年 3 月 22 日）。

2. 心跳机制必要性

由于防火墙、负载均衡器通常为闲置连接设置 60-300 秒超时，建议在应用层实现心跳机制，定期发送小数据包保持连接活跃（来源：WebSocket 连接频繁断开？手把手教你用 Java 实现心跳机制保活，2026 年 2 月 26 日）。

3. 服务器负载过高

当服务器处理的 WebSocket 连接数量过多时，可能会导致资源耗尽，无法维持所有连接，进而频繁断开连接。需合理设置maxconn参数（来源：WebSocket 连接频繁断开的问题及解决方案，2024 年 10 月 28 日）。

4. 移动网络不稳定性

在移动设备上，网络切换（Wi-Fi 到 4G）、信号弱、设备休眠等都会导致 TCP 连接中断，需在客户端实现自动重连机制（来源：WebSocket 连接频繁断开？手把手教你用 Java 实现心跳机制保活，2026 年 2 月 26 日）。

参考来源

来源：Racher 技术博客 - Racher Haproxy WebSocket 的配置方法（2021 年 12 月 28 日）

来源：HAProxy 官方配置指南 - 如何为 WebSocket 连接配置 HAProxy（2024 年 3 月 20 日）

来源：技术社区 - WebSocket 连接频繁断开？手把手教你用 Java 实现心跳机制保活（2026 年 2 月 26 日）

来源：DevOps 实践 - HAproxy 在 linux 和 docker 部署和优化（2024 年 11 月 15 日）