微服务中不应直接暴露WebSocket路由，因网关对长连接支持不完善易导致断连；应绕过网关直连专用WebSocket服务，并配置反向代理透传Upgrade头；需解耦连接状态与服务实例、主动心跳探活、正确生成连接ID。
微服务里不该直接暴露 WebSocket 路由
WebSocket 连接是长生命周期的，而微服务网关（如 Envoy、Traefik）默认对长连接支持不完整——容易丢 ping/pong、超时中断、Upgrade 头被过滤。直接把 /ws 路由注册到网关后端服务，前端连不上是常态，不是配置没调好。
正确做法是：WebSocket 流量绕过网关，直连 WebSocket 专用服务实例。这个实例可以和业务微服务同进程，也可以独立部署，但必须有独立域名或子路径（如 wss://ws.yourapp.com），且反向代理（Nginx / ALB）需显式透传 Upgrade 和 Connection 头。
- Nginx 配置里必须包含：
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade" - 不要用
http.ListenAndServeTLS直接绑 HTTPS 端口——证书管理、ACME 自动续期、HTTP/2 支持都得自己扛；交给 Nginx 或云厂商 LB 更稳 - 若强制走网关，确认它支持 WebSocket 协议升级（例如 Traefik v2.9+ 的
websockets: true配置项），否则连接会在 60 秒左右静默断开
gorilla/websocket 不适合嵌入 gRPC 或 HTTP/REST 微服务框架
gorilla/websocket 的 Upgrader.Upgrade() 必须作用于原始 http.ResponseWriter 和 *http.Request，而 gRPC-Gateway、Kratos、Go-Kit 等框架在中间件链里会包装或消耗响应体。一旦你调了 w.WriteHeader() 或写了任何响应头，Upgrade() 就 panic：“http: response.WriteHeader called”。
常见错误现象：服务启动正常，但访问 /ws 返回 500，日志里出现 websocket: response does not implement http.Hijacker 或直接 panic 崩溃。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 别试图在 Kratos 的
HTTPServer里注册http.HandleFunc—— 它和框架的路由冲突，且 Hijack 权限已被接管 - 如果用 go-micro/v4 或 Service Mesh（Istio），WebSocket 必须走单独的
http.Server实例，监听不同端口（如:8081），与主微服务端口分离 - Hprose-Golang 的
websocket.Handle()是封装过的，但它底层仍依赖原生http.ServeMux，不能混进 Gin/Echo 的路由树
连接状态必须脱离单体服务生命周期管理
微服务可随时扩缩容、滚动更新、被 K8s 重启——但 WebSocket 连接是内存态的，map[*websocket.Conn]bool 存在本地内存里，节点一死，所有连接就断，且无法通知客户端“服务迁移中”。这不是重连能解决的，是架构级缺失。
生产环境必须解耦连接状态与服务实例：
- 用 Redis Pub/Sub 中转广播消息：一个服务实例收到消息，发到
ws:topic:chat频道，所有实例订阅并推送给本地连接 - 用一致性哈希 + clientID 分片：每个连接分配唯一
clientID，按CRC16(clientID) % 16384落到某个分片，发送方查分片路由再投递，避免全量广播 - 别依赖
sync.Map或gorilla/websocket内置的conn.Close()清理——K8s 发送 SIGTERM 后，进程只有几秒存活时间，来不及遍历 map
心跳与连接探活必须由服务端主动发起
浏览器 WebSocket 默认不发心跳，TCP 层保活（KeepAlive）在 NAT、防火墙、移动网络下基本失效。客户端静默掉线后，服务端 ReadMessage() 会一直阻塞，直到 OS 层 TCP 超时（常达 2 小时），导致 goroutine 泄漏、连接池爆满。
必须手动设 SetPingHandler 并定期 WriteMessage(websocket.PingMessage, nil)：
- 别只依赖
Upgrader.EnableCompression = true—— 压缩不等于保活，它只影响 payload - 读超时（
SetReadDeadline）要设成“最后一次收到数据后 30 秒”，而不是固定时间点；写超时（SetWriteDeadline）建议设为 10 秒，避免慢客户端拖住整个 write pump - 收到
websocket.PongMessage时，立刻刷新读超时；收到websocket.CloseMessage要调conn.WriteMessage(websocket.CloseMessage, nil)再conn.Close()，不能只 close
最易被忽略的是：连接 ID 的生成时机。不能用 conn.RemoteAddr().String() 当唯一标识——NAT 后多个用户 IP 相同；也不能用 uuid.New() 在 Upgrade 后生成——此时客户端可能已断连，ID 无意义。正确做法是在 Upgrade 前，从 JWT token 或 query 参数里提取业务 ID，校验后再升级。
