Nginx 502错误排查实战：定位上游服务故障的完整方法

1. 502 Bad Gateway到底是什么先搞清楚Nginx在替你背什么锅碰到502的第一个反应别急着改配置。这个错误码翻译过来是Nginx作为网关没能从上游服务器拿到有效响应。也就是说Nginx本身活得好好的倒霉的是它后面那台真正的业务服务器——可能是Tomcat、Gunicorn、Node.js、PHP-FPM也可能是一台内网API服务。很多人一上来就查Nginx的error.log结果发现日志空空如也然后就开始怀疑Nginx配置写错了。其实方向反了。502的本质是链路问题Nginx只是链路中间那个传话的人。上游服务器连接不上、连接上了但响应超时、响应内容非法这三种情况最终都会以502的形式呈现在客户端面前。你要做的不是盯着502本身而是沿着请求路径一级一级往下找直到定位到那个真正断掉的地方。我见过最典型的误判场景开发环境一切正常上线后偶尔502过几秒自己又好了。开发同学一口咬定是Nginx配置有问题运维查了半天发现Nginx配置压根没动过最后定位到是后端服务在线程池耗尽时拒绝新连接Nginx这边只能返回502。所以这句话得记住502是结果不是原因。排查502前先确认你的代理链路长什么样。一条典型链路可能是客户端 - Nginx(80/443) - 反向代理目标(127.0.0.1:8080) - 应用服务。Nginx只是中间人它自己不会主动产生业务错误。如果Nginx与上游之间用的是TCP连接那就要检查端口连通性如果用的是Unix Socket那就要检查socket文件权限如果上游是域名那还要检查DNS解析是否间歇性失败。不同链路的排查路径完全不同先画清楚链路图再动手能省掉大量无效操作。2. 从日志到抓包一套能复现的502排查链路2.1 第一步把Nginx的日志调到会说话的级别默认的Nginx日志配置往往什么关键信息都看不出来只有一行upstream prematurely closed connection while reading response header from upstream信息量太少。排查502的第一步先把日志格式和级别调整好让日志告诉我们更多细节。在nginx.conf的http块里配置一个带upstream耗时和上游状态码的log_formatlog_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for $upstream_addr $upstream_status $upstream_response_time $request_time $upstream_cache_status; access_log /var/log/nginx/access.log main;这一行配置的价值在于$upstream_addr能直接告诉你Nginx把请求转发到了哪个上游地址$upstream_status能告诉你上游返回了什么状态码——如果上游返回500但Nginx返回502那问题出在上游如果$upstream_status是-说明连接压根没建立成功$upstream_response_time能帮你判断是超时还是秒回。改完配置后用nginx -t检查语法再nginx -s reload然后复现一次502打开access.log看这一行的完整输出。正常情况下你能立刻得出结论问题在上游服务本身还是在Nginx与上游之间的连接建立阶段。2.2 第二步快速判断上游是死了还是活着假设access.log里显示$upstream_status为空$upstream_addr正确那基本可以确定是连接建立失败。这时候手动验证上游服务状态别只依赖浏览器刷新因为浏览器缓存会骗人。用curl直接请求上游地址curl -v http://127.0.0.1:8080/health如果上游是Unix Socket用curl -v --unix-socket /run/php-fpm/www.sock http://localhost/health这一步能区分两种情况curl秒回正常响应说明Nginx到上游的通道出了问题重点查Nginx配置里的proxy_pass写法、防火墙规则、上游监听地址是否写错curl直接connection refused或者超时说明上游服务根本没起来或者起来后 hang 住了这时需要去查上游服务的日志和监听状态。检查监听端口的典型命令ss -tlnp | grep 8080 ss -lx | grep php-fpm如果端口在监听但TCP连接是半开状态比如用ss -tn state established看到大量SYN-SENT那可能是上游服务accept队列满了也就是经典的backlog溢出问题。2.3 第三步防火墙、SELinux和内核参数这三座大山很多502故障是环境层面的配置怎么改都没用因为压根没走到应用那一步。在Linux服务器上三个最常见的隐形杀手是iptables/nftables规则、SELinux策略、以及内核参数中的连接跟踪表溢出。先检查防火墙规则是否放行了Nginx到上游的端口iptables -L -n | grep 8080如果服务器在云上还要检查安全组云安全组拦掉的流量在操作系统内部连日志都看不到。SELinux方面如果开启的是 enforcing 模式Nginx默认被限制只能代理到特定端口可以临时用setsebool -P httpd_can_network_connect 1放行或者干脆用getenforce确认状态后针对性地调整策略。另外注意nf_conntrack表溢出问题这个坑特别隐蔽。当服务器连接数太多、conntrack表被占满时新连接直接丢包表现就是客户端间歇性502、服务端日志没有任何异常。查看方式sysctl net.netfilter.nf_conntrack_max sysctl net.netfilter.nf_conntrack_count dmesg | grep nf_conntrack如果nf_conntrack_count接近nf_conntrack_max就说明连接跟踪表要爆了需要调大nf_conntrack_max并缩短超时时间。这个故障在并发量上来后特别容易触发而且毫无规律属于那种排查到怀疑人生的类型。2.4 第四步抓包一锤定音当日志层面看不出问题时该上抓包工具了。在Nginx服务器上抓环回接口流量因为Nginx和上游通常在同一台机器上tcpdump -i lo -nn port 8080 -w /tmp/upstream.pcap然后在客户端复现一次502CtrlC停止抓包后用wireshark打开。重点看TCP握手是否完成、Nginx是否发了请求数据、上游是否有响应。如果看到TCP握手三次完成但紧接着RST那说明上游accept后立即主动断开——典型的上游服务崩溃前兆如果握手都没完成说明防火墙把SYN包吞了如果三次握手正常但HTTP层没有响应那就是应用层超时。抓包这一步对经验不足的人来说有点门槛但它能一次性定位到TCP层完全正常问题在应用层这样的结论少走大量弯路。如果连tcpdump都不会装那就先在本地起一个最简单的Nginx作为上游用curl直连先把上游正常时Nginx能正常代理这个基准建立起来再逐步替换回真实上游通过二分法缩小范围。3. 六类高频根因与对应修复方案3.1 上游服务崩溃或未启动最常见但也最好解决这是502故障里占比最高的一类。后端进程因为OOM被kill、代码异常导致进程退出、发布脚本没拉起来新进程都会让Nginx的proxy_pass指向一个不存在的服务。检查方法简单粗暴ss -tlnp | grep 端口端口没监听就是进程没了端口在监听但进程处于僵死状态用ps -ef | grep 进程名看状态再查上游自己的日志确认崩溃原因。这类问题的长期解法不是修改Nginx而是给上游配置守护机制。systemd服务的话确保Restartalways容器环境则配置restart policy和健康检查。Nginx这边能做的只是在504/502时返回一个更友好的错误页面比如error_page 502 /502.html; location /502.html { root /usr/share/nginx/html; internal; }但这不是根治只是让用户看到的好看点而已。3.2 上游连接超时Nginx等待过久主动放弃Nginx默认的proxy_connect_timeout是60秒proxy_read_timeout也是60秒。当上游处理请求很慢比如某个接口需要执行一个90秒的数据库查询Nginx会在60秒后主动断开连接客户端收到502。日志特征upstream timed out while reading response header from upstream。修复方式看场景。如果是上游确实需要长时间处理那就显式调大超时location /api/ { proxy_pass http://backend; proxy_connect_timeout 5s; proxy_read_timeout 120s; proxy_send_timeout 30s; }注意connect_timeout不建议设太大5秒足够因为TCP连接建立本身就不该超过几秒。真正要大的是read_timeout和send_timeout这两个默认值在慢业务场景下很容易成为瓶颈。但更要反思上游为什么这么慢。如果同一个接口偶尔快偶尔慢去查数据库慢查询如果一直慢说明接口本身设计有问题Nginx调参只是缓冲不是解药。3.3 Unix Socket文件权限与路径问题PHP-FPM专属大坑Nginx代理PHP-FPM时使用的经常不是TCP端口而是Unix Socket文件比如/var/run/php-fpm/www.sock。这类502的经典报错是connect() to unix:/var/run/php-fpm/www.sock failed (13: Permission denied)原因几乎都是权限不匹配。Nginx worker进程以nginx用户运行但socket文件的所有者却是www用户或者root导致没有权限连接。解决方案二选一修改php-fpm的socket文件权限让它对nginx用户可读写。编辑www.conflisten.owner nginx listen.group nginx listen.mode 0660或者将Nginx的worker进程改为与PHP-FPM相同的用户修改nginx.conf的user指令user www;另外注意socket文件路径别写错。很多人把proxy_pass http://unix:/var/run/php-fpm/www.sock;写成了proxy_pass http://unix:/var/run/php.sock;路径对不上Nginx连文件都找不到。写完后用ls -l确认socket文件真实存在而不是用test -f来判断——socket文件在shell里看起来是存在但传统-f参数对它可能判断异常建议直接用ls -l或者ss -lx看监听状态。3.4 上游返回非法或空响应最隐蔽的一类有一种502Nginx日志写着upstream prematurely closed connection while reading response header from upstream而你的上游服务日志显示什么都没发生这通常意味着上游进程在处理请求时被操作系统强杀或者是连接被上游主动关闭但没发送任何HTTP响应。典型场景PHP-FPM进程执行了超出max_execution_time限制的脚本被强杀Java应用OOM后被JVM自杀Python服务因为GIL问题或未捕获异常导致worker退出。这时Nginx情绪稳定它只是如实地把上游的异常转述给了客户端。定位这类问题需要开启上游自己的错误日志。以PHP-FPM为例php_admin_value[error_log]和log_errors要配置好否则报错全被吞掉。Java应用则要看jvm日志和gc日志特别关注OutOfMemoryError和Unable to create new native thread这类关键行。这类问题光在Nginx层面打转是找不到出口的必须联调到上游应用的日志体系。3.5 DNS解析问题upstream域名动态解析的坑配置文件里proxy_pass如果填的是域名proxy_pass http://api.internal.example.com:8080;Nginx在启动时解析一次DNS并缓存结果。如果上游服务换了IP域名解析已更新但Nginx还在用旧IP连接就会出现间歇性502。解决方法是开启运行时DNS解析把upstream块里的server指令配合resolver使用resolver 127.0.0.53 valid30s ipv6off; upstream backend { server api.internal.example.com:8080 resolve; }这里的resolve参数让Nginx在每次建立新连接时动态解析域名valid30s指定DNS缓存有效期。这个配置在Kubernetes环境里尤其关键因为Service的ClusterIP会频繁变动不配置动态解析的话旧连接池里的IP全都会失效。3.6 keepalive连接池与后端连接复用冲突另一个让502时而出现时而消失的根因是连接复用。配置了upstream keepalive后Nginx会维护与上游的空闲连接池但上游服务如果主动关闭了这些空闲连接比如Tomcat的keepAliveTimeout较短Nginx不知道这条连接已经死了继续往上面发请求结果就是502。表现为日志里频繁出现upstream prematurely closed connection while reading upstream但上游服务日志里看不出异常。处理思路有两个方向。一是让Nginx在发现连接失效时重试一次proxy_next_upstream error timeout http_502 http_503 http_504; proxy_next_upstream_tries 2;这能让Nginx在一个上游连接失败时自动换到下一个上游或重建连接重试有效缓解偶发502对用户的影响。二是严格匹配keepalive参数。以下是一个兼顾性能与稳定性的配置模板upstream backend { server 127.0.0.1:8080; keepalive 32; } location /api/ { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ; }使用keepalive时proxy_http_version必须设为1.1并且要清空Connection头否则上游会按HTTP/1.0处理连接复用机制不生效最终退化成每次新建连接的场景反而更容易放大连接超时问题。4. 上游健康检查与自动摘除没事少折腾Nginx让后端自己报数4.1 没有健康检查时Nginx会把请求发给病人经过5个轮次的调优后我强烈建议你顺手做一件事给上游配置健康检查。Nginx开源版默认不带主动健康检查模块这经常被误解为开源版做不了健康检查实际上通过max_fails和fail_timeout参数就能实现简单的被动健康检查upstream backend { server 127.0.0.1:8080 max_fails3 fail_timeout30s; server 127.0.0.1:8081 max_fails3 fail_timeout30s; }这个配置的逻辑是如果某个上游在fail_timeout30秒内失败了max_fails3次Nginx会在接下来的30秒内自动把该上游标记为不可用不再向其转发请求。30秒后重新尝试。这套机制虽然没有主动探测那么灵敏但对于绝大多数业务场景够用了而且完全免费。如果你用的是Nginx Plus或者愿意编译第三方模块nginx_upstream_check_module那就可以实现主动健康检查Nginx每隔几秒主动访问上游的health接口根据返回码判断上游是否健康比被动健康检查快得多。但对于团队里没有专职运维的情况我自己通常会选择openresty自带的健康检查能力或者干脆在Kubernetes层面用Pod的健康探针来实现Nginx这边保持简单。4.2 给每个服务建立一个标准的health接口光有健康检查还不够上游服务的/health接口质量决定了整个故障发现链路的效率。我见过太多团队把/health接口写成一个返回hello world的固定字符串——这个接口根本测不出服务的真实健康状态。一个合格的健康检查接口至少应该做到三件事检查自身依赖的数据库连接池是否还有空闲连接检查外部依赖的缓存或消息队列是否可达检查自身进程的线程池/协程池使用率是否接近上限。以Spring Boot为例一个健康检查接口可以这么实现调用一次DataSource的getConnection()并释放超时2秒内返回成功就算通过连接失败则返回503。Nginx的健康检查模块收到非2xx状态码就会自动把当前上游摘掉后续请求自动切换到其他节点。这就形成了完整的故障自愈链路后端自己报数Nginx负责淘汰用户无感知。4.3 有了健康检查之后502的故障面会被大幅压缩配置了健康检查和自动摘除后最简单的回报就是偶发502会明显减少。拿我们一个实际的例子说明某次MySQL主从切换后从库连接数瞬间爆满Java服务在获取数据库连接时全部超时大量请求在接口层堆积。Nginx这边虽然没有感知到后端端口异常端口还在监听但健康检查接口因为数据库连接获取失败返回了503健康检查模块迅速把该节点摘除请求全部打到另一个健康节点上。整个过程用户最多感受到一次页面短暂卡顿而不是铺天盖地的502报警。这个案例说明了一个很重要的思路502的防御不能只看Nginx和TCP层要让健康检查探针把你业务链路的真实状态暴露出来。探针越接近真实业务链路发现故障的速度越快故障影响面越小。5. 我踩过的一些真坑以及针对性的防御性配置5.1 关于超时时间不是越长越好而是按业务分级别设定很多人遇到502就一刀切把proxy_read_timeout改成300秒甚至600秒这种粗暴调参方式短期看起来解决了超时问题实际上是把故障缓冲期拉长用户体验更差而且掩盖了上游真实存在的性能问题。我现在的习惯是分location设定超时。正常API接口不用改用默认值就行但对于那些确实需要长时间处理的请求比如导出报表、批量导入单独开一个location并放长超时location /export/ { proxy_pass http://backend; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_request_buffering off; }proxy_request_buffering off这行很多人不熟悉。默认Nginx会先把客户端请求体完整缓冲到磁盘或内存再转发给上游。对于大文件上传场景如果关闭缓冲Nginx边收边转上游可以更早开始处理避免上游因等待完整请求体而导致连接超时。但要注意关闭缓冲后如果客户端上传中断上游会收到一个不完整的请求需要业务层做好判断。5.2 惊群效应与backlog溢出高并发502的隐藏推手一次大促场景下的502排查让我铭记在心。上游服务CPU、内存、连接数全部正常但Nginx大量报502而且都是connect失败。后来用ss -lntp看8080端口的Recv-Q发现队列长度持续大于socket的backlog设置。当时上游Tomcat的acceptCount配置是100Nginx瞬间涌入的连接远超这个数多余连接直接被内核丢弃。解决方式是双管齐下Tomcat的acceptCount适当调大Connector port8080 protocolHTTP/1.1 maxThreads400 acceptCount200/同时把内核的somaxconn调大sysctl -w net.core.somaxconn1024另外还要注意Nginx自身传递连接的效率。如果Nginx和上游都在同一台机器开启proxy_bind固定源IP和tcp_nodelay on可以稍微降低连接建立耗时但收益相对有限核心还是让后端吃得住流量。5.3 日志切割别忘掉磁盘满引起的无脑502这个坑特别容易在凌晨触发。access.log和error.log在无人值守的情况下一直增长磁盘被日志占满Nginx尝试写入新日志时失败行为变得异常所有请求返回502。哪怕从应用层面看一切正常也要先确认磁盘使用率df -h一个习惯性动作配置logrotate或每天定时任务把旧日志压缩归档保留最近7天即可。像logrotate做每日切割并压缩一天的日志通常能压到原来的十分之一以下。把Nginx的/var/log/nginx目录单独挂一个分区也能避免日志把系统盘撑爆。5.4 故障演练让502在你可控的时候出现一次最后分享一个反常识的建议主动制造一次502。在生产环境流量低峰的凌晨手动停掉一台上游服务观察Nginx的表现健康检查是否及时摘除节点摘除后请求是否平滑切换到存活节点客户端有没有收到报错有没有堆积报警等恢复后对比日志确认整个闭环链条是通的。我见过太多的团队502一出现就是全员扑上去救火等故障恢复后谁也没复盘更别说自己主动演练。生产环境的故障链路最怕的是没遇到过而不是遇到了处理不好。主动演练一次你才知道你的监控、报警、摘除机制到底靠不靠谱也才知道配置里的哪些参数只是摆设。就我个人经验而言把上面这套链路完整走一遍你会对Nginx的502建立完全不同的认知——它不再是一个随机出现的恐怖错误码而是链路上某个节点状态的可视化呈现。排查速度、定位精度、修复效率都会比网上找配置改一改高出不止一个量级。