nginx-healthcheck-module

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

本项目由 Akvicor 维护，修改自
yaoweibin/nginx_upstream_check_module。
当前版本保留主动健康检查模型，适配新版 Nginx upstream 内部结构，并聚焦于
http与streamupstream 的 TCP/UDP 检查。

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

功能

• 支持 Nginx 1.26+，仓库内提供对应 upstream 补丁。
• 支持主动type=tcp和type=udp健康检查。
• 支持httpupstream 和streamupstream。
• 可在 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