Nginx代理WebSocket需协同配置Upgrade头、Connection头、HTTP/1.1版本及长超时时间；通过自定义日志、上游埋点与可观测工具实现监控分析，并逐层排查连接失败、秒断、WSS代理等问题。
要让 Nginx 正确代理 WebSocket 连接并支持实时监控与分析，关键在于配置升级协议、保持长连接、透传关键头部，并配合后端服务与可观测性工具协同工作。
WebSocket 代理的核心配置
Nginx 默认不识别 WebSocket 协议，需显式设置 Upgrade 和 Connection 头部，触发 HTTP 协议升级。以下是最小可行配置片段：
- 使用 proxy_http_version 1.1 启用 HTTP/1.1（WebSocket 升级依赖于此）
- 设置 proxy_set_header Upgrade $http_upgrade，将客户端的 Upgrade 请求头透传给上游
- 设置 proxy_set_header Connection "upgrade"，告知上游这是一个升级请求（注意引号不可省略）
- 避免设置 proxy_buffering on 或过短的超时值；建议启用 proxy_read_timeout 86400（或更大），防止连接被静默断开
连接状态与流量的实时采集
Nginx 自身不提供 WebSocket 级别的会话指标（如消息数、延迟、错误码），但可通过以下方式间接获取可观测数据：
- 启用 log_format 自定义日志，记录 $status、$request_time、$upstream_response_time 及 $http_upgrade，筛选出 status=101 的升级成功日志
- 结合 nginx-module-vts 或 nginx-plus 获取每 upstream 的活跃连接数、请求速率等维度统计
- 在 upstream 服务侧埋点：例如 Spring Boot 的
WebSocketHandler中记录连接建立/关闭、收发消息计数，通过 /actuator/metrics 接口暴露
常见问题排查要点
WebSocket 代理失败通常不是单点问题，需逐层验证：
- 浏览器控制台报错
WebSocket connection to 'wss://...' failed：先检查 Nginx 日志中是否有 400/426/502，确认是否因缺少 Upgrade 头或协议不匹配被拒绝 - 连接建立后秒断：检查 proxy_read_timeout 是否过小，或后端未及时响应 ping/pong 帧导致 Nginx 主动关闭
- WSS（TLS）无法代理：确保 Nginx 配置了有效的 SSL 证书，并在 server 块中启用 ssl on（或 modern 写法 listen 443 ssl），且后端地址为
https://或wss://（若反向代理到 wss，需开启 proxy_ssl_* 相关指令）
与监控系统集成建议
将 Nginx 日志与后端指标统一接入，才能形成完整链路视图：
- 用 Filebeat 或 Fluent Bit 收集 Nginx access log，过滤 upgrade=websocket 的条目，解析为结构化字段（如 client_ip、upstream_addr、duration）
- Prometheus 抓取后端暴露的 WebSocket 指标（如 activeSessions、messagesReceived），配合 Grafana 绘制连接生命周期趋势图
- 对异常场景做告警：例如 1 分钟内 upgrade 失败率 >5%、活跃连接数突降 80%，可关联 Nginx 错误日志中的 upstream timeout 或 refused
不复杂但容易忽略。真正起作用的不是某一行配置，而是 Upgrade 头、Connection 头、HTTP 版本、超时时间这四者的协同生效。
