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.1，于 2025 年 11 月 19 日发布。
一个用于 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, "failed to configure worker events: ", 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,"Event from: ", sourcename)
if eventname == checker.events.remove
-- a target was removed
ngx.log(ngx.DEBUG,"Target removed: ",
target.ip, ":", target.port, " ", target.hostname)
elseif eventname == checker.events.healthy
-- target changed state, or was added
ngx.log(ngx.DEBUG,"Target switched to healthy: ",
target.ip, ":", target.port, " ", target.hostname)
elseif eventname == checker.events.unhealthy
-- target changed state, or was added
ngx.log(ngx.DEBUG,"Target switched to unhealthy: ",
target.ip, ":", target.port, " ", target.hostname)
else
-- unknown event
end
end
}
}
描述
此库支持对任意主机进行主动和被动健康检查。
库的控制通过其编程 API 进行。事件的消费通过 lua-resty-worker-events 库进行。
使用 checker:add_target(host, port) 添加目标。
状态变化（“健康”或“不健康”）通过工作事件广播。
主动检查在后台根据指定的定时器间隔执行。
对于被动健康检查，库通过其编程 API 接收显式通知，使用诸如 checker:report_http_status(host, port, status) 的函数。
有关完整 API，请参见 在线 LDoc 文档。
历史
版本控制严格基于 Semantic Versioning
发布新版本：
- 更新下面的变更日志（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.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- 破坏性更改：在 http(s) 检查中，tcp_failures 不能再为 0（除非 http(s)_failures 也设置为 0） #55
- 特性：添加对 https_sni 的支持 #49
- 修复：通过使用尾调用正确记录行号 #29
- 修复：在不提供主机名时，使用 IP #48
- 修复：makefile；make install
- 特性：添加状态版本字段 #54
- 特性：为探测请求添加头部 #54
- 修复：在探测期间重新加载时提前退出 #47
- 修复：防止由于异步行为导致目标列表为 nil #44
- 修复：用 resty-timer 替换定时器和节点范围锁，以防止间隔 跳过 #59
- 更改：在发布事件时添加额外的日志记录 #25
- 修复：在添加大量目标时，初始化/工作初始化期间不耗尽定时器 #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 仓库 中找到此模块的其他配置提示和文档。