502错误是nginx作为代理未能从上游获取合法http响应，需按连通性、超时、配置、缓冲四维度排查：先用curl直连health端点验证后端真实可用，再查ss确认监听地址，结合error.log定位upstream timed out或connection refused，调大proxy_connect_timeout和proxy_read_timeout，校验proxy_pass斜杠、host头、websocket三件套等协议配置，并增大proxy_buffer_size等缓冲参数。
502 错误不是 Nginx 自身出问题，而是它作为“中间人”没能从后端拿到合法响应。排查核心是顺着 Nginx 的视角看：它连没连上？等没等到？收没收到？配没配对？
先确认后端服务真实可用
别只看进程在不在，要看它能不能真正响应请求：
- 用 curl -v http://127.0.0.1:端口/health 直连测试，必须返回 200 和有效内容
- 执行 ss -tuln | grep :端口，确认监听的是 0.0.0.0 或 127.0.0.1，而不是 localhost 或其他 IP
- 查后端日志，比如 Node.js 的 stdout、PHP-FPM 的 error.log，重点找崩溃、拒绝连接、启动失败记录
- 容器环境要核对 docker ps 是否运行，docker logs 容器名 有无报错，端口映射是否正确
检查超时设置是否合理
后端稍慢一点，Nginx 就可能主动断开并返回 502：
- proxy_connect_timeout 建议设为 30–60 秒，防网络抖动或后端冷启动慢
- proxy_read_timeout 普通接口至少 120 秒；WebSocket 或长轮询必须设大（如 86400）
- proxy_send_timeout 通常与 read timeout 保持一致即可
- 所有值都要大于后端自身处理耗时，并留出缓冲余量
核对代理头和协议配置
很多 502 是因为“转发得不对”，后端根本看不懂请求：
- 反代 HTTPS 站点且带 SNI，必须加 proxy_ssl_server_name on;
- WebSocket 必须三件套：proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";
- Host 头别盲目用 $host，若后端靠 Host 路由或鉴权，应写死为实际域名，如 proxy_set_header Host api.example.com;
- location 和 proxy_pass 尾部斜杠要匹配，location /api/ { proxy_pass http://backend; } 才能正确透传路径
查看缓冲区与资源限制
响应头太大、返回体太长、并发太高，Nginx 默认缓冲撑不住：
- 增大响应头缓冲：proxy_buffer_size 16k;
- 扩大主体缓冲区：proxy_buffers 8 16k;、proxy_busy_buffers_size 32k;
- 大文件或流式场景可关缓冲：proxy_buffering off;（注意内存压力）
- 检查后端是否返回非法 header（如空格、控制字符），这类响应会被 Nginx 当作无效而触发 502
