排障记：一次 Nginx 反代 502 的真实复盘与可复用排查顺序
背景
前几天给一台阿里云 ECS 上的服务接域名，配完 Nginx 反代后 curl 本地正常，但外网一访问就 502 Bad Gateway，折腾了快两个小时。这轮把真实踩坑过程复盘出来，结论是可复用的，希望能帮到同样在反代上栽过跟头的人。
怎么做
我很快定位到问题在 Nginx 层，因为本地直连后端端口是通的。于是按"从近到远"的顺序查：先看 Nginx 错误日志，再抓配置，最后看后端监听地址。三个动作合起来，基本能覆盖 80% 的 502 根因。
遇到什么坑
坑一：最常见也最隐蔽——Nginx 默认按 IPv6 的 127.0.0.1 写 upstream。如果后端只监听了 IPv4 的 127.0.0.1:8080，Nginx 拿 proxy_pass http://127.0.0.1:8080 去连时走 IPv6 回环，连不上就直接 502。这一步当时没意识到，因为日志里报的是 connect() failed (111: Connection refused)，看着像端口没起，实际上端口是活的，只是协议栈没对上。把 upstream 显式写成 127.0.0.1 都不行，得写死 IPv4 或用 localhost 的解析配置，这个细节排查了很久。
坑二：proxy_pass 末尾的斜杠问题。带不带斜杠会导致 Nginx 把完整 URI 还是去掉前缀再转发，写错时后端路由全乱，表现成 404/502 混合。这个属于配置语义坑，光看错误日志看不出，得对比前后端路由才暴露。
坑三：防火墙和安全组。阿里云安全组默认只放行 80/443，后端 8080 端口如果被 Nginx 本机转发反而没事，但如果你以为要开 8080 去"顶住"就是白费功夫，反代场景根本不需要对外开后端端口，安全组开多了反而是隐患。
关键结论 / 可复用方法
- 拿到 502 先看 /var/log/nginx/error.log，别猜。日志里 connect() refused(timeout) 直接指向 upstream 问题，这是性价比最高的第一步。
- 后端端口必须跟 Nginx 转发的地址族一致：后端绑 0.0.0.0 或明确 IPv6，别让 v4/v6 不一致的坑挖到你。这一条能省掉一半排查时间。
- proxy_pass 用变量时要小心，带变量会让 Nginx 在请求期动态解析，行为跟写死字面量完全不一样，少用变量，写死是最稳的。
- 反代一律走 Nginx 本机转发，后端不对外开端口，安全组只开 80/443，这是最省心也最安全的拓扑。
这套"先日志、再地址族、再语义"的排查顺序我整理进常用清单了，之后几次 502 基本十分钟内就能定位。工具是死的，顺序对了效率完全不同。
