Nginx反向代理502错误怎么解决？常见原因与排查步骤

Nginx反向代理为什么会出现502？

使用Nginx作为反向代理时，浏览器访问的是Nginx，而Nginx还需要把请求转发给后端应用，例如ASP.NET Core、Node.js、Java、PHP-FPM或Docker容器。如果Nginx无法正常连接后端服务，或者后端返回了无效响应，就可能出现502 Bad Gateway。

Nginx官方文档中的proxy_pass就是用于指定被代理服务器地址，而proxy_connect_timeout、proxy_read_timeout等参数则控制与后端建立连接以及读取响应时的超时时间。

因此，遇到502时，不要只修改Nginx配置，首先要确认后端服务是否真的正常运行。

Nginx反向代理502错误排查步骤

1. 检查后端服务是否正常运行

这是Nginx 502最常见的原因。

例如配置如下：

location / {
    proxy_pass http://127.0.0.1:5000;
}

可以直接在服务器执行：

curl http://127.0.0.1:5000

如果无法连接，说明问题不在Nginx，而是5000端口上的应用没有正常提供服务。

如果是ASP.NET Core，可以检查：

systemctl status your-app

Docker环境则可以执行：

docker ps
docker logs 容器名

如果日志中出现应用启动失败、端口占用、数据库连接失败等错误，应先解决应用本身的问题。

2. 检查proxy_pass地址和端口

Nginx配置中的IP、域名和端口必须与后端实际监听地址一致。

例如后端监听：127.0.0.1:8080，那么Nginx应该配置：

location / {
    proxy_pass http://127.0.0.1:8080;
}

如果错误地写成8081，就可能出现connect() failed，最终返回502。

修改配置后不要直接重启，建议先执行：

nginx -t

确认语法正确后再：

systemctl reload nginx

3. 查看Nginx错误日志

排查502最有效的方法之一就是查看error.log：

tail -f /var/log/nginx/error.log

不同错误信息对应的问题通常不同。

例如：connect() failed (111: Connection refused) while connecting to upstream，通常意味着Nginx无法连接后端服务，常见原因包括后端停止运行、端口错误或监听地址不正确。Nginx官方案例中也明确将这类错误与upstream服务不可用联系起来。

如果看到 upstream timed out，则更应该检查后端处理速度、网络连接以及proxy_read_timeout配置。

4. 检查监听地址是否正确

一个容易被忽略的问题是后端只监听了127.0.0.1，但Nginx却通过服务器内网IP访问。

可以使用：

ss -lntp

查看实际监听情况。

例如：127.0.0.1:5000，表示只能从本机访问。

如果Nginx和后端服务位于不同服务器，就需要让后端监听对应的内网IP或0.0.0.0，同时正确配置防火墙和安全组。

5. 检查超时配置

如果后端接口执行时间比较长，Nginx默认的读取超时可能不够。Nginx官方文档显示，proxy_read_timeout默认值为60秒，它控制读取后端响应时两次读取操作之间允许的最大间隔。

可以根据实际业务调整：

location / {
    proxy_pass http://127.0.0.1:5000;

    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 120s;
}

不过，不要把超时时间无限调大来掩盖后端性能问题。如果一个普通接口需要几十秒才能返回，更应该检查数据库查询、外部API调用和程序代码。

6. 检查Docker、容器和服务器网络

如果Nginx运行在宿主机，而应用运行在Docker中，不能简单假设127.0.0.1:5000就是容器服务。

例如Docker映射：

-p 5000:8080

宿主机访问应该使用127.0.0.1:5000。

如果Nginx本身也运行在Docker中，则通常应该通过Docker网络中的服务名访问，例如：

proxy_pass http://api:8080;

这类场景出现502时，应同时检查容器状态、Docker网络以及容器内部监听端口。

7. 检查HTTPS和WebSocket配置

如果后端使用HTTPS，需要确认proxy_pass协议是否正确：

proxy_pass https://127.0.0.1:8443;

如果应用使用WebSocket，还需要正确转发Upgrade和Connection请求头，否则可能出现连接异常。Nginx官方文档也指出，WebSocket反向代理需要额外配置。

一套实用的502排查顺序

遇到Nginx 502，可以按照下面顺序快速定位：

1. nginx -t检查配置语法。
2. 查看/var/log/nginx/error.log。
3. 使用curl直接访问upstream。
4. 使用ss -lntp确认后端实际监听端口。
5. 检查systemd、Docker或应用自身日志。
6. 检查防火墙、安全组和服务器之间的网络连接。
7. 最后再检查proxy_connect_timeout、proxy_read_timeout以及HTTPS、WebSocket等特殊配置。

总结

Nginx反向代理502并不一定是Nginx本身故障，更多时候是后端服务停止、端口配置错误、监听地址不匹配、网络连接失败或者后端响应超时。排查时最重要的是先看Nginx错误日志，再绕过Nginx直接访问upstream。只要确定Nginx能否连接后端，502问题通常就能快速定位。