如何用第三方主动健康检查模块实现对 upstream 节点的毫秒级心跳探测

开源 Nginx 默认不支持毫秒级主动心跳探测，需依赖 nginx_upstream_check_module 模块并配置毫秒参数（如 interval=500）；该模块须源码编译集成，OpenResty 已默认内置；支持 HTTP（推荐 RESTful 微服务）和 TCP（适合 gRPC/Dubbo）两种探测类型，均需显式指定 type 并设毫秒级时间参数；通过 check_status json 暴露结构化健康状态，仅限内网监控系统访问。

开源 Nginx 默认不支持毫秒级主动心跳探测，必须依赖 nginx_upstream_check_module 模块，并在配置中将时间参数精确到毫秒单位（如 interval=500），才能实现真正意义上的亚秒级探活。

确认模块已正确编译并启用

该模块无法通过包管理器安装，也不支持运行时加载。需严格按以下步骤验证和部署：

• 执行 nginx -V 2>&1 | grep -o 'upstream_check'，有输出才表示模块已集成
• 若无输出，必须使用与当前 Nginx 版本完全一致的源码（如 1.28.0）+ 匹配补丁（如 check_1.26.1+.patch）+ 对应版本模块（推荐 v0.4.0）重新编译
• OpenResty 是更省事的选择——它默认内置该模块，且配置语法完全兼容 Nginx

配置毫秒级 HTTP 探测（推荐用于 RESTful 微服务）

在 upstream 块中启用 check 指令，并将所有时间参数设为毫秒值。示例：

upstream api_backend {    server 10.0.1.10:8080;    server 10.0.1.11:8080;    check interval=500 rise=2 fall=3 timeout=300 type=http;    check_http_send "GET /actuator/health HTTP/1.1rnHost: api.example.comrnConnection: closernrn";    check_http_expect_alive http_2xx;}

• interval=500：每 500 毫秒发起一次探测，非秒级（interval=1 在部分版本中会被自动归一为 1000ms，建议明确写 500/1000/2000 等整数毫秒值）
• timeout=300：单次请求必须在 300ms 内完成响应，超时即判为失败
• 务必显式声明 type=http，否则 check_http_send 等子指令无效
• 避免用 HEAD，改用 GET 并加 Connection: close，确保后端健康接口能返回完整 JSON（如 {"status":"UP","components":{"db":{"status":"UP"}}）

搭配 TCP 探测实现更低开销的毫秒级保活

当后端是高性能 RPC（如 gRPC、Dubbo）或对延迟极度敏感时，HTTP 探测可能引入额外 GC 和序列化开销。此时可切换为轻量级 TCP 连通性探测：

upstream rpc_backend {    server 10.0.2.20:9090;    server 10.0.2.21:9090;    check interval=200 rise=1 fall=2 timeout=100 type=tcp;}

• interval=200 + timeout=100 可实现 200ms 周期、100ms 超时的极快反馈，适合内网低延迟场景
• TCP 检查仅验证端口可达与三次握手成功，不校验业务逻辑，因此需配合后端自身健康接口做双重保障
• 不支持 check_http_* 类指令，但启动快、资源占用极小，实测在万级连接下 CPU 占用低于 0.3%

暴露状态页并限制访问，支撑监控闭环

启用 check_status 指令，让 Prometheus 或 Zabbix 直接拉取节点实时健康数据：

location /nginx-health {    check_status json;    access_log off;    allow 127.0.0.1;    allow 192.168.100.0/24;  # 仅允许监控服务器网段    deny all;}

• check_status json 输出结构化数据，字段含 status（up/down）、rise、fall、check_count、check_time（毫秒级时间戳）等
• 避免使用 html 格式，不利于自动化采集；禁用日志减少 I/O 压力
• 生产环境严禁开放给公网，防止节点拓扑与状态泄露