nginx官方不支持upstream check健康检查，需手动编译第三方模块nginx_upstream_check_module；启用后在upstream块中配置check指令及参数，并通过location /status配合check_status查看状态。
Upstream-Check 模块不是 Nginx 官方内置功能
直接在默认编译的 Nginx 中使用 check、check_http_send 等指令会报错：unknown directive "check"。这是因为 nginx_upstream_check_module 是第三方模块，需在编译 Nginx 时显式添加。如果你用的是 apt/yum 安装的包（如 Ubuntu 的 nginx-full 或 CentOS 的 nginx），大概率不含该模块——此时 reload 配置一定会失败。
验证方式很简单：
nginx -V 2>&1 | grep -o 'upstream_check'
没输出就说明没启用。临时补救只有两个选择：自己编译带模块的 Nginx，或改用官方健康检查（health_check 指令，仅限 Plus 版本）或基于 proxy_next_upstream 的简易探测（无主动探活能力）。
配置 Upstream-Check 时必须关闭 keepalive 冲突
常见错误是把 keepalive 和 check 放在同一 upstream 块里，例如：
upstream backend {
server 10.0.1.10:8080;
check interval=3 rise=2 fall=3 timeout=1;
keepalive 32;
}
这会导致 Nginx 启动失败，报错：keepalive cannot be used with health check。原因是 upstream_check_module 自己维护连接池，与官方 keepalive 机制不兼容。
正确做法是：
- 移除 upstream 块内的
keepalive指令 - 若需长连接，在 location 块中用
proxy_http_version 1.1+proxy_set_header Connection ""透传给后端 - 对上游连接复用依赖
check自带的连接管理（它会在探活时复用底层 socket）
平滑下线依赖 check 的状态同步与 proxy_next_upstream 配合
upstream_check_module 本身只负责探测并标记节点为 down，但 Nginx 默认不会自动跳过已 down 的节点——除非你明确告诉它“哪些失败要重试”。否则，请求仍可能打到刚被标记为 down、但尚未从负载均衡列表中剔除的节点上（尤其在高并发下）。
关键配置组合如下：
upstream backend {
server 10.0.1.10:8080 max_fails=0 fail_timeout=0;
server 10.0.1.11:8080 max_fails=0 fail_timeout=0;
check interval=3 rise=2 fall=3 timeout=1 type=http;
check_http_send "HEAD /actuator/health HTTP/1.1\r\nHost: localhost\r\n\r\n";
check_http_expect_alive http_2xx http_3xx;
}
server {
location / {
proxy_pass http://backend;
proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
proxy_next_upstream_tries 3;
proxy_next_upstream_timeout 5s;
}
}
注意点：
-
max_fails=0必须设为 0，否则 Nginx 会用自己的被动健康检查逻辑覆盖check的结果 -
check_http_send要匹配后端真实健康接口路径和协议头（Spring Boot 默认是/actuator/health，且需支持 HEAD） -
proxy_next_upstream必须包含error和timeout，才能在节点被check标记为 down 后，首次请求失败时触发重试
如何确认节点真的“平滑”下线了
光看 check 日志（如 upstream_check_status 页面）显示某节点为 down 不够——得验证流量是否彻底绕过它。最直接的方式是：
- 在目标后端节点停服务前，用
curl -v http://your-nginx/多次请求，记录响应头中的X-Upstream-Addr（可配合proxy_set_header X-Upstream-Addr $upstream_addr;输出） - 手动停掉该节点（比如
kill -15Spring Boot 进程） - 等待 3–6 秒（即
interval × fall），再快速发 10+ 请求，检查返回的X-Upstream-Addr是否完全不包含该节点 IP
如果仍有请求打过去，大概率是 proxy_next_upstream 没生效，或者客户端（如浏览器）因 HTTP/1.1 keepalive 复用了旧连接，误以为还在通信——这时需要加 proxy_force_ranges off 或更激进地设 proxy_buffering off 来暴露问题。真正平滑的下线，是业务无感知的，而这个“无感知”的边界，往往卡在连接复用和重试策略的缝隙里。
