根本原因是Nginx默认丢弃Upgrade和Connection逐跳头，导致后端收不到协议升级意图；必须配置proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"三者缺一不可，并调大proxy_read_timeout以防空闲断连。

WebSocket 握手失败（返回 200/400/502 而不是 101）

根本原因是 Nginx 默认丢弃 Upgrade 和 Connection 这两个逐跳头，导致后端收不到协议升级意图。只写 proxy_pass 完全没用。

• proxy_http_version 1.1 必须显式设置：HTTP/1.0 不支持 Upgrade，缺了这一行，Nginx 会静默降级转发
• proxy_set_header Upgrade $http_upgrade：必须用变量，不能硬写 "websocket"，否则非标准客户端（如某些嵌入式设备）带 Upgrade: h2c 会被截断
• proxy_set_header Connection "upgrade"：必须是字符串 "upgrade"，不是 $http_connection（它常为 keep-alive）或 add_header（那是响应头，无效）
• 三者必须写在 location 块内，server 或 http 块顶层配置不生效

连接几秒后自动断开（“突然掉线”“反复重连”）

这是 proxy_read_timeout 太小的典型表现。WebSocket 是空闲长连接，Nginx 默认值 60 秒，只要后端 60 秒没发数据，它就主动关 TCP 连接——前端看不到错误，只看到连接消失。

Zynq Linux Hardware Debug

Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。

下载

• 设为 proxy_read_timeout 86400（24 小时）最稳妥；若后端有心跳，至少设为 proxy_read_timeout 300（5 分钟），且 ≥ 心跳间隔 × 3
• 同步调整 proxy_send_timeout 86400：防止后端推送大消息或延迟响应时被中断
• 别设 proxy_read_timeout 0：部分 Nginx 版本行为未定义，可能引发不可预测断连
• keepalive_timeout 对 WebSocket 无效，改它没用

HTTPS 场景下 wss:// 连接被拒绝或卡在 TLS 层

浏览器访问 wss://your.com/ws，但 Nginx 只监听 80 端口，或 SSL 配置缺失/不匹配，连接根本到不了 HTTP 升级阶段。

• server 块必须含 listen 443 ssl，不能只有 listen 80
• ssl_certificate 和 ssl_certificate_key 路径要正确，且证书域名必须匹配请求 Host
• 后端仍走 HTTP：Nginx 终止 SSL 后以明文 HTTP/1.1 转发，后端无需处理 HTTPS
• 补上 proxy_set_header Host $host 和 proxy_set_header X-Forwarded-Proto $scheme，避免后端因协议误判生成 http 链接或重定向循环

数据延迟、粘包或接收不实时

WebSocket 是实时流协议，Nginx 默认缓冲和 Nagle 算法会引入毫秒级延迟，尤其影响协同编辑、实时游戏等场景。

• 加 proxy_buffering off：禁用响应缓冲，避免帧被攒包或延迟发送
• 加 tcp_nodelay on：绕过 TCP Nagle 算法，小数据包立即发出
• 删掉 proxy_cache 相关配置：WebSocket 不走缓存路径，设了也无效，还可能干扰
• proxy_cache_bypass $http_upgrade 可保留，用于明确跳过缓存判断

Nginx 对 WebSocket 的支持本质是“透传升级请求 + 容忍长空闲”，所有配置都围绕这两点展开。最容易忽略的是：三行 header 缺一不可、proxy_read_timeout 必须调大、SSL 场景下监听端口和证书必须匹配——这三点出错，基本就是连不上或连上秒断。