Nginx 反向代理排障教程：502、504、回源超时与配置冲突的完整处理步骤

Nginx 反向代理是教程站里最典型的“看起来很简单，真出问题就很烦”的主题。你可能只写了几行 proxy_pass 就把服务转发起来了，但一旦出现 502、504、回源超时、连接池耗尽、代理头不对或配置冲突，很多人就只会不停 reload 和重启。真正有用的教程，应该给出一套完整的排障顺序：从配置语法、上游连通、代理参数、超时设置到日志定位，一层层排下来。这篇文章就是按这个逻辑写的。

步骤 1：先确认语法和配置生效范围

Nginx 出问题时第一步永远是看配置本身，而不是先怪应用。尤其是多站点、多 include、多 server 块的场景，最容易出现“你改了配置，但实际命中的不是这份配置”的问题。所以先做语法检查，再看站点到底命中了哪个 server block。

nginx -t
nginx -T

nginx -T 非常有价值，因为它会把最终生效配置完整展开，让你知道到底哪些 include 生效了。

步骤 2：确认上游服务是不是活着

502 和 504 不一定是 Nginx 的锅，很多时候是上游服务挂了、没监听、监听错地址、或者应用自身处理太慢。排障时不要只盯着 Nginx，必须先验证上游进程本身是否在线，端口是否监听，应用是否能在本机被访问。

ss -lntp
curl -I http://127.0.0.1:3000

步骤 3：代理头和协议识别要统一

很多站点在反向代理后出现登录态异常、重定向错误、真实 IP 获取不到，本质上不是应用坏了，而是代理头没传对。像 Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto 这些头，如果处理不统一，应用层就很容易出现逻辑误判。

步骤 4：超时和缓冲区设置决定 504 和大响应是否稳定

504 很多时候不是真挂，而是超时值不合适。尤其是回源处理时间较长、接口返回大响应、文件下载、AI 请求代理等场景，更容易碰到默认超时不够的问题。这个时候你就要从 proxy_connect_timeout、proxy_read_timeout、client_max_body_size 这些地方去查，而不是只会刷新页面看报错。

步骤 5：日志比猜测更值钱

Nginx 排障最稳的方式，永远是看 access log 和 error log。它们能告诉你到底是连接不上、上游超时、头部过大、配置冲突还是客户端问题。只要你会按时间点看日志，很多问题根本不用猜。

步骤 6：把代理配置做成模板，减少重复犯错

如果你经常给不同服务做反向代理，建议把一套相对稳定的代理模板沉淀下来，包括代理头、超时、缓冲区、静态资源处理、错误页等，这样以后问题会少很多。

操作清单

• 先看语法和最终生效配置。
• 先确认上游服务在线，再看 Nginx。
• 代理头统一，不要缺项。
• 504 重点看超时，不要盲目重启。
• 日志是定位根因的关键。

常见问题 FAQ

1）为什么明明改了配置却没生效？

可能是你改的不是实际命中的 server block，或者 reload 没成功。

2）为什么反向代理后应用总是识别成 HTTP？

通常是没有正确传递 X-Forwarded-Proto，或者应用层没有信任代理。

3）为什么会出现 504，但上游服务其实没挂？

大概率是代理超时值太小，或者上游响应时间本来就比较长。