计算机网络 / 系统课时

Nginx 转发 WebSocket 要改什么

Nginx 转发 WebSocket 要改什么

WebSocket 经 Nginx 反向代理时,最常见的问题不是业务代码,而是升级握手被当成普通 HTTP 转发,或空闲连接被代理层提前关闭。本节完成一份最小可用配置,并用握手与长连接两个维度验证代理链路。

学习目标

  • 理解为什么 WebSocket 代理必须显式转发 Upgrade 与 Connection 相关头。
  • 配置 HTTP/1.1 代理与合理的读超时,避免连接刚建立就失效。
  • 用 Nginx 配置检查和客户端连接验证快速定位代理层问题。

握手为什么需要额外代理头

浏览器先发送普通 HTTP 请求,并通过 Upgrade: websocket 请求切换协议。Upgrade 与 Connection 属于逐跳头,不会被反向代理自动原样传递,因此 Nginx 需要显式重建这些头;同时上游连接必须使用 HTTP/1.1。

Nginx 转发 WebSocket 的升级握手与长连接链路

仅把 proxy_pass 指向后端并不够。如果上游收不到升级意图,常见结果是返回普通 HTTP 响应、400/426,或者前端看到连接在握手阶段立即关闭。

配置升级头与超时

下面是一份适合放在 http 上下文中的最小配置。map 根据客户端是否提供 Upgrade 头决定 Connection 的值,避免把所有请求都强制标成升级连接。

nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name realtime.example.com;

    location /ws/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;

        proxy_read_timeout 75s;
        proxy_send_timeout 75s;
    }
}

这是配置片段,依赖完整的 http 配置和实际后端地址。proxy_read_timeout 表示两次从上游读取数据之间允许的最大空闲时间,并不是整个 WebSocket 会话的总时长。若业务可能长期无消息,应让应用发送 ping/pong 或心跳,并把超时设置为略高于心跳周期。

配置保存后先检查语法:

bash
nginx -t

预期输出:

text
nginx: the configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful

<PATH> 会随安装方式不同而变化。检查通过后再按系统方式平滑重载 Nginx,避免直接重启导致现有连接被无谓中断。

验证握手和长连接

代理是否正确,至少要验证两件事:握手得到 101,以及连接在超过一个心跳周期后仍能收发消息。可以使用支持 WebSocket 的客户端,例如安装了 wscat 后执行:

bash
wscat -c ws://realtime.example.com/ws/

预期输出:

text
Connected (press CTRL+C to quit)
>

随后发送一条后端已支持的测试消息,并观察响应。若能连上但在固定时间后断开,重点检查 proxy_read_timeout、应用心跳周期以及负载均衡器或云网关的空闲超时;如果握手阶段就失败,则先看状态码和 Nginx 错误日志,不要先改业务消息格式。

按现象定位配置问题

返回 400 或 426 时,优先确认上游是否收到 Upgrade: websocket 和正确的 Connection 头;返回 502 时,先确认 proxy_pass 的主机、端口和后端进程是否可达。若浏览器报连接很快关闭,而 Nginx 日志没有握手错误,通常应继续检查超时链路。

只要升级头、HTTP/1.1 和超时策略三者一致,Nginx 就能把握手后的连接当作双向隧道持续转发,而不再按普通短连接处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Nginx 转发 WebSocket 要改什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通