Nginx配置本地可访问子域名遇502错误的排查与解决

问题原因 #

出现502 Bad Gateway的核心原因是：你的后端应用（运行在3000端口的服务）没有监听127.0.0.1这个地址，而是只绑定了设备的外部IPv4地址（192.168.xxx.yyy）。

当你直接访问http://website.test:3000时，hosts把域名解析到127.0.0.1，但实际可能是浏览器/系统优先通过设备IP访问到了服务；而Nginx用proxy_pass http://127.0.0.1:3000时，尝试连接本地回环地址的3000端口，该端口未被应用监听，导致Nginx无法建立连接，返回502错误。

解决方案 #

要实现离线/联网状态下都能正常访问，优先推荐以下两种方案：

方案1：修改后端应用监听地址（最彻底）

把应用启动时的监听地址从192.168.xxx.yyy改成0.0.0.0。0.0.0.0表示监听所有可用网卡接口，包括本地回环（127.0.0.1）、设备IPv4地址，离线时本地接口也能正常响应。

举个Node.js应用的例子，把启动代码里的：

app.listen(3000, '192.168.xxx.yyy');

改为：

app.listen(3000, '0.0.0.0');

修改后重启应用，保持Nginx原配置不变，访问http://website.test即可正常跳转。

方案2：配置Nginx多后端故障转移（无需修改应用）

如果无法修改应用的监听地址，可以在Nginx里配置upstream，同时包含127.0.0.1和设备IP，让Nginx自动尝试可用的后端：

修改你的nginx.conf为：

upstream website_backend {
    server 127.0.0.1:3000;
    server 192.168.xxx.yyy:3000;
}

server {
        listen       80;
        server_name  website.test;
        location / {
             proxy_pass http://website_backend;
             # 可选：添加容错配置，提升稳定性
             proxy_connect_timeout 5s;
             proxy_next_upstream error timeout;
        }
}

server {
        listen       80;
        server_name  server.website.test;
        location / {
            proxy_pass http://127.0.0.1:1337;
            # 若该服务也存在相同问题，可参照上面的upstream配置修改
        }
}

这样不管应用监听的是127.0.0.1还是设备IP，Nginx都能找到可用的后端，离线时设备IP依然是本地有效地址，不会影响访问。

验证方法 #

可以用以下命令查看应用的监听地址，确认是否包含0.0.0.0或127.0.0.1：

• Linux/macOS：netstat -anp | grep 3000
• Windows：netstat -ano | findstr :3000

内容的提问来源于stack exchange，提问作者Joseph MM