Nginx upstream健康检查配置与节点摘除

upstream健康检查决定了 Nginx 在多台后端之间转发时,多久能发现某个节点已经不可用,并把它从轮询里摘出去。这件事在安全场景下比在可用性场景下更关键:被入侵的后端往往仍然返回 200,只是内容被改写、跳转被劫持,默认的被动检查完全看不出来,流量就会一直打在这台已经失守的机器上。本文给出被动检查与主动检查两套配置,并补一层内容级校验,用于识别「活着但已经不正常」的节点。

适用场景

  • Nginx 反向代理两台以上后端(PHP-FPM、Tomcat、Node、Java 服务),未配置任何健康检查参数;
  • 后端曾出现被挂马、被植入跳转脚本、返回博彩页面,但服务进程仍在正常运行;
  • 单节点被 CC 打满 CPU,连接排队导致整体响应时间被拖长,需要自动摘除;
  • 使用云主机且没有负载均衡器,健康检查完全依赖 Nginx 自身;
  • 发布过程中需要灰度摘节点,希望有可程序化触发的摘除开关。

前置条件

  • Nginx 1.18 及以上;被动健康检查为内置功能,主动检查需要额外模块或 OpenResty;
  • 每台后端提供一个轻量健康检查端点,只做依赖探测,不查业务库全表;
  • 具备重新编译 Nginx 的能力(主动检查方案需要),或已使用 OpenResty;
  • 备份配置:cp -a /etc/nginx /etc/nginx.bak.$(date +%F);
  • 明确各接口的幂等性,这决定 proxy_next_upstream 能否覆盖 non_idempotent 请求。

原理说明

Nginx 开源版只有被动健康检查(passive health check)。它的判断依据是真实业务请求的失败次数:某个 server 连续失败达到 max_fails 次,就在 fail_timeout 时间内把它标记为不可用,期间不再分配新请求;fail_timeout 到期后放一个请求过去试探,成功则恢复。

关键陷阱在「什么算失败」。默认 proxy_next_upstream 只包含 error 与 timeout,也就是连接失败、超时这类传输层错误。后端返回 500、502、403、404 都不算失败,不会累加 max_fails。这意味着进程还在、只是业务已经坏掉的节点永远摘不掉——而这恰好是被入侵节点最典型的状态。

主动健康检查(active health check)由 Nginx 自己按固定间隔发探测请求,不需要等真实用户流量。开源 Nginx 不带这个能力,需要两条路:编译 nginx_upstream_check_module,或使用 OpenResty 的 lua-resty-healthcheck。主动检查的优势是发现快、不依赖用户请求,劣势是会额外产生探测流量,且只能看状态码,看不出返回内容是否被篡改。

因此完整的隔离要三层:被动检查覆盖状态码异常、主动检查缩短发现时间、内容指纹校验识别「200 但内容变了」。前两层都是状态码维度,第三层才是内容维度,缺了它,挂马节点可以长时间驻留。

操作步骤

第一步:摸清当前配置与真实失败行为

不要凭印象判断有没有配健康检查,直接看编译参数与生效配置:

# 1) 是否已编译主动检查模块
nginx -V 2>&1 | tr ' ' '\n' | grep -E 'upstream_check|http_healthcheck'

# 2) 现有 upstream 是否配置了 max_fails / fail_timeout
nginx -T 2>/dev/null | grep -nE 'upstream |server .*max_fails|proxy_next_upstream'

# 3) 手工验证某台后端的状态码行为
for ip in 10.0.0.11 10.0.0.12; do
  echo "== $ip =="
  curl -s -o /dev/null -w 'code=%{http_code} time=%{time_total}\n' \
       --max-time 3 "http://$ip:8080/healthz"
done

第 1 条无输出说明只能用被动检查;第 2 条若没看到 max_fails,说明正在用默认值(1 次失败、10 秒摘除),这个默认值对 CC 场景过于敏感,对挂马场景又完全无效。

第二步:配置被动健康检查,覆盖状态码失败

核心改动是把 proxy_next_upstream 从默认值扩展为包含 5xx、403、429,并显式给每个 server 设置失败阈值:

upstream backend_app {
    zone backend_app 64k;

    # 3 次失败摘除,30 秒后放行一个探针;fail_timeout 也是探针间隔
    server 10.0.0.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=30s;

    # 备用节点:主节点全部不可用时才接管,用于返回维护页
    server 10.0.0.13:8080 backup;

    keepalive 32;
}

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

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

        # 关键:把这些状态码都算作该节点失败
        proxy_next_upstream error timeout http_500 http_502 http_503 http_504 http_403 http_429;
        # 最多换 2 个节点,避免单请求把整个池都试穿
        proxy_next_upstream_tries 2;
        proxy_next_upstream_timeout 10s;

        proxy_connect_timeout 3s;
        proxy_read_timeout 15s;
        proxy_send_timeout 15s;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

两个参数需要按业务性质调整。http_403 是否计入失败要看站点情况:若 403 是正常的权限拒绝(例如未登录访问会员内容),把它算作节点失败会导致后端被误摘,此时应当移除;若 403 来自 WAF 或防盗链的异常拦截,保留它有价值。non_idempotent 默认不在 proxy_next_upstream 里,因为重发 POST 可能造成重复下单,除非接口带幂等键,否则不要加。

第三步:加主动健康检查(编译模块方案)

主动检查能把发现时间从「等用户踩坑」缩短到秒级。以 nginx_upstream_check_module 为例,先给源码打补丁再编译:

# 1) 取与当前 Nginx 同版本的源码与模块
cd /usr/local/src
NGX_VER=$(nginx -v 2>&1 | sed 's#.*/##')
wget -q http://nginx.org/download/nginx-$NGX_VER.tar.gz
tar xf nginx-$NGX_VER.tar.gz
git clone --depth 1 https://github.com/yaoweibin/nginx_upstream_check_module.git
cd nginx-$NGX_VER

# 2) 打补丁(按 Nginx 版本选对应 patch)
patch -p1 < ../nginx_upstream_check_module/check_1.20.1+.patch

# 3) 沿用原有编译参数,追加模块后编译安装
./configure $(nginx -V 2>&1 | grep 'configure arguments' | sed 's/.*arguments: //') \
    --add-module=../nginx_upstream_check_module
make -j"$(nproc)" && make install
nginx -V 2>&1 | grep -o upstream_check_module

# 4) 配置主动探测
cat >/etc/nginx/conf.d/upstream_check.conf <<'EOF'
upstream backend_app {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=30s;

    # 每 3 秒探测一次,连续 2 次成功才恢复,连续 3 次失败即摘除
    check interval=3000 rise=2 fall=3 timeout=2000 type=http;
    check_http_send "HEAD /healthz HTTP/1.0\r\nHost: localhost\r\nConnection: close\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

server {
    listen 127.0.0.1:8090;
    location /upstream_status {
        check_status;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}
EOF
nginx -t && systemctl reload nginx

# 5) 查看各节点状态:up / down / checking
curl -s http://127.0.0.1:8090/upstream_status

状态端点必须只监听回环或内网并加 allow/deny,否则会对外暴露后端 IP 与存活状态,等于替攻击者做了资产测绘。

第四步:加内容指纹校验,识别「200 但已被篡改」

状态码检查对挂马无能为力:被注入的页面依然返回 200。判断内容是否被改,最省成本的做法是校验响应体特征串与体积区间。用 OpenResty 的 lua-resty-healthcheck 加自定义校验可以做到:

# nginx.conf 中 http 段
lua_shared_dict healthcheck 1m;
lua_socket_log_errors off;
init_worker_by_lua_block {
    local hc = require "resty.healthcheck"
    local checker = hc.new("backend_app")
    checker:set_timeouts(1000, 1000, 1000)
    checker:add_target("10.0.0.11", 8080, "http", { name = "n1" })
    checker:add_target("10.0.0.12", 8080, "http", { name = "n2" })

    -- 自定义校验:状态码 2xx 之外,还要求正文含站点固定指纹
    local function custom_check(host, port)
        local httpc = require("resty.http").new()
        httpc:set_timeout(2000)
        local res, err = httpc:request_uri("http://" .. host .. ":" .. port .. "/healthz", {
            method = "GET",
            headers = { Host = "www.example.com" },
        })
        if not res then return false, err end
        if res.status ~= 200 then return false, "status " .. res.status end
        -- 指纹串由发布流程写入,挂马或整站替换后必然不匹配
        if not string.find(res.body, "BUILD_FINGERPRINT=", 1, true) then
            return false, "fingerprint missing"
        end
        -- 体积突变(例如被插入大段外链)同样判为异常
        if #res.body < 200 or #res.body > 8192 then
            return false, "body size abnormal"
        end
        return true
    end

    checker:add_target("10.0.0.11", 8080, "http", { check = custom_check })
    checker:add_target("10.0.0.12", 8080, "http", { check = custom_check })
    checker:set_interval(5)   -- 每 5 秒探测
    checker:set_fall(3)       -- 连续 3 次失败摘除
    checker:set_rise(2)       -- 连续 2 次成功恢复
}

指纹串由发布流水线在构建时写入 /healthz 输出,每次发版变化。一旦节点被植入跳转脚本或整站替换,指纹必然对不上,从而被自动摘除。这条链路的价值高于状态码检查:它检测的是内容完整性,而不是进程存活。

第五步:把节点状态接进告警

摘除只是止血,必须有人知道。把状态端点转成可采集的指标,接进已有的监控:

# 方式一:用 nginx-prometheus-exporter 之外的轻量脚本导成文本指标
cat >/usr/local/bin/upstream_metrics.sh <<'EOF'
#!/bin/sh
# 从 check_status(json 格式)转 Prometheus 文本格式
curl -s 'http://127.0.0.1:8090/upstream_status?format=json' \
| jq -r '.servers[] | "nginx_upstream_up{upstream=\"\(.upstream)\",
   server=\"\(.name)\"} \(if .status=="up" then 1 else 0 end)"'
EOF
chmod +x /usr/local/bin/upstream_metrics.sh

# 方式二:直接定时巡检并在状态变化时推送告警
*/1 * * * * /usr/local/bin/upstream_metrics.sh | grep ' 0$' \
  && echo "upstream node down" | mail -s "[ALERT] nginx upstream down" ops@example.com

配置验证

  • 被动摘除生效:在后端执行 systemctl stop app,连续请求 3 次后该节点应停止接流量,日志出现 upstream timed out 或 connect() failed;
  • 状态码摘除生效:让后端 /healthz 返回 500,观察该节点在 max_fails 次后被摘除,30 秒后自动探回;
  • 主动探针生效:curl -s http://127.0.0.1:8090/upstream_status 中该节点状态由 up 变为 down,恢复服务后变回 up;
  • 内容校验生效:手动删除后端的指纹行,5 至 15 秒内该节点应被判 down;恢复后自动回池;
  • 备用节点接管:把两台主节点全部停掉,请求应落到 backup 节点并返回维护页,而不是 502;
  • 状态端点不对外:从公网访问 /upstream_status 必须返回 403,本机访问正常。

验证时建议用 tail -f /var/log/nginx/error.log 同步观察,no live upstreams 说明所有节点都被摘除,此时应立刻检查探针配置是否过于严格。

常见问题

问:配了 max_fails=3,为什么后端返回 502 却一直没被摘除?

因为默认的 proxy_next_upstream 不含 http_502。Nginx 只把连接失败与超时计入失败次数,后端自己返回的 5xx 属于「正常响应」,不会累加。必须显式写出 http_500 http_502 http_503 http_504 才会生效,这是最常见的一处配置遗漏。

问:主动检查会不会把正常节点误摘?

会,主要来自三个原因:探测路径指向了会查数据库的接口,高峰期超时;fall=3 配 interval=1000 过于激进,抖动即摘;健康检查端点被 WAF 或鉴权中间件拦住返回 403 或 302。对策是把探测路径做成纯内存判断(只查进程状态与配置加载时间),把 interval 放到 3 至 5 秒,并把探针来源 IP 加入白名单。

问:摘除节点后,正在处理的请求会怎样?

已经建立的连接不会被立即切断,会按 proxy_read_timeout 走完或超时。proxy_next_upstream 的重试只对尚未向客户端发送任何响应字节的请求有效,一旦开始回传响应体就无法切换节点。因此 proxy_read_timeout 不要设得过大,否则一个卡死节点会长期占用连接。

问:只有一台后端,健康检查还有意义吗?

有,用法不同。单节点时可以把检查结果接到告警与自动重启(配合 systemd 或 supervisor),并把 backup 指向一个返回维护页的静态服务,让异常时用户看到明确提示而不是 502。内容指纹校验同样有意义,它能发现单节点被挂马。

总结

upstream 健康检查的落地要点只有三条:把 proxy_next_upstream 从默认的 error timeout 扩展到状态码维度,否则坏掉的节点永远摘不掉;用主动检查把发现时间压到秒级,避免用真实用户流量做探测;再加一层内容指纹校验,覆盖「进程活着但内容已被篡改」这个状态码检查的盲区。三层都就位后,被入侵的节点会在几十秒内被隔离,而不是持续对外提供被污染的页面。

最后补一条运营层面的动作:把健康检查状态纳入日常巡检看板,任何一次非计划的节点摘除都应该触发排查,而不是被「自动恢复了」掩盖过去。摘除是止损,排查才是根因处置。