全异步主动健康检查因传统Nginx轮询阻塞worker进程，而lua-resty-upstream-healthcheck基于cosocket+timer实现非阻塞探测，每个worker独立并发探活，真正零阻塞、无额外线程或进程。
为什么需要全异步主动健康检查
传统 Nginx 的 health_check 指令（如 stream 或 http 模块内置）依赖定时器轮询，且探测逻辑阻塞 worker 进程，高并发下易拖慢整体响应。而 lua-resty-upstream-healthcheck 基于 cosocket + timer 实现纯 Lua 层的非阻塞探测，在不增加系统线程、不 fork 子进程的前提下，让每个 worker 独立、并发地对上游节点发起 HTTP/TCP 探活请求——真正做到了“全异步”与“零阻塞”。
核心配置：启用健康检查模块
确保已安装 lua-resty-upstream-healthcheck（推荐通过 opm 或 luarocks 安装），并在 Nginx 配置中声明 upstream 和 healthcheck 实例：
注意：必须在 init_by_lua_block 中初始化，避免多 worker 重复创建或共享状态冲突
- 在
http块中定义 upstream（仅作路由标识，不参与实际负载） - 用 Lua 创建 healthcheck 实例，绑定到该 upstream 名称
- 设置探测路径、间隔、超时、成功/失败阈值等关键参数
示例片段：
http {
lua_package_path "/path/to/lua-resty-upstream-healthcheck/lib/?.lua;;";
<pre class="brush:php;toolbar:false;">init_by_lua_block {
local hc = require "resty.upstream.healthcheck"
local ok, err = hc.spawn_checker{
-- 必填：关联的 upstream 名称
upstream = "backend_servers",
-- 探测配置
type = "http",
port = 8080,
check_http_send = "GET /health HTTP/1.0\r\nHost: example.com\r\n\r\n",
check_http_expect_alive = {200, 302},
-- 时间与阈值
interval = 2, -- 每 2 秒探测一次
fall = 3, -- 连续 3 次失败标记为 down
rise = 2, -- 连续 2 次成功恢复为 up
timeout = 1 -- 单次探测超时 1 秒
}
if not ok then
ngx.log(ngx.ERR, "failed to spawn health checker: ", err)
end
}
upstream backend_servers {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
server 192.168.1.12:8080;
}
server {
location / {
proxy_pass http://backend_servers;
# 后续可配合 lua_balancer_by_lua_block 实现动态权重或剔除 down 节点
}
}}
如何感知节点状态变化
该模块不自动修改 upstream 配置，而是通过共享内存（shm）暴露实时状态。你可在 Lua 中随时读取：
- 调用
hc.get_status("backend_servers")获取汇总状态（up/down 数量、总节点数） - 调用
hc.get_peers("backend_servers")获取每个 peer 的详细信息（ip、port、checks、falls、status） - 结合
log_by_lua_block记录异常切换，或通过自定义 endpoint（如/healthz）对外暴露集群健康摘要
例如在 log 阶段记录 down 事件：
log_by_lua_block {
local hc = require "resty.upstream.healthcheck"
local peers = hc.get_peers("backend_servers")
for _, p in ipairs(peers) do
if p.status == 0 then -- 0 表示 down
ngx.log(ngx.WARN, "peer down: ", p.ip, ":", p.port,
" falls=", p.falls, " checks=", p.checks)
end
end
}进阶技巧：配合 balancer 动态剔除故障节点
默认 proxy_pass 仍会转发请求到标记为 down 的节点（除非用 keepalive + max_fails）。要实现“真正绕过”，需启用 lua_balancer_by_lua_block：
- 在 upstream 块中启用
least_conn或其他基础策略作为 fallback - 在 balancer 阶段遍历
hc.get_peers()，过滤掉 status == 0 的节点 - 使用
balancer.set_current_peer(ip, port)手动指定后端 - 注意：此方式要求 Nginx 编译时开启
--with-http_upstream_module及 Lua 支持
这样就能在请求入口层完成“实时熔断”，比被动 fail_timeout 更灵敏，也比静态配置更弹性。
