nginx 502/504 故障排查标准化核心是统一日志入口、分角色直连验证、故障卡片化响应、配置与告警联动；要求全员首查 /var/log/nginx/error.log，按四类错误特征执行对应命令与判断，并强制健康检查与压测验证。
规范化团队的 Nginx 502/504 故障排查标准，核心是把“凭经验猜”变成“按线索查”，让新人也能快速定位、老手不重复踩坑。关键不是堆流程，而是统一入口、明确分工、固化验证动作。
统一日志入口与关键词响应规则
所有成员必须第一时间查看 /var/log/nginx/error.log，且只关注四类带明确阶段标记的错误行：
-
connect() failed (111: Connection refused) → 立即检查上游端口监听状态（
ss -tuln | grep :端口号）和服务进程存活（systemctl is-active your-app） -
upstream prematurely closed connection → 同步查上游服务日志末尾 +
dmesg -T | grep "killed process"，确认是否 OOM 杀进程 -
upstream timed out (110: Connection timed out) while reading response header → 锁定为 504，跳转检查
proxy_read_timeout配置与上游实际处理耗时 - upstream timed out (113: No route to host) → 直接交网络组，不自行排查应用层
分角色执行“三分钟直连验证”
避免“我以为它好了”的误判，强制使用 curl 模拟 Nginx 转发路径，由不同角色完成指定动作：
-
运维同学：在 Nginx 本机执行
curl -v http://127.0.0.1:上游端口/health，验证端口通、响应快、HTTP 状态码正确 - 开发同学：提供可复现的请求样例（含 Header、Body），并确认该请求在本地或测试环境能稳定返回，排除业务逻辑阻塞
- DBA 或中间件同学：若涉及数据库或缓存，同步检查连接池活跃数、慢查询、连接超时等指标，不等应用报错再介入
建立故障分类响应卡片（SOP 卡）
将高频场景压缩成一页纸卡片，贴在团队协作工具首页，每张卡包含：错误特征 + 必查命令 + 两个判断依据 + 升级条件。例如：
【502-OOM 类】
✅ 特征：error.log 出现 prematurely closed + dmesg 有 killed process xxx
✅ 必查：dmesg -T | grep -i "killed process"、journalctl -u your-app -n 20
✅ 判断依据：1）上游进程 RSS 内存接近容器/系统内存上限；2）无 graceful shutdown 日志
⚠️ 升级条件：连续 2 次同因重启，需立即评估内存泄漏或限制调优
配置变更与告警联动机制
杜绝“改完就跑”，所有 Nginx 超时参数（proxy_*_timeout）、上游地址、健康检查路径的修改，必须满足：
- 提交配置前，在测试环境用
ab或hey压测对应接口，验证 timeout 设置与实际响应分布匹配 - 上线后 10 分钟内，自动触发一次轻量探测：
curl -sI http://localhost/health | grep "200 OK"，失败则钉钉@责任人 - 所有上游服务必须暴露
/health接口，返回 JSON 格式含status和memory_usage_mb字段，供 Nginx health_check 或监控采集
