Nginx主动健康检查

一、引言：被动健康检查的“致命盲区”

在绝大多数Nginx配置中，upstream的健康保障依赖于max_fails和fail_timeout这两个参数。这是一种被动健康检查（Passive Health Check）机制：只有当真实用户请求打到某个后端节点并失败时，Nginx才会将其标记为不可用。

这种“用真实流量试错”的模式在生产环境中存在三个致命缺陷：

• 首请求必损：节点刚恢复或刚上线时，第一批请求必然命中尚未被标记的故障节点，用户体验直接受损；
• 故障感知滞后：若某节点流量占比低（如权重1/10），可能需要数十秒甚至数分钟才能积累足够的失败次数触发摘除；
• 恢复探测粗暴：fail_timeout到期后，Nginx直接将节点重新放入池中，没有渐进式验证，若节点未完全恢复，新一轮真实请求再次成为“炮灰”。

主动健康检查（Active Health Check）正是为解决这些问题而生。它由Nginx独立发起周期性探测请求，与业务流量完全隔离，实现：

• ✅ 故障提前发现，用户请求零损伤；
• ✅ 新节点上线前预检，通过后才接入流量；
• ✅ 恢复过程可控，支持慢启动和渐进放量；
• ✅ 多维度判定，不仅看TCP连通性，还验证HTTP状态码、响应体内容、响应时间等。

本文将从开源与商业版的方案对比出发，深度拆解主动健康检查的配置语义、高级策略和生产级落地模板，帮你构建真正“用户无感”的后端容错体系。

二、方案选型：三条技术路线的全景对比

本文后续内容聚焦OpenResty方案，因其是开源生态中最接近Nginx Plus能力的生产级选择，且原理可迁移至其他方案。📌选型建议：

• K8s环境：优先使用Ingress Controller的原生健康检查，与Pod Readiness Probe联动；
• 非K8s + 预算充足：Nginx Plus是最优解，功能完整、官方支持；
• 非K8s + 开源需求：OpenResty + lua-resty-upstream-healthcheck是事实标准；
• 极简场景/学习：原生被动检查足够，但务必理解其局限。

三、OpenResty主动健康检查核心架构

3.1 工作原理

┌─────────────────────────────────────────────────────┐ │ OpenResty Worker │ │ │ │ ┌──────────────┐ ┌───────────────────────────┐ │ │ │ Timer Module │───▶│ Health Check Coroutine │ │ │ │ (定时触发) │ │ 1. 遍历upstream节点列表 │ │ │ └──────────────┘ │ 2. 发起HTTP/TCP探测请求 │ │ │ │ 3. 校验响应(状态码/Body) │ │ │ ┌──────────────┐ │ 4. 更新共享内存中的健康状态 │ │ │ │ Shared Dict │◀──▶│ │ │ │ │ (健康状态存储)│ └───────────────────────────┘ │ │ └──────┬───────┘ │ │ │ 读取 │ │ ┌──────▼───────┐ │ │ │ Balancer │ ← 业务请求到达时，仅选择健康节点 │ │ │ (负载均衡器) │ │ │ └──────────────┘ │ └─────────────────────────────────────────────────────┘

📌关键设计：

• 健康检查运行在独立协程中，不阻塞业务请求处理；
• 健康状态存储在shared dict中，跨worker共享，避免重复探测；
• Balancer阶段只读取状态、不做探测，保证请求处理延迟不受影响。

3.2 核心组件安装

# 确保OpenResty已安装 # 安装lua-resty-upstream-healthcheck luarocks install lua-resty-upstream-healthcheck # 或使用opm（推荐） opm get openresty/lua-resty-upstream-healthcheck

四、基础配置：从零搭建主动健康检查

4.1 最小可用配置

http { # ===== 共享内存：存储健康状态 ===== lua_shared_dict healthcheck 10m; # ===== 初始化健康检查器 ===== init_worker_by_lua_block { local hc = require "resty.upstream.healthcheck" local ok, err = hc.spawn_checker({ shm = "healthcheck", upstream = "api_backend", type = "http", http_req = "GET /health HTTP/1.1\r\nHost: api-backend\r\n\r\n", interval = 2000, -- 每2秒探测一次 timeout = 1000, -- 探测超时1秒 fall = 3, -- 连续3次失败 → 标记不健康 rise = 2, -- 连续2次成功 → 标记健康 valid_statuses = {200}, -- 仅200视为健康 }) if not ok then ngx.log(ngx.ERR, "failed to spawn health checker: ", err) end } # ===== Upstream定义 ===== upstream api_backend { server 10.0.1.10:8080; server 10.0.1.11:8080; server 10.0.1.12:8080; } server { location /api/ { proxy_pass http://api_backend; } # ===== 健康检查状态查看接口 ===== location = /upstream_health { content_by_lua_block { local hc = require "resty.upstream.healthcheck" local status = hc.get_status("api_backend") ngx.say(status) } } } }

4.2 核心参数详解

⚠️关键注意：http_req必须是完整的原始HTTP请求，包括方法、路径、协议版本、Host头和空行。缺少任何部分都会导致探测失败。推荐使用string.format动态构造：

http_req = string.format( "GET %s HTTP/1.1\r\nHost: %s\r\nUser-Agent: nginx-healthcheck\r\nConnection: close\r\n\r\n", "/health", "api-backend" )

五、高级策略：超越“通/不通”的精细化治理

5.1 多维度健康判定

-- 自定义校验函数：状态码 + 响应体 + 响应时间三重验证 local function custom_checker(resp_status, resp_body, resp_time) -- 条件1：状态码必须200 if resp_status ~= 200 then return false end -- 条件2：响应体必须包含"OK" if not resp_body or not string.find(resp_body, '"status"%s*:%s*"ok"') then return false end -- 条件3：响应时间不超过500ms if resp_time > 500 then return false end return true end hc.spawn_checker({ -- ... 其他参数 checker = custom_checker, -- 替代valid_statuses })

📌价值：后端返回200但实际处于降级状态（如数据库连接池耗尽、缓存全miss）时，传统状态码检查无法识别。内容+延迟双重校验能捕获这类“假健康”节点。

5.2 差异化探测策略

不同后端服务的健康特征不同，应为每个upstream定制探测参数：

5.3 与新节点上线联动

-- 新节点加入upstream后，先执行预检再放行流量 local function pre_check_new_node(host, port) local hc = require "resty.upstream.healthcheck" local ok = hc.single_check("api_backend", host, port, { timeout = 2000, valid_statuses = {200}, }) if ok then ngx.log(ngx.INFO, "new node ", host, ":", port, " passed pre-check") -- 调用服务发现API注册节点 else ngx.log(ngx.WARN, "new node ", host, ":", port, " failed pre-check, skipping") end end

📌零停机发布的关键：新Pod/容器启动后，先通过主动健康检查验证就绪，再注册到upstream。彻底消除“刚上线就被打挂”的经典问题。

5.4 慢启动与渐进放量

OpenResty原生不支持slow_start，可通过自定义Balancer实现：

local node_recovery_time = {} -- shared dict记录节点恢复时间 function balanced_peer(premature, upstream_name) local peers = get_healthy_peers(upstream_name) local now = ngx.now() for _, peer in ipairs(peers) do local recovery_ts = node_recovery_time[peer.id] if recovery_ts then local elapsed = now - recovery_ts if elapsed < 30 then -- 30秒慢启动窗口 -- 按时间比例降低权重 peer.weight = math.floor(peer.base_weight * (elapsed / 30)) else node_recovery_time[peer.id] = nil -- 恢复正常 end end end return select_peer_by_weight(peers) end

📌价值：节点恢复后立即承受全量流量可能导致二次崩溃（如JIT未预热、连接池为空、缓存冷启动）。慢启动让流量线性增长，给后端充分的“热身”时间。

六、可观测性：健康检查本身的监控

6.1 暴露健康状态API

location = /nginx_upstream_status { content_by_lua_block { local cjson = require "cjson.safe" local hc = require "resty.upstream.healthcheck" local result = {} local upstreams = {"api_backend", "auth_backend", "cache_backend"} for _, name in ipairs(upstreams) do result[name] = hc.get_status(name) end ngx.header.content_type = "application/json" ngx.say(cjson.encode(result)) } }

6.2 Prometheus指标导出

-- 在/content_metrics中输出 local hc = require "resty.upstream.healthcheck" local status = hc.get_status("api_backend") -- 解析status字符串，提取各节点状态 for node, state in pairs(parse_status(status)) do ngx.say(string.format( 'nginx_upstream_health{upstream="api_backend",node="%s"} %d', node, state == "healthy" and 1 or 0 )) end

6.3 必采监控指标

七、生产安全检查清单

八、常见踩坑速查表

九、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！