healthcheck: 用于 nginx-module-lua 的健康检查库，以验证上游服务状态
安装
如果您尚未设置 RPM 仓库订阅，请 注册。然后您可以继续以下步骤。
CentOS/RHEL 7 或 Amazon Linux 2
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-healthcheck
CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-healthcheck
要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。
本文档描述了 lua-resty-healthcheck v3.1.2，于 2026 年 4 月 9 日发布。
一个用于 OpenResty 的健康检查库。
概述
http {
lua_shared_dict test_shm 8m;
lua_shared_dict my_worker_events 8m;
init_worker_by_lua_block {
local we = require "resty.worker.events"
local ok, err = we.configure({
shm = "my_worker_events",
interval = 0.1
})
if not ok then
ngx.log(ngx.ERR, "配置工作事件失败: ", err)
return
end
local healthcheck = require("resty.healthcheck")
local checker = healthcheck.new({
name = "testing",
shm_name = "test_shm",
checks = {
active = {
type = "https",
http_path = "/status",
healthy = {
interval = 2,
successes = 1,
},
unhealthy = {
interval = 1,
http_failures = 2,
}
},
}
})
local ok, err = checker:add_target("127.0.0.1", 8080, "example.com", false)
local handler = function(target, eventname, sourcename, pid)
ngx.log(ngx.DEBUG,"来自: ", sourcename .. " 的事件")
if eventname == checker.events.remove
-- 一个目标被移除
ngx.log(ngx.DEBUG,"目标已移除: ",
target.ip, ":", target.port, " ", target.hostname)
elseif eventname == checker.events.healthy
-- 目标状态已更改，或已添加
ngx.log(ngx.DEBUG,"目标已切换为健康: ",
target.ip, ":", target.port, " ", target.hostname)
elseif eventname == checker.events.unhealthy
-- 目标状态已更改，或已添加
ngx.log(ngx.DEBUG,"目标已切换为不健康: ",
target.ip, ":", target.port, " ", target.hostname)
else
-- 未知事件
end
end
}
}
描述
该库支持对任意主机执行主动和被动健康检查。
库的控制通过其编程 API 进行。其事件的消费通过 lua-resty-worker-events 库进行。
使用 checker:add_target(host, port) 添加目标。
状态变化（“健康”或“不健康”）通过工作事件广播。
主动检查在指定的定时器间隔下在后台执行。
对于被动健康检查，库通过其编程 API 接收显式通知，使用诸如 checker:report_http_status(host, port, status) 的函数。
有关完整 API，请参见 在线 LDoc 文档。
历史
版本严格基于 语义版本控制
发布新版本：
- 更新下面的变更日志（PR 应该合并并包括变更日志条目）
- 根据变更日志确定新的 SemVer 版本
- 创建新的 rockspec
- 使用
ldoc渲染文档（不要在 PR 中执行此操作） - 提交为 "release x.x.x"（不要包括 rockspec 修订版）
- 用 "x.x.x" 标记提交（不要包括 rockspec 修订版）
- 推送提交和标签
- 将 rock 上传到 luarocks:
luarocks upload rockspecs/[name] --api-key=abc
3.1.2 (2026年4月9日)
- 修复（主动检查）：使用 HTTP/1.1 进行健康检查探测，自动版本协商 #176
3.1.1 (2025年11月19日)
- 修复：将默认头更改为空表而不是数组，以消除弃用通知 #174
3.1.0 (2024年6月19日)
- 特性：移除 resty.events 的版本检查 #162
3.0.2 (2024年5月16日)
- 修复：避免创建多个定时器以运行相同的主动检查 #157
3.0.1 (2023年12月22日)
- 修复：修复启动多个健康检查器时的延迟清理逻辑 #146
3.0.0 (2023年10月12日)
2.0.0 (2020年9月22日)
注意：
此版本中的更改已被当前和未来的开发所丢弃。
以下是其变更日志，但请注意，除非在 3.y.z、1.6.3 或之前的版本中明确说明，否则这些更改可能不在 3.y.z 中。有关更多信息，请阅读：release 3.0.0 (#142) 和 chore(*): realign master branch to 3.0.0 release (#144)
- 破坏性：已移除对弃用的顶级字段
type的回退 （自0.5.0起弃用） #56- 破坏性：将
lua-resty-worker-events依赖项提升至2.0.0。这使得 本库中的许多 API 变为异步，因为工作事件post和post_local不再自动调用正在运行的工作线程上的poll，有关更多信息，请参见： https://github.com/Kong/lua-resty-worker-events#200-16-september-2020- 破坏性：tcp_failures 在 http(s) 检查中不再可以为 0（除非 http(s)_failures 也设置为 0） #55
- 特性：添加对 https_sni 的支持 #49
- 修复：通过使用尾调用正确记录行号 #29
- 修复：在不提供主机名时，使用 IP #48
- 修复：makefile；make install
- 特性：添加状态版本字段 #54
- 特性：为探测请求添加头 #54
- 修复：在探测期间重新加载时提前退出 #47
- 修复：防止由于异步行为导致目标列表为 nil #44
- 修复：用 resty-timer 替换定时器和节点范围锁，以防止间隔 跳过 #59
- 更改：在发布事件时添加额外的日志记录 #25
- 修复：在添加大量目标时，在 init/init_worker 期间不要耗尽定时器 #57
- 修复：不要在模块表上调用，而是使用方法进行锁定。也在 #57
1.6.3 (2023年9月6日)
1.6.2 (2022年11月17日)
- 修复：避免对标记为延迟移除的新目标引发工作事件，即内存中已存在的目标在重新添加时只需清除移除标志。 #122
1.6.1 (2022年7月25日)
- 修复：改进以确保正确保护共享资源以避免竞争条件，并清晰报告失败状态。 #112, #113, #114。
- 修复：减少检查未使用目标的频率，减少创建的锁的数量。 #116
- 修复接受任何 lua-resty-events
0.1.x版本。 #118
1.6.0 (2022年6月27日)
- 特性：除了 lua-resty-worker-events 支持外，添加对 lua-resty-events 模块的支持。通过此添加，lua-resty-healthcheck luarocks 包不再需要特定的事件共享模块，但您仍然需要提供 lua-resty-worker-events 或 lua-resty-events。 #105
- 更改：如果可用，lua-resty-healthcheck 现在使用
string.buffer，新的 LuaJIT 的序列化 API。如果不可用，lua-resty-healthcheck 将回退到 cjson。 #109
1.5.3 (2022年11月14日)
- 修复：避免对标记为延迟移除的新目标引发工作事件，即内存中已存在的目标在重新添加时只需清除移除标志。 #121
1.5.2 (2022年7月7日)
- 更好地处理
resty.lock失败模式，增加更多检查以确保在运行关键代码之前持有锁，并改善在尝试获取锁后是否应重试函数的决策。 #113 - 增加了对锁定函数失败的日志记录。 #114
- 删除目标的清理频率降低，减少短时间内创建的锁的数量。 #116
1.5.1 (2022年3月23日)
- 修复：在添加或移除目标时避免破坏主动健康检查。 #93
1.5.0 (2022年2月9日)
- 新选项
checks.active.headers支持一个或多个按头名称索引的值列表。 #87 - 引入 dealyed_clear() 函数，用于在时间间隔后移除地址。此函数可在地址被移除但在间隔到期之前可能再次添加时使用，以保持其健康状态。 #88
1.4.3 (2022年3月31日)
- 修复：避免在添加或移除目标时破坏主动健康检查。 #100
1.4.2 (2021年6月29日)
1.4.1 (2021年2月17日)
- 修复：确保单个工作线程将主动检查主机状态。 #67
1.4.0 (2021年1月7日)
- 使用单个定时器主动检查目标。这减少了健康检查器使用的定时器数量，因为它们以前每个目标使用两个定时器。 #62
1.3.0 (2020年6月17日)
- 为主动健康检查添加对 mTLS 的支持。此功能可以在创建新的健康检查对象时添加
ssl_cert和ssl_key字段，分别包含证书和密钥。 #41
1.2.0 (2020年2月13日)
- 添加
set_all_target_statuses_for_hostname，一次为给定主机名的所有条目设置目标。
1.1.2 (2019年12月19日)
- 修复：当
ngx.sleepAPI 不可用时（例如，在日志阶段），无法使用 lua-resty-lock 锁定，任何需要独占访问的函数都会失败。此修复添加了一个重试方法，启动一个新的轻量线程，该线程可以访问ngx.sleep，以锁定关键路径。 #37;
1.1.1 (2019年11月14日)
- 修复：当无法获得目标列表的独占访问时失败。此修复防止工作线程进入不一致状态。 #34;
1.1.0 (2019年9月30日)
- 添加对设置自定义
Host头以用于主动检查的支持。 - 修复：在 SSL 握手失败时记录错误 #28;
1.0.0 (2019年7月5日)
- 破坏性：与主机相关的所有 API 函数现在都需要
hostname参数。这样，在同一 IP 和端口组合上监听的不同主机名不会相互影响。 - 修复：修复报告主动 TCP 探测成功 #20; 修复问题 #19
0.6.1 (2019年4月4日)
0.6.0 (2018年9月26日)
- 引入
checks.active.https_verify_certificate字段。 默认值为true；将其设置为false将禁用 HTTPS 上的主动健康检查中的证书验证。
0.5.0 (2018年7月25日)
- 添加对
https的支持 -- 感谢 @gaetanfl 的 PR！ - 引入单独的
checks.active.type和checks.passive.type字段； 顶级type字段仍然作为回退支持，但现在已被弃用。
0.4.2 (2018年5月23日)
- 修复主动健康检查中的
Host头
0.4.1 (2018年5月21日)
- 修复健康检查计数器的内部管理
0.4.0 (2018年3月20日)
- 正确设置
http_statuses中的默认值 - 对
checks表进行类型和边界检查
0.3.0 (2017年12月18日)
- 通过将其计数器设置为 0 禁用单个检查
0.2.0 (2017年11月30日)
- 添加
set_target_status
0.1.0 (2017年11月27日) 初始发布
- 初始上传
GitHub
您可以在 nginx-module-healthcheck 的 GitHub 仓库 中找到此模块的其他配置提示和文档。