Nginx upstream 健康检查实战:max_fails 与 fail_timeout 的同一参数陷阱、5xx 不算失败与开源版没有 health_check

多台后端、一个 Nginx 反代,是很多站到了某个规模之后必然走到的一步:一台机器扛不住,或者想做到发布不中断。配置本身不长,二十行就能跑起来。但真正让人半夜被叫起来的,几乎从来不是"没配 upstream",而是 upstream 里有一台机器已经不干活了,Nginx 却还在往它身上分发请求。

这个问题的表现很有欺骗性:不是全站挂,而是"三成请求超时"、"每刷三次卡一次"、"后台偶尔 502 但刷新就好"。因为剩下的机器还在正常工作,监控上的整体可用性看着还行,用户体验却已经是残废状态。

这篇把 upstream 的健康检查讲清楚:被动检查的阈值怎么算、max_fails 与 fail_timeout 到底是什么关系、主动检查为什么在开源版里没有、以及没健康检查的版本该怎么兜底。

一、默认配置下,Nginx 其实已经在做"被动健康检查"

很多人以为开源版 Nginx 完全不检查后端健康,这个说法不准确。默认情况下 Nginx 是被动检查:只有当请求发过去、失败返回了,它才把这次失败记在账上。相关的是三个参数:

upstream backend {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.13:8080 max_fails=3 fail_timeout=10s;
}

max_fails 是"在 fail_timeout 这个时间窗口内允许失败几次",fail_timeout 是"窗口长度"以及"失败后摘除多久"。两者共用同一个参数,这个设计是理解一切混淆的根源。具体行为是:

在任意一个 10 秒的滑动窗口内,如果某台服务器失败了 3 次,它就被标记为不可用,并且摘除 10 秒;10 秒后 Nginx 会放一个请求过去试探(这个试探请求是真实用户请求,不是探测包),成功就恢复,失败就再摘 10 秒。

这里有两个必须记住的推论。第一,"摘除时间"和"统计窗口"是同一个数字,所以你不能既想要 60 秒的统计窗口又想要 5 秒的快速恢复,一条参数只能表达一个值。第二,max_fails=0 是关闭被动检查,不是"允许无限次失败"——0 的意思是永远不标记为不可用,这台机器会一直留在轮询里。我在一个老配置里见过 max_fails=0,注释写的是"这台机器很稳定",实际上是把它从健康检查体系里彻底摘了出去。

还有一个坑:Nginx 默认的 max_fails 是 1。也就是说你不写这个参数,一台机器只要失败一次就被摘 10 秒。对偶发超时比较敏感的场景,这个默认值偏激进,一次网络抖动就能让整台机器下线十秒,流量全压到剩下几台上,反而可能引发连锁雪崩。至少把它设成 2 或 3,让偶发失败有余量。

二、"失败"的定义比你想的窄:只有这几种情况会记账

被动检查只认连接层面的失败和超时,具体是:连接被拒绝(Connection refused)、连接超时、读超时、以及后端提前关闭连接。它不认 HTTP 业务状态码。

这句话很关键:后端返回 500、502、503,在被动检查眼里是"成功的一次交互"——请求发出去了,响应也回来了,连接建立没有任何问题。所以一台后端即使 PHP 崩了、数据库连不上、每个请求都返回 500,Nginx 依然认为它健康,继续分流量。

如果想让它把 5xx 也算作失败,需要显式配置:

upstream backend {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=15s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=15s;
}

# 在 proxy 段落里
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;

proxy_next_upstream 决定哪些情况会把请求转给下一台,同时也会影响这些响应是否计入失败。默认值是 error timeout,所以默认配置下 502 不会触发转移,用户直接看到错误页。加上 http_502 / http_503 之后,Nginx 会换一台再试一次。

但这里有一个必须慎重的边界:proxy_next_upstream 配合非幂等请求会出事。默认情况下 Nginx 只在"请求还没发出去"或"请求已发出但响应头还没收到"时才会安全地重试;一旦用 non_idempotent 参数把 POST 也纳入重试范围,用户提交的表单可能在两台机器上各执行一次。老站长应该都见过"点一次提交,后台多了两条订单"的鬼故事,源头往往就在这里。我的建议是:只对 GET 放宽重试,POST 保持默认,宁可让用户看到一个错误页,也不要产生两次写入。

proxy_next_upstream_tries 2 限制了最多试几台。不限制的话,五台后端全挂时,一个请求会依次砸过五台,每台都等一个超时——用户等 5×proxy_read_timeout,这比立刻报错还糟。设成 2 是个合理的中间值。

三、主动健康检查:开源版没有,别被博客骗了

Nginx 开源版不支持 health_check 指令。你在很多中文教程里看到的这种写法:

# 这是 Nginx Plus(商业版)或 Tengine 的语法,开源版 nginx -t 会直接报错
location / {
    proxy_pass http://backend;
    health_check interval=5s fails=3 passes=2;
}

它在开源版上会报 unknown directive "health_check"。三个可选方向:

一是 Nginx Plus,商业订阅,个人站基本不考虑。二是把 nginx 换成 Tengine 或 OpenResty——Tengine 是这个指令最早的支持者,OpenResty 则需要装 lua-resty-upstream-healthcheck 这一套。三是在 Nginx 之外做检查:这是小站最实际的方案,一个定时脚本探测后端健康页,不健康就用 Nginx 的 backup 标记或者直接改 upstream 文件 reload。

别小看第三种方案的性价比。后端只有两三台时,一个每分钟跑一次的 curl 循环,配合 upstream_conf 这类工具或者干脆渲染模板 reload,已经能覆盖九成故障。代价是恢复有延迟(最多一分钟),换来的是零额外依赖。

四、如果后端崩了却还在接流量,先看这三处

现象是"某台机器明显不工作了,但请求还是一直打过去",按下面的顺序查,绝大多数能定位:

第一处,连接是长连接吗。这是最常见、也最容易被忽略的。Nginx 到后端的 keepalive 连接一旦建立,会长期保持;后端进程虽然重启了,那条 TCP 连接在 Nginx 这端看来还是"established",直到下一次真正发请求过去才发现断了。这就导致故障后的一段时间里,每个打到这台机器的请求都先失败一次才转移。检查方式:看 upstream_keepalive 是否配置,以及后端的 keepalive_timeout 是否比 Nginx 这端短——后端的 keepalive 应该更短,让后端主动关,Nginx 就不会拿到一条已经死掉的连接。

upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    keepalive 32;
    keepalive_timeout 60s;
    keepalive_requests 1000;
}
# proxy 段必须有这一行,否则 keepalive 不生效
proxy_http_version 1.1;
proxy_set_header Connection "";

漏写 proxy_set_header Connection "" 是另一个高频错误:Nginx 默认会给上游发 Connection: close,upstream 里的 keepalive 配置就完全不起作用,每个请求都新建连接。这个错误不报错、不影响功能,只是让你以为配了长连接。

第二处,健康页是不是被缓存了。如果你用外部脚本检查后端的 /health,而那个路径经过了 CDN 或者 Nginx 自身的 proxy_cache,脚本拿到的可能是缓存里的旧结果——一台挂掉的机器,健康检查一直返回 OK。健康检查的路径必须在所有缓存层上都 bypass,最省事的做法是用一个带随机参数的 URL,或者在 Nginx 里给 /health 精确 location 加 proxy_cache off。

第三处,状态是不是被写在了磁盘上但没被读回来。用脚本渲染 upstream 配置并 reload 的方案,最典型的失败是脚本写了文件、但 reload 失败了(配置语法错、权限不对),于是 Nginx 还在用内存里的旧配置。检查 nginx -t 的返回值和 reload 之后的 nginx -T | grep -A5 upstream,看到的是不是你以为的那份。这一步不能省,因为 reload 失败时 Nginx 是静默保留旧配置的,日志里只有一行 warning。

五、一套能扛住单机故障的最小配置

把上面几条整合起来,这是我在两台后端上用的一份配置,注释里写了每个参数为什么是这个值:

upstream backend {
    least_conn;                                  # 请求耗时差异大时比轮询稳
    server 10.0.0.11:8080 max_fails=3 fail_timeout=15s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=15s;
    keepalive 32;
    keepalive_timeout 60s;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_connect_timeout 3s;                # 建连失败要快速失败
        proxy_send_timeout 10s;
        proxy_read_timeout 30s;                  # 与后端 max_execution_time 对齐

        proxy_next_upstream error timeout http_502 http_503;
        proxy_next_upstream_tries 2;
        proxy_next_upstream_timeout 10s;         # 三次重试总共不超过 10 秒

        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;
    }
}

几个取舍说明。least_conn 而不是默认轮询,是因为内容站的请求耗时差异极大(首页要查库,静态页秒回),轮询会把请求均匀地分给已经排队很长的机器。proxy_connect_timeout 3s 特意设得短:后端整机挂了的时候,建连是立刻被拒绝的,不需要等 30 秒;真正需要长超时的是读阶段。proxy_read_timeout 必须和应用的执行上限对齐——如果 PHP 的 max_execution_time 是 30 秒,Nginx 却只等 10 秒,那就是 PHP 还在干活、Nginx 已经给用户报了 504,还会白白算一次失败。

proxy_next_upstream_timeout 这个参数很少人写,但它决定了"最多折腾多久"。没有它,两台的场景下最坏是 2 次等待,有了它就有了硬上限。

六、上线之后怎么确认它真的在工作

配置写完,光 reload 不算完。至少做三件事。第一,停掉一台后端,观察转移:连续打 20 个请求,看日志里 status 分布,应该是前 3 个失败、之后全部 200,说明摘除生效了;再启动它,等 15 秒,看它是否回到轮询里。

第二,看 upstream 相关日志。Nginx 的 error log 里这类信息的关键词是 upstream、no live upstreams、connect() failed。维护窗口里把这些日志单开一个文件,事后复盘比翻全量日志快得多。

第三,给 upstream 加监控。Nginx 本身不暴露每台后端的健康状态,要么用 stub_status(只有总数),要么在日志格式里带上 $upstream_addr 和 $upstream_status,然后按这两列做聚合。一个页面里 upstream_status 出现两次用逗号分隔(如 502, 200),就说明发生了重试——这是判断重试频率最直接的证据。

log_format upstream_log '$remote_addr $request $upstream_addr '
                        '$upstream_status $upstream_response_time $request_time';
access_log /var/log/nginx/upstream.log upstream_log;

最后一句经验:健康检查这件事,最贵的选择不是配置复杂度,而是以为它在工作。默认参数下 Nginx 确实会摘除挂掉的机器,但它只在"请求失败"之后才动手;这意味着故障发生后,一定有若干个用户请求先替所有人踩了坑。能把这个踩坑的数量控制在个位数,配置就算合格了。

Last modification:November 19th, 2026 at 12:31 pm

Leave a Comment