Nginx上游服务器返回502怎么办?upstream连接与超时配置分析

用 Nginx 做反向代理时,502 Bad Gateway 几乎是运维绕不开的一课。它的字面意思是"网关收到了上游(upstream)的无效响应",翻译成大白话就是:Nginx 把请求转给后端,但没能从后端拿到一个像样的答复。后端是 Tomcat、Spring Boot、PHP-FPM、Node 还是 Python 服务,都可能出现这种情况,而根因既可能在 Nginx 配置里,也可能在后端本身,甚至可能在更外面的负载均衡或 CDN 上。

这篇文章专门围绕"upstream"这条链路展开:先讲 Nginx 和上游之间一次请求到底经历了哪几个阶段,再逐个拆解 upstream 块、proxy_* 超时、proxy_next_upstream 故障转移、长连接复用这些配置项,最后给出一套从日志到实操的排查流程。文中涉及的超时时间、连接数都是常见经验值,请结合业务实测调整。

读完之后,你应该能看懂 error.log 里那条 upstream 报错到底在说什么,知道该改哪个指令、改多大,也明白哪些改动有风险、怎么回滚。因为改代理配置直接影响线上可用性,文中所有配置修改都会强调 nginx -t 校验和保留旧配置。

一、先把 upstream 链路拆开

一次反向代理请求,Nginx 和上游之间大致经过四步,每一步失败的表现不同:

  1. 建立连接:Nginx 向上游 IP:Port 发起 TCP 连接。连不上 → 502(connection refused / no route to host)。
  2. 发送请求:把请求行、头、体发给上游。中途断开 → 502(upstream prematurely closed connection)。
  3. 等待响应:等上游返回响应头和数据。等太久 → 504(upstream timed out);上游返回畸形响应 → 502(upstream sent invalid header)。
  4. 读取响应体:把响应体读回并转发给客户端。上游中途断开 → 502。

理解这四步,就能把"502 还是 504"这件事看透:502 基本等于"连接或响应层面出问题",504 是"时间超了"。所以排查 502,重点在"连接是否建立、上游进程是否活着、响应是否合法"。

一个基础的反向代理配置长这样:

upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

server {
    listen 80;
    server_name www.example.com;

    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

二、upstream 块的关键参数

upstream 块定义后端服务器列表和调度策略,几个参数直接影响可用性:

指令 作用 常用取值(经验值)
server 定义后端节点 IP:PORT,可加 weight、max_fails、fail_timeout
weight 权重 默认 1,按机器性能配比
max_fails 失败几次判定不可用 默认 1,建议 2~3
fail_timeout 判定不可用的观察窗口/摘除时长 默认 10s,可设 10~30s
keepalive 与上游保持的闲置长连接数 视并发,如 32~128
least_conn / ip_hash 调度策略 长连接业务用 ip_hash,通用用默认轮询
upstream backend {
    least_conn;                       # 按最少连接数调度
    server 127.0.0.1:8080 weight=3 max_fails=3 fail_timeout=15s;
    server 127.0.0.1:8081 weight=1 max_fails=3 fail_timeout=15s;
    keepalive 64;                     # 保持 64 条到上游的空闲长连接
}

max_fails 与 fail_timeout 是 502 的"减震器":当某节点连续失败到 max_fails 次,Nginx 会在 fail_timeout 时间内把它摘掉,请求转给其他节点,用户就不一定看到 502。但要注意:如果只有一个 upstream 节点,摘掉就没得转,用户直接吃 502。所以生产环境建议至少两个实例。

这里有个容易误解的点:max_fails 默认值是 1,意味着一次失败就立刻摘除节点。听起来很"灵敏",但放在有瞬时抖动的网络上就过于激进了——后端偶尔一个慢请求触发超时,节点就被判定不可用,反而可能把健康节点也摘了,于是出现 no live upstreams 全线 502。所以生产环境通常把 max_fails 调到 2~3,fail_timeout 保持 10~30s(经验值),给后端一点容错的余地,同时又不至于让故障节点长期停留在池子里。

三、proxy 超时四件套

超时配置是 502/504 排查的核心。四个超时各管一段:

指令 管什么 默认值 经验取值
proxy_connect_timeout 建立到上游的连接 60s 3~5s
proxy_send_timeout 向上游发送请求 60s 30~60s
proxy_read_timeout 等待上游响应 60s 30~60s(慢接口可放宽)
send_timeout 向客户端发送响应 60s 30~60s
location /api/ {
    proxy_pass http://backend;
    proxy_connect_timeout 5s;      # 连不上快速失败,别让用户干等
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
    proxy_next_upstream error timeout http_502 http_503 http_504;
    proxy_next_upstream_tries 2;   # 最多重试 2 次
    proxy_next_upstream_timeout 10s;
}

为什么 proxy_connect_timeout 建议调小到 3~5s? 如果后端宕了、端口没人监听,操作系统会很快返回"连接被拒",此时连接超时用不上;但如果后端机器网络不通(比如网络设备丢包)、SYN 得不到响应,连接会一直挂到 proxy_connect_timeout 才报错。把这个值设小,能让失败更快暴露、更快切换到其他节点,减少用户等待。默认 60s 太长,用户体验很差。

proxy_next_upstream 是故障转移的关键:它列出"遇到哪些情况就换下一个上游节点重试"。error 覆盖连接错误,timeout 覆盖超时,http_502/503/504 覆盖上游返回的错误码。重试要求请求幂等,对 POST 支付、下单这类非幂等请求要格外小心,重试可能导致重复提交,业务侧需要配合幂等设计。

四、几个高频 502 根因与对应处理

根因一:后端进程不在了。 看进程和端口:

sudo ss -lntp | grep 8080        # 端口在不在
ps -ef | grep -i java | grep -v grep
sudo journalctl -u myapp -n 100 --no-pager    # 看服务日志(systemd 托管)

根因二:端口/地址写错。 后端实际监听 8081,Nginx 却写 8080。用 ss 对照 proxy_pass 逐字核对。

根因三:SELinux 拦截(RHEL 系)。 表现是 Nginx 能本地 curl 通但通过 Nginx 访问 502,且 audit.log 有 AVC 拒绝。处理:

# 查看最近被拒绝的记录
sudo ausearch -m avc -ts recent
# 允许 nginx/httpd 发起网络连接
sudo setsebool -P httpd_can_network_connect on

风险提示:不要用 setenforce 0 永久关闭 SELinux 来"解决"502,应通过布尔值或策略调整放行。若临时关闭排查,记得 setenforce 1 恢复。

根因四:上游响应头过大/不合法。 后端返回的超大头或畸形头会让 Nginx 报 upstream sent invalid header 或 upstream sent too big header。可适当调大缓冲:

proxy_buffer_size 16k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;

根因五:keepalive 配置不当。 想让 Nginx 与上游复用长连接,除了 upstream 里写 keepalive 64,还必须同时设置:

upstream backend {
    server 127.0.0.1:8080;
    keepalive 64;
}
location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;                # 长连接需要 HTTP/1.1
    proxy_set_header Connection "";        # 清掉 close,避免连接不复用
}

漏了后两条,keepalive 形同虚设,还会频繁建连,高并发下更容易出现 502。

五、一套可执行的排查流程

按顺序执行,基本能从"一片 502"收敛到具体原因:

# 1. 看 Nginx error.log,抓 upstream 报错原文
sudo tail -f /var/log/nginx/error.log
# 关键短语:
#   connect() failed (111: Connection refused)  -> 后端没监听/进程挂
#   no live upstreams                            -> 所有节点都被摘除
#   upstream prematurely closed connection       -> 后端主动断开/崩溃
#   upstream sent invalid header                 -> 响应头异常
#   upstream timed out (110)                     -> 超时(更偏 504)

# 2. 从 Nginx 机器直接打后端,绕过代理验证
curl -v http://127.0.0.1:8080/health
curl -w "connect=%{time_connect} total=%{time_total}\n" -o /dev/null -s http://127.0.0.1:8080/

# 3. 看后端进程/端口/日志
sudo ss -lntp | grep 8080
sudo journalctl -u myapp -n 200 --no-pager

# 4. 多节点时确认存活节点数
# Nginx 不直接暴露 upstream 状态,可看错误日志里是否有 no live upstreams

改配置的标准动作:先备份 → 改 → nginx -t 校验 → nginx -s reload → 观察 error.log。回滚就是把 .bak 复制回去再 reload。

sudo cp /etc/nginx/conf.d/app.conf /etc/nginx/conf.d/app.conf.bak
sudo vim /etc/nginx/conf.d/app.conf
sudo nginx -t && sudo nginx -s reload
# 回滚:sudo cp /etc/nginx/conf.d/app.conf.bak /etc/nginx/conf.d/app.conf && sudo nginx -t && sudo nginx -s reload

发布期 502 的治理:应用停止/启动期间端口不可用,是 502 的高发时段。解决办法是优雅停机(处理完在途请求再退出)、多实例滚动发布,并在 Nginx 侧配 proxy_next_upstream 把请求导到健康节点,让用户在发布期间几乎无感。

六、监控与预防

光靠人肉看日志不够,建议给 upstream 健康状态加监控:Nginx 商业版有 upstream 状态页,开源版可以借助 nginx-prometheus-exporter 或直接采集 error.log 里的 upstream 错误做告警。经验做法是:

  • 对 error.log 里 upstream 关键字做计数告警,5 分钟内超过阈值(如 10 次,经验值)就提醒。
  • 给每个后端实例配 upstream 健康检查(max_fails/fail_timeout 是内置的被动检查)。
  • 后端服务增加 /health 接口,配合负载均衡或编排平台做主动健康检查。

另外要提醒的是,502 的排查不能只盯 Nginx 一侧。如果 Nginx 前面还有一层云负载均衡或 CDN,它们自己也可能产生 502,且它们的错误日志往往不在你的服务器上。遇到"改了半天 Nginx 都没用"的情况,先确认 502 到底是哪一层返回的:用 curl -v 看响应里的 Server 头、看有没有 CDN 的特征头(如 Via、X-Cache),必要时直接绕开外层、用后端机器 IP 直连验证。只有先把"是谁在报 502"这件事钉死,后面的排查才不会做无用功。

常见问题

Q1:只有一台后端,出现 502 怎么快速定位?
先用 ss -lntp 确认后端端口在不在,再用 curl 直连后端。若直连不通,问题在后端;若直连通但 Nginx 报 502,重点看 SELinux、proxy_pass 地址和响应头大小。

Q2:proxy_connect_timeout 设多大合适?
经验上 3~5s。设太大会让网络不通的后端拖着用户等待,设太小在跨机房高延迟链路可能误判。内网同机建议 2~3s,跨机房可 5s 左右。

Q3:proxy_next_upstream 重试会导致订单重复吗?
可能。对非幂等请求(下单、支付)要谨慎开启重试,或让后端做幂等(唯一请求号去重),否则一次请求被重试两次可能产生两笔业务。

Q4:配了 keepalive 但连接还是不复用?
检查是否同时设置了 proxy_http_version 1.1 和 proxy_set_header Connection "",缺一个都会让长连接失效。

Q5:no live upstreams 是什么意思?
所有上游节点都被判定为不可用(失败次数达到 max_fails 被摘除)。此时要么后端全挂,要么 max_fails 设得太小、把健康节点也误摘了。

总结

  • 502 的本质是 Nginx 无法从上游拿到有效响应,重点查"连接能否建立、后端进程是否存活、响应是否合法",与"等太久"的 504 区分开。
  • upstream 块用 max_fails/fail_timeout 做被动摘除、keepalive 复用长连接;后者必须配合 proxy_http_version 1.1 和清空 Connection 头才生效。
  • 超时四件套各管一段,proxy_connect_timeout 建议 3~5s(经验值)让故障快速暴露,proxy_read_timeout 管等待上游响应。
  • proxy_next_upstream 能自动故障转移,但重试仅适用于幂等请求,非幂等业务需配套幂等设计。
  • 排查按"看 error.log 的 upstream 原文 → 直连后端验证 → 查进程/端口/SELinux → 改配置先备份后 nginx -t 再 reload"执行,最稳。