真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

nginx Troubleshooting

Nginx 反向代理 WebSocket 配置与排障

Nginx 反向代理 WebSocket 出现 1006 异常关闭、连接建立后很快断开或收不到消息时，必须设置 proxy_http_version 1.1、透传 Upgrade 与 Connection: upgrade 头，并调大 proxy_read_timeout 让长连接不被 60s idle 超时断开，握手成功会返回 101。

WebSocket 代理必须配置 Upgrade 和 Connection 头：proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; 同时调大 proxy_read_timeout。

适用环境Linux / Nginx / 反向代理
风险等级低
最后验证2026-07-03
建议权限普通用户

2026-07-03 更新·约 4 分钟阅读

Scenario

这篇文章解决什么问题

适用于“Nginx 反向代理 WebSocket 配置与排障”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。WebSocket 代理必须配置 Upgrade 和 Connection 头：proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; 同时调大 proxy_read_timeout。

Symptoms

典型现象

  • Nginx 反向代理 WebSocket 出现 1006 异常关闭、连接建立后很快断开或收不到消息时，必须设置 proxy_http_version 1.1、透传 Upgrade 与 Connection: upgrade 头，并调大 proxy_read_timeout 让长连接不被 60s idle 超时断开，握手成功会返回 101。
  • 相关日志、命令或页面中反复出现 nginx、websocket、proxy 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 确认请求是否真正到达当前 Nginx，而不是 CDN、负载均衡或另一台机器。
  • 保留一次失败请求的时间、域名、路径、状态码和客户端 IP，方便和 access/error log 对齐。
  • 修改配置前先导出 nginx -T 的最终合并配置，避免只看了未生效的片段。

Root Causes

常见根因分层

入口层未命中或命中了旧配置

server_name、location 优先级、SNI、默认站点和 include 顺序都会让请求落到意外配置。症状通常是本机看起来配置正确，但线上响应头、证书或错误页与预期不一致。

  • 用 nginx -T 看最终配置
  • 用 curl -H Host 或 openssl -servername 精确复现
  • 确认 reload 成功且没有旧进程残留

反向代理到后端链路异常

502、超时、上传失败和跨域问题经常发生在 Nginx 到 upstream 的这一跳，包括端口、DNS、协议、body size、header 和超时设置。

  • 从 Nginx 机器 curl upstream
  • 区分 connect refused、timeout、reset、invalid header
  • 检查 upstream keepalive 与后端连接限制

前置网关和应用限制不一致

CDN、Ingress、API Gateway、Nginx、应用框架可能都有独立限制。只改其中一层会造成看似随机的失败。

  • 逐层确认响应来源
  • 统一上传大小、超时和 CORS 策略
  • 修复后从外网重新验证

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。Nginx 反向代理 WebSocket 配置与排障 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_http_version 1.1;

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 确认 Nginx 配置了 proxy_http_version 1.1，WebSocket 需要 HTTP/1.1。
  • 设置 Upgrade 和 Connection 请求头透传到后端。
  • 调大 proxy_read_timeout，WebSocket 长连接默认 60s 会超时断开。
3. 读取服务端证据，而不是只看客户端提示
proxy_read_timeout 3600s;
proxy_http_version 1.1;
curl -v -H "Upgrade: websocket" -H "Connection: Upgrade" -H "Sec-WebSocket-Key: test" -H "Sec-WebSocket-Version: 13" http://example.com/ws

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 调大 proxy_read_timeout，WebSocket 长连接默认 60s 会超时断开。
  • 确认后端服务正确处理 WebSocket 握手并返回 101 Switching Protocols。
  • 排查前端 1006 错误时检查 Nginx access.log 是否有 WS 请求和 101 响应。
4. 做最小修复并立即回归验证
proxy_http_version 1.1;
curl -v -H "Upgrade: websocket" -H "Connection: Upgrade" -H "Sec-WebSocket-Key: test" -H "Sec-WebSocket-Version: 13" http://example.com/ws

Commands

排查命令与使用意图

命令 1

用于补充“Nginx 反向代理 WebSocket 配置与排障”的排查证据链。proxy_set_header 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 1
proxy_set_header Upgrade $http_upgrade;

命令 2

用于补充“Nginx 反向代理 WebSocket 配置与排障”的排查证据链。proxy_set_header 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 2
proxy_set_header Connection "upgrade";

命令 3

用于补充“Nginx 反向代理 WebSocket 配置与排障”的排查证据链。proxy_read_timeout 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
proxy_read_timeout 3600s;

命令 4

用于补充“Nginx 反向代理 WebSocket 配置与排障”的排查证据链。proxy_http_version 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
proxy_http_version 1.1;

命令 5

用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。

命令 5
curl -v -H "Upgrade: websocket" -H "Connection: Upgrade" -H "Sec-WebSocket-Key: test" -H "Sec-WebSocket-Version: 13" http://example.com/ws

Risk Notes

容易踩坑的地方

  • 不要在生产环境直接 restart Nginx，优先 nginx -t 后 reload，restart 会中断正在处理的连接。
  • 不要为了临时修复把 body size、CORS 或 TLS 校验无上限放开，应设置合理的业务上限并记录调整原因。
  • 不要忽略 error.log 中反复出现的 upstream 超时或 SSL 错误，这些往往是更大问题的早期信号。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 Nginx 反向代理 WebSocket 配置与排障 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 把 nginx -t 和 reload 后健康检查写入发布流程，每次变更都做一次端到端验证。
  • 为关键站点保留一条外网探测，监控状态码、证书有效期和响应时间，避免等到用户反馈才发现问题。
  • 把上传大小、代理超时、CORS 允许来源写成显式配置，避免散落在多个 location 中导致不一致。
  • 建立 Nginx 配置模板管理机制，所有 server block 使用统一模板，减少手写配置的语法错误和遗漏。

常见问题

WebSocket 连接经常断开怎么办？

常见原因是 proxy_read_timeout 过短、中间有 CDN/负载均衡断开长连接，或后端有 idle timeout。调大超时并检查中间层。

wss 和 ws 有什么区别？

wss 是 WebSocket over TLS，需要 HTTPS 环境。Nginx 在 443 端口终止 TLS 后代理到后端可以是 ws 或 wss。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • nginx websocket 反向代理
  • nginx proxy_set_header Upgrade
  • websocket 1006 异常关闭
  • nginx websocket 超时断开
  • nginx proxy_http_version 1.1
  • nginx websocket proxy_read_timeout
  • nginx wss 代理配置
  • websocket 101 Switching Protocols

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

工具

Nginx 反向代理配置生成器

可视化生成 Nginx 反向代理配置，支持 upstream 后端、SSL 证书、WebSocket 升级、proxy_pass 路径转发、proxy_read_timeout 与 client_max_body_size 等常用指令，浏览器本地生成可直接复制到 nginx.conf。

nginx命令

Nginx 测试配置与平滑重载命令

Nginx 修改配置后安全上线的标准命令，先 nginx -t 校验语法、nginx -T 查看最终合并配置，再 systemctl reload nginx 平滑加载新配置（reload 失败会保留旧配置），最后 tail error.log 检查启动错误，避免直接 restart。

nginx速查

Nginx 配置与命令速查表

Nginx 配置与命令一页速查：nginx -t/-s reload/-T 语法测试与重载、location 匹配优先级、proxy_pass 反向代理片段与超时上传限制、access/error 日志排查，改配置和查 502/413 时直接对照。

nginx命令

Nginx 限流配置命令

Nginx 常用限流配置命令，limit_req_zone 在 http 块定义速率与共享内存，limit_req 在 location 启用并配合 burst/nodelay 控制突发，limit_conn 限制单 IP 并发连接数，limit_rate 限制响应带宽，配合 geo/map 实现 IP 白名单豁免。

nginx排障

Certbot 证书自动续期失败排查

Certbot 自动续期 Let's Encrypt 证书失败时，用 certbot renew --dry-run 复现真实错误，覆盖 80 端口 HTTP-01 验证不通、Nginx 未放行 .well-known/acme-challenge、DNS TXT 记录未生效和 certbot.timer 未触发等常见根因。

nginx排障

HTTPS 混合内容(Mixed Content)排查

HTTPS 页面加载 http:// 资源被浏览器提示 Mixed Content blocked 时，用 F12 Console 定位被阻止的 script/stylesheet/image，区分 active/passive 混合内容并逐个改成 https 或相对协议，也可在 Nginx 加 CSP upgrade-insecure-requests 兜底。

nginx