Nginx 上游健康检查插件 nginx-healthcheck-module

nginx-healthcheck-module

• 博客链接
• GitHub链接

用于 Nginx 1.26+ 的主动 upstream 健康检查模块。

本项目由 Akvicor 维护，修改自
yaoweibin/nginx_upstream_check_module。

当前版本保留主动健康检查模型，适配新版 Nginx upstream 内部结构，并聚焦于
http 与 stream upstream 的 TCP/UDP 检查。

因原项目无法适配新版本Nginx, 会导致检测异常，TIME_WAIT数量激增等各种问题， 因此这个版本中剔除了tcp/udp检查外的其他上游检查功能，增加了延迟统计，增加了TCP复用。

功能

• 支持 Nginx 1.26+，仓库内提供对应 upstream 补丁。
• 支持主动 type=tcp 和 type=udp 健康检查。
• 支持 http upstream 和 stream upstream。
• 可在 Nginx upstream 负载均衡过程中跳过不健康后端。
• 状态接口支持 html、csv、json、prometheus 输出。
• 状态输出中包含检查延迟统计：最后一次、平均、最小、最大延迟，单位毫秒。
• 支持 TCP 健康检查连接复用：reuse=on。

原项目中的 HTTP、FastCGI、MySQL、AJP、SSL hello 等七层检查，在当前维护版本中不再支持。

兼容性

• 目标 Nginx 版本：1.26+。
• 模块必须通过 --add-module 静态编译。
• 暂不支持动态模块加载。
• stream 健康检查要求 Nginx 编译时启用 --with-stream。

仓库内补丁会为 Nginx 内置 HTTP 和 Stream upstream 负载均衡器添加主动健康检查过滤，

包括 round robin、hash、consistent hash、适用场景下的 ip_hash，以及 least_conn。

安装

git clone https://github.com/nginx/nginx.git
git clone https://github.com/Akvicor/nginx-healthcheck-module.git

cd nginx
git checkout release-1.26.3
git apply ../nginx-healthcheck-module/nginx_healthcheck_for_nginx_1.26+.patch

./auto/configure --with-stream --add-module=../nginx-healthcheck-module
make
make install

请保留你当前 Nginx 构建所需的其他 configure 参数。如果需要 stream {} 健康检查，

需要保留 --with-stream。

已编译好的debian源

先导入GPG密钥，用于验证包

curl -fsSL https://cdn.ksyaki.com/debian/nginx-team/public-key.asc \
  | gpg --dearmor --batch --yes -o /usr/share/keyrings/akvicor.gpg

Debian 13

tee /etc/apt/preferences.d/99-akvicor-nginx.pref >/dev/null <<'EOF'
Package: nginx nginx-* libnginx-mod-*
Pin: origin cdn.ksyaki.com
Pin-Priority: 1001
EOF

echo "deb [signed-by=/usr/share/keyrings/akvicor.gpg] https://cdn.ksyaki.com/debian/nginx-team trixie main" \
  | tee /etc/apt/sources.list.d/akvicor-nginx.list

apt update
apt install nginx

Debian 12

tee /etc/apt/preferences.d/99-akvicor-nginx.pref >/dev/null <<'EOF'
Package: nginx nginx-* libnginx-mod-*
Pin: origin cdn.ksyaki.com
Pin-Priority: 1001
EOF

echo "deb [signed-by=/usr/share/keyrings/akvicor.gpg] https://cdn.ksyaki.com/debian/nginx-team bookworm main" \
  | tee /etc/apt/sources.list.d/akvicor-nginx.list

apt update
apt install nginx