Nginx 反向代理实战：配置、验证与 502/504 故障定位

反向代理故障经常被误判为“Nginx 配置错了”。可靠的排查顺序应从上游进程开始，再检查网络、代理配置和超时，避免无目的地反复重启。

一、先证明上游服务健康

ss -lntp | grep 9000
curl -i --max-time 3 http://127.0.0.1:9000/health

期望看到端口监听以及 2xx 健康响应。如果这一步失败，先修复应用；Nginx 无法代理一个不存在或不可达的服务。

二、写一份最小代理配置

upstream app_backend {
    server 127.0.0.1:9000;
    keepalive 16;
}

server {
    listen 80;
    server_name example.test;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        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;
        proxy_connect_timeout 3s;
        proxy_read_timeout 30s;
    }
}

proxy_pass 是否带 URI 会影响路径拼接。新手应先使用上面的最小形式，确认请求路径符合预期后再做重写。

三、永远先检查再加载

sudo nginx -t
sudo nginx -s reload
curl -i -H 'Host: example.test' http://127.0.0.1/health

只有 nginx -t 明确成功后才加载。reload 会让新工作进程读取新配置，并让旧进程优雅退出，比直接停止服务更安全。

四、区分 502 与 504

现象	常见原因	第一检查点
502 Bad Gateway	拒绝连接、进程退出、协议不匹配、权限问题	直连上游与错误日志
504 Gateway Timeout	连接或响应超时、慢查询、下游阻塞	应用耗时与超时阶段

sudo tail -n 100 /var/log/nginx/error.log
sudo tail -n 100 /var/log/nginx/access.log
curl -v --max-time 5 http://127.0.0.1:9000/slow-endpoint

看到 connect() failed 时关注地址、端口与权限；看到 upstream timed out 时应定位应用为何没有按时响应，而不是先把超时无限调大。

五、容器环境的额外检查

在 Nginx 容器里，127.0.0.1 指向 Nginx 自己，不是另一个应用容器。
使用 Compose 服务名和容器端口，例如 app:9000。
分别在宿主机和代理容器内执行连通性测试，区分端口映射与容器网络问题。

回滚与验收

修改前复制当前已验证配置。
变更后执行语法检查和健康检查。
验证真实 Host、静态资源、登录跳转和大请求。
失败时恢复旧配置，再次 nginx -t 后 reload。