ngx_http_upstream_hc_module 是 nginx plus（r12+）专有模块，提供主动健康检查功能，开源版 nginx 不支持；需通过 nginx -v、/status 页面或安装源确认版本，配置使用 health_check 指令并确保后端提供 /health 接口。
ngx_http_upstream_hc_module 是 Nginx Plus（商业版）提供的模块，用于对 upstream 服务器执行主动式健康检查（Active Health Checks），它会定期向后端节点发送探测请求，并根据响应状态自动标记或恢复节点的可用性。开源版 Nginx 不包含该模块，无法直接启用。
确认你使用的是 Nginx Plus
该模块仅存在于 Nginx Plus（R12 及以上版本），开源 Nginx（nginx.org 发布的版本）不支持。可通过以下方式确认：
- 运行 nginx -V，查看输出中是否包含 nginx-plus 或 build by nginx.com
- 访问 http://your-nginx-host/status（需启用 stub_status），Nginx Plus 会返回含 health check 统计的 JSON 格式状态页
- 查阅安装来源：是否通过 nginx.com 官方仓库安装（如 apt/yum 源为 nginx-plus）
配置主动健康检查的基本步骤
在 upstream 块中启用 health_check 指令，配合 location 使用 proxy_pass 转发即可。示例配置如下：
server 192.168.1.10:8080;
server 192.168.1.11:8080;
health_check interval=5 fails=3 passes=2 uri=/health timeout=1;
}
server {
location / {
proxy_pass http://backend;
}
}
说明：
- interval=5：每 5 秒发起一次健康检查请求
- fails=3：连续 3 次失败则标记为 unhealthy
- passes=2：连续 2 次成功则恢复为 healthy
-
uri=/health：向每个 upstream server 的
/health路径发起 GET 请求（需后端真实提供该接口） - timeout=1：单次检查超时时间为 1 秒
可选增强配置
提升健壮性和可观测性：
- 使用 match 块自定义响应校验逻辑，例如要求 HTTP 状态码为 200 且响应体包含
"ok" - 添加 port 参数指定健康检查使用的端口（不同于服务端口），便于隔离探测流量
- 启用 health_check_shm_size（全局指令）增大共享内存，支撑大规模 upstream 和高频率检查
- 结合 status_zone 和 status 指令，在
/status页面查看各节点实时健康状态与统计
验证与排错要点
常见问题及应对方式：
- 后端未实现
/health接口 → 返回 404 导致持续 fail，需确保该路径返回 200 + 合理响应体 - 防火墙或安全组拦截探测请求 → 检查 upstream server 是否允许来自 Nginx Plus 所在 IP 的入向连接
- 检查日志中是否有
health check failed记录（默认记录在 error_log 中，级别为 warn） - 用
curl -v http://192.168.1.10:8080/health手动模拟探测，确认响应行为符合预期
