Nginx反向代理总报502、504?手把手教你排查配置,附PDF整理思路

做运维或者自己折腾服务器的站长,大概率都经历过这样的深夜惊魂:手机突然弹出一堆报警,打开网站一看,硕大的 502 Bad Gateway 或者 504 Gateway Time-out 挂在页面上。这时候你登录服务器,查了后端服务,发现进程明明活着,CPU 和内存也正常,但 Nginx 就是死活连不上后端。

很多朋友在搜索“nginx反向代理配置指南pdf”时,其实心里真正想找的并不是一份死板的说明书,而是一份能直接解决报错、排坑避雷的实战手册。今天站长就抛开那些教科书式的参数罗列,用问答的形式,把反向代理里最容易踩的坑给你挖出来,顺便聊聊怎么整理一份属于自己的配置指南PDF。

一、 为什么你的反向代理总是“连不上”后端?

💡 推荐阅读:别再怪服务器了!WordPress 慢成蜗牛?我靠这 6 步硬核提速实录,首页加载从 4.8s 干到 1.2s

在动手改配置之前,咱们得先达成一个共识:Nginx 反向代理的本质就是一个“中间传话人”。客户端找 Nginx,Nginx 再去找后端的 Tomcat、Node.js 或者 Python 应用要数据。只要这个“传话”链条里有一环断了,报错就来了。

根据笔者这些年的排障经验,90% 的反向代理故障都集中在下面这三个高频疑问里。

Q1:配置看着一模一样,为什么偏偏报 502 Bad Gateway?

根因剖析:
502 的本质是 Nginx 无法与上游后端建立连接,或者后端主动断开了连接。很多新手站长最容易犯的错,是以为在 proxy_pass 里填了 127.0.0.1:8080 就万事大吉了。

实际上,如果你后端的服务监听的是 0.0.0.0:8080,那没问题。但如果后端只监听了 127.0.0.1:8080,而你的 Nginx 跑在 Docker 容器里,或者跑在另一台机器上,那 Nginx 拿着 127.0.0.1 去找后端,找的其实是它自己,当然找不到。

解决方案代码:

先确认后端端口监听状态,在终端执行:

netstat -tlnp | grep 8080

如果显示的是 127.0.0.1:8080,而 Nginx 不在同一台机器的同一个网络命名空间里,你需要让后端监听 0.0.0.0:8080,或者在 Nginx 里填对后端所在的内网 IP。

一个稳健的基础反向代理配置模板如下,注意 proxy_set_header 这几行千万别省,否则后端应用拿不到真实客户端 IP:

location / {
    proxy_pass http://backend_server_ip:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Q2:为什么接口偶尔超时,报 504 Gateway Time-out?

根因剖析:
504 的意思是 Nginx 成功连上了后端,但后端处理太慢,超过了 Nginx 默认的等待时间。Nginx 默认的 proxy_read_timeout 是 60 秒。如果你的业务涉及大数据量导出、复杂报表生成,或者后端数据库查询卡住了,60 秒一到,Nginx 直接撂挑子不干了,甩给你一个 504。

解决方案代码:
适当延长超时时间,但要注意,这治标不治本。如果后端真的卡死,调大超时只会让用户等更久。建议配合后端性能优化一起做。

location /api/ {
    proxy_pass http://backend_server_ip:8080;
    proxy_connect_timeout 75s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;
    send_timeout 300s;
}

Q3:代理 WebSocket 或者 HTTPS 后端,为什么一直握手失败?

根因剖析:
这是非常典型的“协议不匹配”问题。Nginx 默认使用 HTTP/1.0 向后端发起请求,而 WebSocket 需要 HTTP/1.1 的 Upgrade 机制。另外,如果你代理的后端本身是 HTTPS 的,proxy_pass 后面必须写成 https://,否则 Nginx 会拿 HTTP 去敲 HTTPS 的门,自然吃闭门羹。

解决方案代码:
代理 WebSocket 的标准姿势:

location /ws/ {
    proxy_pass http://backend_server_ip:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

代理 HTTPS 后端时,如果后端用的是自签名证书,你还需要加上 proxy_ssl_verify off; 来跳过证书验证,否则 Nginx 会报 SSL 握手错误。

二、 配置检查与平滑重启的正确姿势

💡 延伸阅读:服务器半夜疯狂往外发数据?别慌,手把手教你揪出Linux里的“内鬼”

改完配置千万别直接 nginx -s reload,万一写错了,线上服务直接挂掉。站长强烈建议养成“先测试,后重载”的习惯。

  • 第一步: 执行 nginx -t。如果看到 syntax is ok 和 test is successful,说明语法没问题。
  • 第二步: 执行 nginx -s reload。Nginx 会优雅地关闭旧进程,启用新配置,不会中断现有连接。

另外,如果你在配置里用到了变量(比如 $host),记得检查 resolver 指令。当 proxy_pass 后面跟的是域名而不是 IP 时,Nginx 需要 DNS 解析。如果没配 resolver,Nginx 启动时解析一次就缓存了,后端 IP 变了它也不知道,照样报 502。

三、 关于“PDF配置指南”的整理思路

💡 深度技术指南:别急着改源码:一份开源Docker项目的二次开发实战心法,从编译到上线的避坑指南

很多朋友想找一份现成的 PDF,无非是想把常用配置存下来,方便离线查阅或者发给同事。但网上流传的很多 PDF 都是几年前的,Nginx 版本一更新,有些模块的写法就变了。

笔者建议你自己动手整理一份专属的 PDF 速查表。不需要长篇大论,只需要包含这几个核心板块:

板块 建议收录内容
基础代理 HTTP 代理、HTTPS 代理、WebSocket 代理的标准配置模板
负载均衡 upstream 配置、权重分配、健康检查、ip_hash 会话保持
缓存加速 proxy_cache 路径设置、缓存过期时间、清理缓存指令
安全加固 隐藏 Nginx 版本号、限制请求方法、防止 CC 攻击的基础限流
日志排错 自定义日志格式记录 upstream 响应时间、错误日志级别调整

整理成 PDF 后,打印出来贴在工位上,或者存到手机里,下次再遇到突发故障,直接翻到对应章节复制粘贴,效率比现搜高得多。

四、 给站长的两点实在建议

最后,聊点配置之外的事。反向代理的稳定性,很大程度上也取决于你脚下的“地基”稳不稳。

第一,云服务器别贪便宜。
有些超低价的小厂机器,网络抖动严重,磁盘 IO 也拉胯。Nginx 本身性能极强,但如果底层网络丢包,反向代理就会频繁出现间歇性 502。建议选择主流云厂商的计算型实例,网络收发包能力(PPS)有保障,代理转发才顺畅。

第二,域名和 SSL 证书要走正规渠道。
反向代理经常要配 HTTPS,如果你用的是来路不明的免费证书,浏览器会报安全警告,用户直接流失。买域名和证书,一定要选 ICANN 认证的正规服务商,别为了省几十块钱把站点信誉搭进去。

好了,关于 Nginx 反向代理的排坑指南就先聊到这里。配置这东西,看一百遍不如自己动手改一遍。遇到报错别慌,先看 Nginx 的 error.log,答案八成都在里面写着了。

相关技术专题与延伸阅读

滚动至顶部