讲师中心 微信公众号

工具推荐

视频效率加速
Seko
Seko

AI短剧一键生成成片

updream

一键生成高质量推广成片

剧云
剧云

中文短剧剧本制作平台

AniShort
AniShort

AI短剧协同制作平台

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

云萱小哥_7257

云萱小哥_7257

发布时间:2026-11-22 13:40:25

|

244人浏览过

|

来源于php中文网

原创

在 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 或客户端网络。结合应用层心跳日志,可以全面定位问题根源。

热门AI工具

更多
WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

讯飞智作

讯飞智作是一款AI视频创作工具,AI文本配音工具,数字人课程、营销视频制作。

切问学术

切问学术是一款AI论文写作工具,复旦大学NLP团队推出的AI学术智能体。

超级麦吉

一款通过数字员工协作完成调研、数据分析与文档制作的AI办公平台。

音述AI
音述AI Hot

一款AI音频处理工具,主要用于音述AI是一个以“用声音述说故事”为核心的 AI 音乐创作与声音分享社区,适合需要提升相关任务效率的用户。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

讯飞智文

一款面向学习和办公场景的AI文档创作工具,可辅助生成PPT与Word文档,提高资料整理和内容制作效率。

超级简历WonderCV

一款AI办公效率工具,主要用于免费求职简历模版下载制作,应届生职场人必备简历制作神器,适合需要提升相关任务效率的用户。

相关专题

更多
nginx 重启
nginx 重启

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

443

2023.07.27

nginx 配置详解
nginx 配置详解

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

4427

2023.08.04

nginx配置详解
nginx配置详解

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

7485

2023.08.04

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

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

621

2024.02.23

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

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

1536

2024.07.09

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

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

4018

2024.08.07

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

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

142

2026.01.13

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

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

637

2026.01.13

CVE-2026-114938高危漏洞修复
CVE-2026-114938高危漏洞修复

Java4Shell是OpenJDK Base64解码路径中的远程代码执行漏洞,编号CVE-2026-114938,2026年11月17日披露,官方已发布17.0.21.1、21.0.13.1等修复版本,建议优先升级 。本专题围绕Java4Shell(CVE-2026-114938)持续更新,从漏洞原理、受影响版本、受影响产品到修复与自查一站式汇总,适合Java开发、运维与安全人员快速定位风险。ARM64环境不受影响,x86-64环境请

0

2026.11.22

热门下载

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

精品课程

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

共0课时 | 0人学习

nginx手册
nginx手册

共0课时 | 0人学习

进程与SOCKET
进程与SOCKET

共6课时 | 0.5万人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn