Envoy 必须显式配置 upgrade_configs 支持 WebSocket，Go 服务需主动保活并适配健康检查与 Origin 校验。未配置时握手失败返回 403；Go 端需设 KeepAlive、Ping/Pong 处理及 WriteDeadline；健康检查应禁用或改用 TCP；CheckOrigin 需基于请求 Origin 动态校验。
Envoy 的 HTTP 连接管理器必须显式启用 WebSocket 升级
Envoy 默认不自动处理 Upgrade: websocket 请求，哪怕你配置了正确的路由，客户端发来 GET /ws + Connection: Upgrade，也会被直接 403 或 404。关键不是“加个 filter”，而是让 envoy.http_connection_manager 知道该放行并保持连接。
必须在 typed_config 中设置 upgrade_configs，否则 Envoy 会把 WebSocket 握手当成非法请求丢弃：
filter_chains:
- filters:
- name: envoy.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
upgrade_configs:
- upgrade_type: websocket
route_config: { ... }-
upgrade_type: websocket是硬性要求，不能拼错、不能省略 - 如果同时支持
websocket和自定义协议（如grpc-web），需分别列出 - 缺少此项时，Nginx 常见的
101 Switching Protocols永远不会发出，前端报Error during WebSocket handshake: Unexpected response code: 403
Go WebSocket 服务端需容忍 Envoy 的连接复用与超时行为
Envoy 对长连接有默认 idle 超时（idle_timeout），而 Go 的 gorilla/websocket 默认不发 ping/pong。一旦连接空闲超过 5 分钟（Envoy 默认值），Envoy 会静默断开，但 Go 服务端可能还维持着 *websocket.Conn，导致后续写操作 panic： write tcp: use of closed network connection。
解决方法不是调大 Envoy 超时，而是让 Go 主动保活：
- 初始化
upgrader时设置upgrader.KeepAlive = 30 * time.Second - 调用
conn.SetPingHandler和conn.SetPongHandler，避免因未响应 ping 导致 Envoy 断连 - 务必用
conn.SetWriteDeadline包裹所有WriteMessage，捕获net.ErrClosed并主动关闭连接 - 不要依赖
http.TimeoutHandler—— 它对 WebSocket 升级后的连接无效
Envoy 配置中 cluster 的 health_check 必须禁用或适配 WebSocket
Envoy 默认对 cluster 成员做 HTTP GET /healthz 探针，但 WebSocket 服务通常不暴露 HTTP 健康端点，或者只监听 /ws。若未配置，Envoy 日志会出现大量 no healthy upstream，且 cluster 状态为 FAILED_ACTIVE_HC，导致所有流量被拒绝。
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
两种安全做法：
- 禁用健康检查：
health_checks: []（开发/测试环境可接受） - 改用 TCP 探针：
tcp_health_check: {}，只要端口能连通即视为健康 - 若坚持用 HTTP 探针，Go 服务必须额外暴露一个普通 HTTP handler（如
GET /health返回 200），且路径不能和 WebSocket 路径冲突（例如别用GET /ws） - 注意：Envoy 的
healthy_panic_threshold默认是 50%，集群只剩一个实例时容易触发 panic mode，建议设为 0
客户端连接地址和 Origin 校验要同步绕过 Envoy 限制
前端通过 new WebSocket("wss://example.com/ws") 连接，实际经过 Envoy 后，Go 服务收到的 Origin header 是 https://example.com，而非浏览器原始地址。若 Go 服务用了 CheckOrigin 严格校验（比如只允许 localhost:3000），会直接拒绝握手。
解决方案必须两端配合：
- Envoy 配置里，确保
route下没加host_rewrite或auto_host_rewrite，否则 Origin 可能被篡改 - Go 服务的
upgrader.CheckOrigin函数应基于r.Header.Get("Origin")白名单判断，而不是硬编码本地开发域名 - 若用 HTTPS + 自签名证书，前端可能因证书问题无法建立 WebSocket，此时需确认 Envoy 的 TLS 终止是否完整（SNI、ALPN、证书链）
- 生产环境禁止返回
return true，但开发阶段可临时设为宽松模式，上线前必须收敛
最易忽略的是：Envoy 的 access_log 默认不记录 WebSocket 升级请求，查不到 403/426 错误；得打开 access_log_path 并加 format: "%REQ(:method)% %REQ(:path)% %RESPONSE_CODE%" 才能看到真实握手状态。
