做运维这些年最怕半夜手机响一接起来就是“网站打不开了”“接口全报错”打开浏览器一看Nginx反向代理后面挂着一行刺眼的502 Bad Gateway。这个错误太常见了常见到很多人第一反应就是“重启一下Nginx”结果重启完该502还是502用户骂得更凶。作为一个被502折腾过无数次的过来人我把自己踩过的坑、排查过的案例、调过的参数全部整理成一篇可以直接照着操作的实战记录。不管你是刚入门的小白还是被线上故障折磨的运维老手这篇文章都能帮你少走弯路遇到502时能快速定位根因而不是瞎猜。1. 先搞清楚502到底是怎么产生的1.1 502的本质网关和后端之间的“传话失败”很多人一看到Bad Gateway就懵其实用大白话解释特别简单。Nginx在反向代理架构里扮演的角色就像一个前台接待员用户请求先到前台前台再把需求转达给后面的业务部门也就是上游服务器可能是Tomcat、PHP-FPM、Node.js或者另一个Nginx。502的意思是前台把请求转过去之后后端要么根本没人接要么接了之后给了一个Nginx无法理解、无法转发的错误响应。用打电话来类比就是——你打通了前台电话前台帮你转接分机结果分机那边传来的是“对方暂时无法接通”或者干脆一片忙音。理解这个本质对排查很重要因为502的根因永远出在“Nginx与上游服务器之间的通信链路”上而不是用户那边的问题。你不需要怀疑用户浏览器、怀疑DNS、怀疑CDN重点就集中在两个地方一是上游服务是否健康二是Nginx到上游的这段通路是否存在障碍超时、连接数、协议、证书等。HTTP层面的完整链路是这样的客户端发送请求给NginxNginx根据location或proxy_pass规则把请求转发给上游上游处理完返回响应Nginx再把响应原样传回客户端。在这个过程里任何一环出现异常都可能表现为502。关键点在于Nginx本身并不是故障源它只是那个倒霉的传话人真正的病根在下游。所以我们排查时永远要逆向思维先查最坏的那个环节不要一上来就折腾Nginx。1.2 502、504、499三个易混错误码的区别很多读者分不清502和504其实这俩是兄弟俩但病因完全不同。502 Bad Gateway是上游服务器返回了无效响应或者根本没有响应。504 Gateway Timeout是Nginx把请求转发给上游后上游在指定时间内没处理完Nginx等不及就主动断开报超时。翻译成人话502是“后端没干这活”504是“后端干得太慢”。还有一个容易被忽略的499这是Nginx特有的错误码含义是客户端在服务端还没响应完之前主动断开了连接。经常出现在接口响应很慢、用户等不及刷新页面的场景。很多人在日志里看到499以为是自己服务的错误其实那是客户端取消请求的记录只能说明你的接口响应时间已经超过了用户的耐心阈值是一种间接的性能预警信号。我自己处理故障时第一步永远是打开Nginx的error.log和access.log看具体报错内容而不是只盯着浏览器里的502页面。同样一个502日志里可能出现完全不同的线索。比如connect() failed (111: Connection refused)说明上游端口根本没人听upstream prematurely closed connection while reading response header说明上游在响应过程中提前断开了no live upstreams while connecting to upstream说明配置的upstream组里所有后端都挂了。这些日志措辞就是你的破案线索下面每一节我都会结合具体日志来讲。2. 排查502第一步先确认后端服务还活着2.1 端口、进程、本地请求三步自检绝大多数502的根因其实特别朴素——后端服务挂了。Java服务OOM崩溃了、PHP-FPM进程池耗尽了、Node.js进程被守护进程杀掉后没拉起来、数据库连接池爆炸导致服务假死……这些情况在日志里表现出来都是一致的Nginx连接后端端口时被拒绝。我的标准三步自检流程是这样的任何场景下都能用第一步检查后端进程是否存活。以最常见的systemd管理为例直接执行systemctl status 你的服务名看进程状态是active还是failed。如果是docker部署就用docker ps看容器状态k8s环境就kubectl get pods。这一步能排除“进程直接挂了”的最简单可能。第二步检查端口是否在监听。进程活着不代表端口就正常监听ss -lntp | grep 端口号或者netstat -ltnp | grep 端口号看看你配置的proxy_pass对应的端口有没有LISTEN状态。曾经遇到过一次奇葩故障服务进程好好的但端口没起来最后发现是服务启动时绑定IP写错了绑到了127.0.0.1上而Nginx通过内网IP去连自然连不上。第三步也是最重要的一步在Nginx服务器上用curl直接请求上游地址验证连通性。比如你的Nginx配置里写的是proxy_pass http://127.0.0.1:8080;那就直接在Nginx机器上执行curl -v http://127.0.0.1:8080/。这一步能精准区分“Nginx到上游的网络问题”和“上游服务自身问题”。如果curl秒回正常内容说明后端是健康的问题大概率出在Nginx和上游之间的交互细节上如果curl也报错那就老老实实回到前两步继续查服务本身。2.2 防火墙、监听地址和proxy_pass配置的坑如果你在Nginx机器上curl上游是通的但Nginx转发时依然502那问题很可能是配置层面的细节错误。这里有一个我至今记忆犹新的案例有个业务上线第二天就开始随机502研发团队查了半天没头绪。后来我把Nginx的error.log打开发现报错清一色是connect() failed (111: Connection refused) while connecting to upstream但手动curl后端地址完全正常。最后折腾了很久才定位到Nginx配置里proxy_pass写的是后端机器的内网域名而这个域名解析出来有两个IP——一个IPv4一个IPv6。Nginx优先用了IPv6去连接而后端服务只监听了IPv4的端口IPv6端口根本没有服务监听所以连接被拒绝。解决办法要么让Nginx强制使用IPv4在proxy_pass里直接填IPv4地址或者设置resolver ipv6off要么让后端服务同时监听IPv6。这个问题在云原生环境里尤其常见因为Kubernetes的Service经常同时暴露IPv4和IPv6地址。防火墙也是经典凶手。有些云厂商的安全组默认放行了80和443但内网端口8080、8081并不在放行列表里。Nginx和上游服务器虽然在同一台机器上没问题但一旦跨机器你就得检查两台机器之间的防火墙、安全组、iptables规则。判断方法不难用telnet 上游IP 端口或者nc -vz 上游IP 端口测试连通性通不了就逐层检查iptables和云平台安全组。另外还要提醒一个非常低级的错误proxy_pass的URL写错。比如后端服务实际端口是8081配置里写成了8080或者proxy_pass结尾的路径带了多余的location前缀导致上游收到的请求路径根本不存在返回404或者直接断连。这种问题不需要什么高深技巧仔细看一遍Nginx配置就能发现但紧急故障时人一慌就容易忽略。3. 超时类502最隐蔽也最常见的元凶3.1 Nginx三个超时参数怎么调后端服务进程正常运行、网络也通但请求一多就502这在动态应用场景下几乎都是超时问题。Nginx到上游的整个请求过程分为三个阶段建立连接、发送请求、读取响应。Nginx针对这三个阶段分别有超时控制参数proxy_connect_timeout控制连接超时、proxy_send_timeout控制发送请求超时、proxy_read_timeout控制读取响应超时。默认值分别是60秒、60秒、60秒大多数场景下connect和send很少出问题read超时才是重灾区。举个例子假设你的接口是一个报表导出接口正常情况下需要5秒能出结果但某天数据库变慢接口执行时间涨到了90秒。Nginx的proxy_read_timeout如果还是默认60秒那么在60秒整这个节点上Nginx会主动断开连接客户端就会收到502。但有意思的是服务端日志里这个接口其实执行成功了只是结果还没传回来连接就被Nginx掐断了。针对这种场景我会把动态API接口的超时参数调到120秒或更长静态资源则维持短超时。配置写在nginx.conf的http块、server块或location块里示例location /api/ { proxy_connect_timeout 5s; proxy_send_timeout 10s; proxy_read_timeout 120s; proxy_pass http://backend_server; }这里有个小经验connect超时不要调太长5秒足够了。连接都建立不起来说明网络或服务有严重问题等太久只会拖慢整体故障响应速度。如果连后端都连不上你给再长的read超时也没用。3.2 后端自身的超时PHP-FPM与Java线程池很多人只盯着Nginx的超时参数却忘了后端服务自己也有超时机制而且这层更隐蔽。最常见的PHP-FPM场景PHP的max_execution_time限制了脚本最大执行时间一旦脚本执行超过这个值PHP-FPM会直接终止进程。那么Nginx视角看到的画面就是连接建立没问题请求发出去了但等了一会儿上游连接突然关闭日志报upstream prematurely closed connection while reading response header。这就是典型的后端主动掐断和Nginx超时是两码事。PHP环境还有一个更隐蔽的request_terminate_timeout参数这个参数只对PHP-FPM的请求处理进程生效默认值为0表示不限制。但如果有人设了值比如设成60秒那么任何请求处理超过60秒都会被无情杀掉。很多phper排查超时问题时只改Nginx的fastcgi_read_timeout却忽略了PHP-FPM的这个参数结果调了半天还是502其实方向就错了。Java应用的情况稍微不同Tomcat的connectionTimeout控制客户端连接空闲超时Spring Boot内置的Tomcat默认20秒。更常见的其实是线程池耗尽导致拒绝服务Tomcat的maxThreads默认200假设接口响应变慢200个线程全部被占住新的请求就排不上队Socket连接被积压到一定量之后新连接直接抛出异常Nginx这边看到的就是502或者connect失败。说句实话遇到后端超时类502治标和治本要同时做。治标是调大Nginx的超时阈值让链路能容忍更慢的响应治本是优化后端接口性能把慢查询、慢逻辑解决掉。如果你只调Nginx不优化后端就等于把马路拓宽了但前方堵车的源头没解决延迟只会越积越严重。3.3 慢请求场景下的超时调优实例去年帮朋友排查过一个线上问题现象是有个上传导入功能的接口文件稍微大一点就502小文件完全正常。看了Nginx错误日志发现频繁出现upstream timed out (110: Operation timed out) while reading response header指向了后端处理接口超时。顺着链路查下去这个业务用的是PHP导入接口要解析Excel并逐行写入数据库一个几百KB的Excel可能有几万行数据处理时间轻松超过60秒。当时我给了三个层面的修改建议第一Nginx的fastcgi_read_timeout从默认60秒调到300秒放行这个接口第二PHP-FPM的request_terminate_timeout同步调到300秒第三也是真正治本的方案——把导入逻辑改成异步任务先上传文件再后台处理处理完前端轮询状态接口获取结果。这个案例想说明的是超时调优不能只改一层。Nginx等Apache——不对Nginx等网关层、PHP-FPM进程层、业务代码本身这三层都可能存在超时限制任何一层限制都会表现为502。排查时要把整个链路上所有超时参数全部过一遍逐一确认阈值才能彻底解决。4. 连接数耗尽高并发下的502集中爆发4.1 Nginx连接数模型与文件描述符高并发场景下的502最典型的特征是“平时没事一搞活动流量上来就崩”。这类问题通常不是超时也不是服务宕机而是连接数被干满了。Nginx本身对并发连接数是有限制的核心参数是worker_processes和worker_connections。理论上单进程最大连接数是worker_connections总的并发连接数大约等于两个参数相乘当然还要再除以一点冗余系数。系统层面还有一个硬性限制——文件描述符。Linux下一切皆文件每个TCP连接都要占用一个文件描述符。Nginx进程能打开的FD数量受ulimit -n限制如果这个值比较小连接数到达上限后Nginx就无法再接收新连接表现就是用户访问变慢、超时、甚至直接拒绝连接。这时候你看到的错误日志可能不是明确的502而是一堆open() socket: Too many open files。我自己在处理这类问题时有一套标准检查顺序。首先执行ulimit -n看当前限制正常情况下应该设置到65535以上然后看Nginx的error.log里有没有worker_connections are not enough这样的提示。这两个信号都能直接指向连接数瓶颈。解决方案也明确提升系统FD限制在/etc/security/limits.conf里设置nofile同时调大Nginx的worker_connections并确保worker_rlimit_nofile也有对应的提高。4.2 upstream keepalive既能提速还能救502还有一个非常关键的高并发优化参数——upstream keepalive。很多人不知道Nginx默认和上游服务器通信是短连接每来一个请求Nginx就向上游建立一次TCP连接请求结束就断开。在高并发场景下这种频繁建连会消耗大量服务器资源甚至直接把上游的连接数打爆。我看到过很多团队在Nginx里配置了upstream但只写了server地址完全没写keepalive指令。这种情况下后端每处理一个请求就要经历完整的TCP三次握手加四次挥手QPS稍微高一点TIME_WAIT状态连接堆积如山后端的连接数监控直接报警最终表现为大量请求502。正确配置方式是在http块里设置keepalive值upstream backend_servers { server 127.0.0.1:8080; server 127.0.0.1:8081; keepalive 64; } server { location / { proxy_http_version 1.1; proxy_set_header Connection ; proxy_pass http://backend_servers; } }这里有两个细节必须同时到位一是proxy_http_version必须改成1.1因为HTTP/1.0不支持连接复用二是要通过proxy_set_header Connection 清空默认的Connection头否则复用会失效。keepalive的值代表每个worker进程保持的最大空闲连接数一般设置成64到128比较合适不要盲目调大因为每个空闲连接都占用资源。这个配置不仅把Nginx到上游的TCP连接复用起来大幅降低延迟更重要的是一下子解决了上游的连接数压力。我见过一个项目只加了keepalive配置压测的QPS直接翻倍同时后端的502几乎消失效果立竿见影。4.3 后端连接数被打满时的排查方法还有一种情况Nginx侧配置没问题但后端服务的连接数上限太低。典型的Java应用Tomcat的maxThreads如果设成200高并发时并发请求超过200就会进入等待队列队列满后直接拒绝新连接。Node.js默认单线程虽然异步I/O能抗高并发但如果有同步阻塞操作事件循环被卡住新的连接也处理不过来。PostgreSQL和MySQL也有各自的max_connections限制数据库连接被占满时应用服务的每个请求都会卡在获取数据库连接这一步越积越多最终所有请求全部超时。这种情况下你会发现一个有意思的现象你单独curl后端某一个接口可能还是好的但只要并发压测502就开始出现。判断方法很直接到后端服务器看连接数ss -s ss -ant | grep 端口号 | wc -l再看后端日志有没有“Connection refused”“Too many connections”“thread pool exhausted”之类的关键字。如果真的达到后端的连接上限方向就不是调Nginx了而是扩容后端实例、调大连接池、优化代码降低连接占用时间。很多时候微服务架构里还有一层网关比如Spring Cloud Gateway或者自研的API网关排查502时必须把整条链路拆开来看客户端到Nginx、Nginx到网关、网关到业务服务、业务服务到数据库。每跳都可能产生502只有逐段压测和检查才能精准定位瓶颈在哪个环节。否则你在Nginx层折腾半天实际根因可能是业务服务连接数据库的连接池满了。5. 证书与加密层502问题的冷门起源5.1 替换SSL证书后不生效的三种原因与502相关的还有一个非常容易被忽略的场景——SSL证书更新。经常有人遇到这种情况证书明明已经替换了有效期也看了没问题但访问网站还是报502错误或者浏览器提示证书无效。这背后的原因有不少我总结了最常见的三种。第一种是改完配置文件没有reload。Nginx的配置和证书文件是在启动或reload时加载到内存的很多人在服务器上替换了pem文件以为立刻就生效其实Nginx还在用旧证书继续工作。除非旧证书完全失效导致握手失败否则你根本察觉不到已经换了新证书。正确操作是执行nginx -t先验证配置然后nginx -s reload平滑重载。第二种是证书文件路径配置错误。Nginx里ssl_certificate指定的路径写错了Nginx启动时不会直接报错而是在客户端发起TLS握手时才发现文件加载不了表现就是握手失败、连接中断。这种问题在日志里能看到ssl_certificate相关的错误提示排查时重点检查路径和文件权限。第三种是证书链不完整。现在很多证书签发机构要求配置证书时必须带上中间证书链如果只填了服务器证书而没有把中间证书一并写入部分客户端能正常访问因为它的信任库里已经缓存了中间证书但另一些客户端在证书链验证时会失败。复杂客户端环境下这种问题尤其隐蔽因为不是所有用户都会报错。5.2 证书链不完整导致上游握手失败在反向代理场景下证书问题导致的502有更具体的表现形式。假设你的架构是Nginx作为出口统一终止SSL然后通过HTTP协议转发到内网后端那么证书问题主要影响的是客户端到Nginx这一段不会直接导致502。但如果你的Nginx还承担了“反向代理到另外一个HTTPS站点”的角色比如配置了proxy_pass https://some-backend-domain那么Nginx作为客户端去和后端建立TLS连接时会验证后端证书的合法性。后端证书无效、过期、域名不匹配、证书链不完备都会导致TLS握手失败Nginx无法和后端通信表现出来就是标准的502。处理这类问题的核心方法很简单——把上游证书链路修复好确保整条证书链是完整的。验证证书链是否完整可以用openssl这个命令openssl s_client -connect 你的域名:443 -showcerts如果返回的证书链中间有断档说明服务器的ssl_certificate配置里缺少中间证书。正确做法是使用证书机构提供的fullchain文件包含完整证书链把内容合并成一个pem文件然后在Nginx里指定server { listen 443 ssl; server_name 你的域名; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; }很多人会问证书只是个文件的替换为什么会导致502这么严重其实道理不复杂反向代理的本质是建立一个可靠的信任链路其中任何一环的TLS握手失败就意味着链路建立不起来网关自然无法转发请求最终只能返回502。5.3 证书更新后的标准验证流程如果你刚刚换过证书又恰好遇到了502我建议按这个顺序来验证。首先用nginx -t确认配置语法和证书文件都能被正确读取这一步能过滤掉路径错误和权限问题。然后执行nginx -s reload让配置生效。接着用openssl s_client -connect 域名:443 -servername 域名检查线上证书的实际签发信息、有效期和证书链确认浏览器拿到的证书确实是你刚更新的那张。最后也是很重要的一步检查Nginx的error.log里有没有SSL相关的告警信息很多证书问题在浏览器端看起来只是安全警告但在Nginx日志里会留下明确的错误记录。还有一个我犯过的错想提醒大家证书更新后一定要检查证书私钥和证书是否匹配。曾经有一次我只替换了证书文件忘记私钥也对不上结果Nginx启动都起不来整个站点直接瘫痪。验证匹配的命令是openssl x509 -noout -modulus -in 证书文件 | openssl md5 openssl rsa -noout -modulus -in 私钥文件 | openssl md5两个命令输出的哈希值一致才说明证书和私钥是配套的。这个细节我在生产环境踩过坑之后现在每次更新证书都会先做这个校验。6. 一个真实案例服务正常、Nginx却502的完整排查6.1 现象与初步判断大概半年前处理过一个印象特别深的故障很能说明排查思路的重要性。当时一个客户的线上API突然开始大面积502但诡异的是运维同学到服务器上检查后端服务进程正常、端口正常、本地curl后端也秒回。后端Java服务日志里没有任何报错和异常看起来一切健康。用户那边就是一片哀嚎接口挂了App基本上没法用。我到现场后没有先去动Nginx而是先看了Nginx的access.log和error.log。发现一个非常关键的细节502报错并不是所有接口都出现而是集中在某一个特定路径下。比如/api/user/info频繁502但/api/goods/list完全正常。这就奇怪了同一个后端服务同一个upstream配置为什么不同的路径表现差异这么大当时我的直觉判断问题大概率不是处在连接层而是处在HTTP协议交互层。6.2 从Nginx日志逆推根因继续深挖Nginx错误日志我找到了这段关键信息upstream prematurely closed connection while reading response header翻译过来就是上游在Nginx读取响应头时提前关闭了连接。这种报错说明TCP连接和请求发送都成功了但后端的响应异常导致连接中途断开。那时候我基本排除了网络和连接数问题把焦点移到后端应用对请求的处理逻辑上。我让同事去翻后端服务那个接口的代码发现这个接口是一个数据聚合接口会并行调用多个下游服务。问题就出在并行调用上某个下游服务偶尔响应特别慢而这个聚合接口设置了较短的读超时比如2秒一旦超时整个请求就抛异常同时连接被强制关闭。但是为什么后端日志没有记录错误呢后来查清楚了那个异常的异常被全局异常处理器吞掉了只记录了一条debug级别的日志生产环境的log级别是info所以日志里看起来什么都没有。这种“后端看起来完全正常”的假象正是很多502难以排查的原因。6.3 解决与复盘定位到根因之后解决方案其实很简单。针对那个慢的下游服务有两个层面的处理第一把聚合接口的读超时时间从2秒调整到5秒增加容错空间第二针对那个下游服务增加一个快速失败的熔断机制如果它连续多次超时直接返回降级结果而不是让整个聚合接口挂掉。改动上线后502彻底消失。这个案例有几个排查经验值得沉淀。第一看日志永远比看表象重要Nginx的access.log能帮你区分是全部接口502还是部分接口502这一个信息就能砍掉一大半排查方向。第二后端日志“没有错误”不等于“没有异常”要确认日志级别是否覆盖了warning和debug信息避免异常被静默吞掉。第三分布式链路追踪在这种场景是真的救人命如果你有SkyWalking或Zipkin一个trace就能看到请求在哪一环耗时最长、哪一环抛出异常能省下几个小时甚至几天的排查时间。7. 问题排查速查表与我的几点经验7.1 502现象与原因快速对照表排查502的时候很多人不是没有排查能力而是没有一套清晰的对照框架。我根据自己的实操经验整理了一张速查表遇到问题先对着表格判断方向再去深入排查。这张表不敢说覆盖了所有可能但至少覆盖了职业生涯中百分之九十以上的502场景。现象特征可能原因首查命令与手段解决方向所有请求都502后端本地curl也失败后端服务宕机或端口未监听systemctl status、ss -lntp拉起服务、检查启动配置所有请求都502但本地curl后端正常防火墙/安全组拦截、IP版本不一致telnet 上游IP 端口、检查proxy_pass配置放通端口、指定正确IP部分接口502后端进程正常后端逻辑异常、连接被提前关闭error.log搜prematurely closed检查后端代码异常处理高并发时集中502连接数耗尽、FD达到上限ulimit -n、error.log搜too many open files调大FD限制、调整worker配置大文件上传、慢接口超时502读取响应超时检查proxy_read_timeout、上游自身超时配置逐层调大超时参数换过证书后出现502证书链不完整、证书与私钥不匹配openssl s_client、nginx -t配置fullchain证书、确认密钥匹配Nginx到HTTPS上游502上游证书无效或域名不匹配openssl s_client -connect 上游域名:443修复上游证书链间歇性502无固定规律上游某节点不稳定、负载不均连续curl上游多个节点摘除异常节点、检查健康检查配置这张表我建议保存在手机备忘录或者本地笔记里真出故障的时候对着看比临时翻文档靠谱得多。排查故障是争分夺秒的事情有一个清晰的排查框架能帮你省下最宝贵的黄金十分钟。7.2 经验之谈日志、二分、监控最后分享几条我自己花了很惨痛代价才沉淀下来的经验。第一永远不要跳过Nginx日志。有些人一看到502就忙着重启Nginx、重启后端、清缓存这些操作看着很努力但都属于瞎忙。Nginx的error.log明确记录了连接失败的阶段和具体错误码access.log能告诉你502的比例和分布。日志是最可靠的证据只有基于证据来排查才不会在错误的道路上越走越远。第二排查时善用二分法。比如有多个后端节点你逐个在Nginx上curl每个节点的IP哪个不通就缩小范围到哪个节点如果在同一个节点上进一步区分是TCP层不通connect失败还是HTTP层异常prematurely closed、超时问题。每排查一步就砍掉一半可能的原因比东一榔头西一棒子高效太多。第三不要把监控当成事后诸葛亮。我见过太多团队平时不配告警出了故障才匆忙去服务器上看历史数据结果发现根本没有数据可看。建议至少给Nginx配四个基础监控指标请求量、5xx比例、平均响应时间、上游响应耗时。有了这些指标你能在502爆发前就发现异常趋势——比如上游响应耗时慢慢从500毫秒涨到3秒这大概率就是502的前兆完全可以在用户投诉之前就把问题掐死在摇篮里。第四也是我个人反复强调的解决502永远不要只盯着Nginx一个组件。一个请求从浏览器到后端要经过无数节点Nginx只是其中一个。排查时要把整个链路的图在脑子里画出来客户端、安全组、Nginx、网关、服务、数据库、缓存每一层都可能产生502也都有自己的日志。真正的运维高手不是靠运气修好故障而是靠一套完整的链路视角加上扎实的基础功一步步把问题的范围缩小到最小然后一击命中。