如何通过Nginx Upstream-Check机制实现后端故障节点自动安全下线？

本文共计949个文字，预计阅读时间需要4分钟。

Nginx官方版本默认不包含`upstream_check_module`，直接写入`check`指令会报错，错误信息为unknown directive。

验证是否就绪：运行 nginx -V 2>&1 | grep -o check，有输出才表示模块存在；或者尝试启动时看错误日志是否报 unknown directive。

• 线上环境别依赖包管理器“猜”模块，nginx -V 和 nginx -t 是唯二可信依据
• OpenResty 用户需确认未禁用该模块（部分精简版会裁掉）
• Docker 场景下，基础镜像如 nginx:alpine 绝对不含此模块，必须自建镜像

check 指令必须紧贴 upstream 块内，且不能与 proxy_pass 混用在 server 块里

check 是 upstream 上下文指令，写在 server 或 location 里会直接语法错误。常见误写是把健康检查逻辑当成 location 策略来配，结果 Nginx 启动失败。

正确结构示例：

upstream backend { server 10.0.1.10:8080; server 10.0.1.11:8080; check interval=3 rise=2 fall=5 timeout=1 type=http; check_http_send "HEAD /health HTTP/1.0\r\n\r\n"; check_http_expect_alive http_2xx http_3xx; }

• interval 太小（如 1）易引发后端探测风暴，尤其当节点数 > 10 时
• rise 和 fall 不建议设为 1 —— 单次超时可能是网络抖动，非真实宕机
• type=http 要求后端必须响应 HTTP，TCP 类型（type=tcp）不发任何数据，只建连，适合无健康接口的旧服务

check_http_expect_alive 控制“什么算活”，但不会自动触发重试或降级路由

这个指令只影响 Nginx 内部节点状态标记（upstream 中显示 up/down），**不改变请求转发行为**。即使某个节点被标为 down，Nginx 默认仍可能按权重或轮询继续打过去，直到连接真正失败才切走 —— 这中间有窗口期。

要真正规避故障节点，必须配合：proxy_next_upstream error timeout http_500 http_502 http_503 http_504;，并确保 proxy_next_upstream_tries 和 proxy_next_upstream_timeout 设置合理。

• 仅靠 check 无法实现“零请求打到坏节点”，它只是状态感知层
• proxy_next_upstream 中若漏掉 error，连接拒绝（如后端进程崩溃但端口还监听）不会触发重试
• HTTP 检查返回 503 但没写进 check_http_expect_alive，该节点会被持续标记为 down，但实际请求仍可能因 proxy_next_upstream 未覆盖而失败

状态页 /status 接口暴露风险与权限控制必须手工补全

upstream_check_module 提供 /status 页面查看节点状态，但它是无鉴权、无限速的纯文本接口。一旦暴露在公网，等于直接公开后端拓扑和实时健康状况。

必须手动加访问控制：

location /status { check_status; allow 127.0.0.1; allow 10.0.0.0/8; deny all; }

• 别用 auth_basic 临时应付——基础认证明文传输，且状态页本身不防刷
• 如果用 OpenResty，可结合 access_by_lua_block 做 IP+Token 双校验，但复杂度陡增
• K8s Ingress 场景下，/status 映射到 Service 时务必加 NetworkPolicy 限制源 CIDR

节点自动下线这件事，核心不在“怎么标 down”，而在“标 down 之后请求是否真的绕开了”。模块只是眼睛，proxy_next_upstream 才是腿；眼睛看得准，腿不跟上，照样踩坑。