摘要：相对「多站点 HTTPS 怎么配」，本文按 nginx.org 官方文档整理反向代理常见 502/504：先分清错误码、再查 error.log 与上游是否存活，再核对 proxy_*_timeout 与 WebSocket 的 Upgrade/Connection。查询日期 2026-10-20；只放官网普通链接（affiliate_later）。

依据：nginx.org · Module ngx_http_proxy_module、WebSocket proxying、Module ngx_http_upstream_module。查询日期：2026-10-20（北京时间）。示例域名与端口均为文档占位；把地址换成你机器上的上游。本文只放 Nginx 官网普通链接（affiliate_later）；不写云厂商单价。

本站已有两篇相关文，先划清边界，避免重复阅读：

本文只做排错手册：浏览器或客户端已经报 502 Bad Gateway / 504 Gateway Timeout，或 WebSocket 连不上 / 握手失败 时，按官方指令含义一步步缩小范围。证书续期仍见免费 HTTPS 证书自动续期；宝塔环境注意面板端口与反代权限见宝塔面板优缺点与安全。

一、502 和 504 先别混

状态码常见含义（反代场景）你优先怀疑什么
502 Bad GatewayNginx 作为网关，从上游拿到了无效响应，或根本连不上上游却以网关错误返回上游进程挂了、端口写错、协议错（http/https/unix:）、防火墙拦了本机回环、上游立刻复位连接
504 Gateway TimeoutNginx 在限定时间内等不到上游完成响应proxy_read_timeout / proxy_send_timeout / proxy_connect_timeout 过短、上游慢查询、上游线程堵死、缓冲/上游排队

官方 ngx_http_proxy_module 把连接建立、读写超时拆成多条指令；排错时先看 error.log 原文，再改超时——不要一上来把所有 timeout 改成 3600。

Nginx 反向代理排错：502/504、上游超时与 WebSocket 升级（2026）-有序
nginx.org《Module ngx_http_proxy_module》：指令列表含 proxy_connect_timeout、proxy_next_upstream、proxy_http_version 等（2026-10-20 截图）

二、固定排查顺序（建议打印贴显示器旁）

  1. 复现一次，记下完整 URL、时间、是整站还是某个 path。
  2. 看 Nginx error.log（路径因发行版而异，常见 /var/log/nginx/error.log）。关键词示例：connect() failed、Connection refused、upstream timed out、no live upstreams。
  3. 绕过 Nginx 直连上游：若上游是本机 127.0.0.1:3000，在服务器上 curl -v http://127.0.0.1:3000/健康路径。直连也失败 → 先修应用/容器/端口，别改 Nginx。
  4. 核对 proxy_pass 目标：IP/端口/unix socket 是否与进程实际监听一致；location 末尾斜杠会改变 URI 拼接（见官方 proxy_pass 说明），路径 404 有时被误当成「反代坏了」。
  5. 再谈超时与 WebSocket（下文）。
  6. 改完 nginx -t 再 reload；监控侧可用 Kuma 盯 5xx（见 Kuma 文），但监控不能替代读日志。

多上游时，用 upstream 块把后端编组，便于权重、backup 与后续排错：

Nginx 反向代理排错：502/504、上游超时与 WebSocket 升级（2026）-有序
nginx.org《Module ngx_http_upstream_module》示例：upstream backend 多 server + backup，再 proxy_pass http://backend（2026-10-20 截图）

三、超时相关：先认指令，再改数字

ngx_http_proxy_module 中与「连得上但等太久 / 建连失败」最常打交道的包括（默认值以你本机 nginx -V 对应版本文档为准，以下只强调语义）：

  • proxy_connect_timeout：与上游建立连接的超时。上游没在听、安全组丢包，多在这一层暴露。
  • proxy_send_timeout：向上游发送请求的超时。
  • proxy_read_timeout：在两次连续读操作之间，等待上游的超时；长轮询、慢接口、大文件生成常见卡在这里 → 客户端侧常表现为 504。
  • proxy_next_upstream / proxy_next_upstream_timeout：何种失败可换下一台上游、以及换上游的总时间窗。只有你真的配了多 upstream 时才有意义。

实践建议：

  1. error.log 已写 upstream timed out → 先确认是业务本身慢，还是超时设得不合理。
  2. 只对确有长耗时的 location（导出、AI 推理回调等）提高 proxy_read_timeout，避免全局开到「永远不超时」。
  3. 上游是 PHP-FPM / Node / Java 时，还要核对这些进程自己的超时；只改 Nginx 不够。
  4. 缓冲相关（proxy_buffering、proxy_buffer_size 等）更多影响大响应与首包行为；偶发 502 伴随 upstream sent too big header 一类日志时再针对性加大，而不是和 504 混改。

四、WebSocket：Upgrade 与 Connection

浏览器或桌面客户端要升级到 WebSocket 时，需要把连接从 HTTP 升级为长连接。官方文档《WebSocket proxying》说明：自 1.3.13 起 Nginx 支持特殊隧道模式；并给出最小配置思路——把客户端的 Upgrade 传给上游，并把 Connection 设为 upgrade。

Nginx 反向代理排错：502/504、上游超时与 WebSocket 升级（2026）-有序
nginx.org《WebSocket proxying》：location 内 proxy_set_header Upgrade / Connection，以及 map $http_upgrade 写法（2026-10-20 截图）

文档示例（查询日页面；注释提到较新版本对 proxy_http_version 1.1 的默认行为有变化，以你安装版本的文档为准）：

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

    server {
        location /chat/ {
            proxy_pass http://backend;
            # 旧版本常需显式：proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
        }
    }
}

排错清单：

  1. 浏览器开发者工具看握手是否仍是普通 HTTP、状态码是否 4xx/5xx。
  2. 确认反代层是否丢掉了 Upgrade（多层 CDN/另一层反代也要放行）。
  3. WebSocket 空闲断开：同时检查 proxy_read_timeout 与上游心跳；超时过短会在「看似已连上」后被网关掐断。
  4. wss:// 场景先保证外层 TLS 正常，再查升级头——证书问题见 HTTPS 专项文，不要和 Upgrade 混为一谈。

五、和「站点监控」怎么配合

  • Kuma / 云拨测：告诉你「外网看到 5xx 或超时」；适合值班。
  • 本篇：告诉你「日志里是 refused 还是 timed out、WebSocket 头缺没缺」。

两者一起用效率最高：监控告警 → SSH 上机 → 按第二节顺序读 error.log → 直连上游 → 再动超时或 Upgrade。独立站若还接支付回调，偶发 502 会导致重试与拒付沟通成本上升，收款侧注意见本站跨境/拒付相关文；本文不展开支付协议。

六、相关阅读

来源与查询日期

风险提示

错误的反代与超时配置可能导致服务长时间不可用或 WebSocket 业务中断；改配置前请备份、在低峰验证，并确保 nginx -t 通过后再 reload。云主机安全组、面板与应用进程权限配置不当还有被扫端口风险。本文不构成运维托管承诺。