Nginx 代理超时如何配置 websocket 长连接超时

云萱小哥_7257

云萱小哥_7257

2026-11-22

244人浏览

原创

在 nginx 中配置 websocket 长连接超时,核心是同时设置 http 升级握手阶段的代理超时和 tcp 连接的 keepalive 超时。你需要将 proxy_read_timeout、proxy_send_timeout 和 proxy_connect_timeout 设置为一个较大的值(如 3600s),并配合 keepalive_timeout 来维持底层 tcp 连接。这样既保证了握手成功,又防止了空闲连接被中间网络设备或 nginx 自身切断。

Nginx 代理超时如何配置 websocket 长连接超时

如何区分 WebSocket 握手与数据转发阶段的超时控制

Nginx 处理 WebSocket 连接时,会先经历一个 HTTP 到 WebSocket 的协议升级过程,随后进入全双工的数据传输阶段。这两个阶段对超时的敏感度不同:握手阶段需要快速响应,而数据传输阶段可能长时间无交互。因此,必须针对这两个阶段分别配置超时参数,确保握手不被误杀,且长连接能持续存活。

Nginx 代理超时如何配置 websocket 长连接超时

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

    location /ws/ {
        proxy_pass http://backend_server;
        
        # 1. 基础 WebSocket 头透传
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        
        # 2. 握手阶段超时 (HTTP 代理超时)
        # 这些参数在握手完成后通常不再起作用,除非发生错误
        proxy_connect_timeout 5s;   # 建立后端连接的时间
        proxy_send_timeout 5s;      # 向后端发送请求头的时间
        proxy_read_timeout 5s;      # 等待后端响应的时间
        
        # 3. 长连接存活超时 (TCP Keepalive)
        # 这是保持 WebSocket 长连接不断的关键
        proxy_read_timeout 3600s;   # 读取后端数据的超时时间
        proxy_send_timeout 3600s;   # 向后端发送数据的超时时间
        
        # 4. 客户端连接超时
        keepalive_timeout 3600s;
    }
}

上述配置中,前三个 proxy_*_timeout 用于确保握手快速失败或成功。后两个 proxy_read_timeout 和 proxy_send_timeout 覆盖了之前的值,专门用于 WebSocket 数据传输阶段。如果只设置握手超时而不设置数据转发超时,Nginx 会在默认 60 秒后切断空闲连接。通过将其设为 3600 秒,可以允许连接在长达一小时内无任何数据交换。

为什么需要单独配置 keepalive_timeout 和 proxy 超时

很多开发者混淆了 Nginx 的 keepalive_timeout 和 proxy_read_timeout。前者控制的是 Nginx 与客户端之间的 TCP 连接保持时间,后者控制的是 Nginx 与后端服务器之间的数据交互超时。对于 WebSocket,两者都需要适当调大,但作用点不同。keepalive_timeout 防止 Nginx 主动断开与浏览器的连接,而 proxy_read_timeout 防止 Nginx 认为后端“死掉”而断开与后端的连接。

Websocket Hub Patterns
Websocket Hub Patterns

可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。

下载

Nginx 代理超时如何配置 websocket 长连接超时

# 在后端应用层实现心跳检测 (Node.js 示例)
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
    // 设置心跳定时器
    const heartbeatInterval = setInterval(() => {
        if (ws.readyState === WebSocket.OPEN) {
            ws.ping(); // 发送 Ping 帧
        } else {
            clearInterval(heartbeatInterval);
            ws.terminate();
        }
    }, 30000); // 每 30 秒发送一次心跳

    ws.on('pong', () => {
        console.log('Client is alive');
    });

    ws.on('close', () => {
        clearInterval(heartbeatInterval);
    });
});

即使 Nginx 配置了长超时,网络中的防火墙或负载均衡器也可能有独立的空闲超时限制(通常为 5-10 分钟)。因此,仅靠 Nginx 配置是不够的。最佳实践是在应用层实现心跳机制,如上面的 Node.js 代码所示,定期发送 WebSocket Ping/Pong 帧。这不仅能穿透中间设备的空闲超时,还能及时发现断开的连接。Nginx 的 proxy_read_timeout 应设置为大于应用层心跳间隔的值,例如心跳 30 秒,Nginx 超时设为 3600 秒,这样既安全又高效。

当 WebSocket 连接意外中断时如何排查

如果配置了长超时但连接仍然中断,通常是因为中间网络设备(如云厂商的 LB)或应用层未发送心跳。排查时,首先检查 Nginx 错误日志中的 upstream timed out 或 client timed out 记录。其次,确认后端服务是否在处理大量并发时触发了自身的资源限制。最后,验证应用层心跳是否正常发送,可以通过 Wireshark 抓包查看 TCP 层面的 ACK 和 WebSocket 帧。

# 查看 Nginx 错误日志定位超时原因
$ tail -f /var/log/nginx/error.log | grep -E "timed out|websocket"

# 使用 curl 测试 WebSocket 升级是否成功
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     -H "Host: ws.example.com" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
     -H "Sec-WebSocket-Version: 1.1" http://ws.example.com/ws/

通过日志分析,你可以确定超时发生在哪个阶段。如果是 upstream timed out,说明 Nginx 与后端之间的问题,需检查后端性能或 proxy_read_timeout 设置。如果是 client timed out,则需检查 keepalive_timeout 或客户端网络。结合应用层心跳日志,可以全面定位问题根源。

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

相关标签:

nginx websocket

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
nginx 重启
nginx 重启

nginx重启对于网站的运维来说是非常重要的,根据不同的需求,可以选择简单重启、平滑重启或定时重启等方式。本专题为大家提供nginx重启的相关的文章、下载、课程内容,供大家免费下载体验。

2023.07.27

443

5

nginx 配置详解
nginx 配置详解

Nginx的配置是指设置和调整Nginx服务器的行为和功能的过程。通过配置文件,可以定义虚拟主机、HTTP请求处理、反向代理、缓存和负载均衡等功能。Nginx的配置语法简洁而强大,允许管理员根据自己的需要进行灵活的调整。php中文网给大家带来了相关的教程以及文章,欢迎大家前来学习阅读。

2023.08.04

4427

6

nginx配置详解
nginx配置详解

NGINX与其他服务类似,因为它具有以特定格式编写的基于文本的配置文件。本专题为大家提供nginx配置相关的文章,大家可以免费学习。

2023.08.04

7485

6

tomcat和nginx有哪些区别
tomcat和nginx有哪些区别

tomcat和nginx的区别:1、应用领域;2、性能;3、功能;4、配置;5、安全性;6、扩展性;7、部署复杂性;8、社区支持;9、成本;10、日志管理。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。

2024.02.23

621

5

nginx报404怎么解决
nginx报404怎么解决

当访问 nginx 网页服务器时遇到 404 错误,表明服务器无法找到请求资源,可以通过以下步骤解决:1. 检查文件是否存在且路径正确;2. 检查文件权限并更改为 644 或 755;3. 检查 nginx 配置,确保根目录设置正确、没有冲突配置等等。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。

2024.07.09

1536

5

Nginx报404错误解决方法
Nginx报404错误解决方法

解决方法:只需要加上这段配置:try_files $uri $uri/ /index.html;即可。想了解更多Nginx的相关内容,可以阅读本专题下面的文章。

2024.08.07

4018

3

nginx部署php项目教程汇总
nginx部署php项目教程汇总

本专题整合了nginx部署php项目教程汇总,阅读专题下面的文章了解更多详细内容。

2026.01.13

142

12

nginx配置文件详细教程
nginx配置文件详细教程

本专题整合了nginx配置文件相关教程详细汇总,阅读专题下面的文章了解更多详细内容。

2026.01.13

637

23

Nginx跨平台安装实操指南:Windows、macOS与Linux环境快速搭建
Nginx跨平台安装实操指南:Windows、macOS与Linux环境快速搭建

本指南详解Nginx在Windows、macOS及Linux系统的安装全流程。涵盖官方包解压、Homebrew一键部署、APT/YUM源配置及Docker容器化方案。无论新手或开发者,均可快速搭建运行环境,掌握跨平台核心指令,为后续配置与调优奠定坚实基础。

2026.03.16

179

12

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
phpEnv手册
phpEnv手册

共0课时 | 0人学习

nginx手册
nginx手册

共0课时 | 0人学习

进程与SOCKET
进程与SOCKET

共6课时 | 0.5万人学习