lua-resty-checkups
使用纯 Lua 管理 Nginx 上游服务器
$ opm get upyun/lua-resty-checkups名称
lua-resty-checkups - 使用纯 ngx_lua 管理 Nginx 上游服务器
[!构建状态](https://travis-ci.org/upyun/lua-resty-checkups)
状态
在大多数情况下可能已准备好投入生产，但尚未在实际环境中得到充分验证。请查看问题列表，如果您有任何问题，请告诉我。
特性
定期向上游服务器发送心跳
主动和被动健康检查
动态更新上游服务器
使用加权轮询或一致性哈希进行负载均衡
与 Nginx 上游块同步
按层级或键尝试集群
兼容性
ngx_http_lua_module: v0.9.20 或更高版本。
概要
-- config.lua
_M = {}
_M.global = {
checkup_timer_interval = 15,
checkup_shd_sync_enable = true,
shd_config_timer_interval = 1,
}
_M.ups1 = {
cluster = {
{
servers = {
{ host = "127.0.0.1", port = 4444, weight=10, max_fails=3, fail_timeout=10 },
}
},
},
}
return _M
-- nginx.conf
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict state 10m;
lua_shared_dict mutex 1m;
lua_shared_dict locks 1m;
lua_shared_dict config 10m;
server {
listen 12350;
return 200 12350;
}
server {
listen 12351;
return 200 12351;
}
init_by_lua_block {
local config = require "config"
local checkups = require "resty.checkups.api"
checkups.init(config)
}
init_worker_by_lua_block {
local config = require "config"
local checkups = require "resty.checkups.api"
checkups.prepare_checker(config)
checkups.create_checker()
}
server {
location = /12350 {
proxy_pass http://127.0.0.1:12350/;
}
location = /12351 {
proxy_pass http://127.0.0.1:12351/;
}
location = /t {
content_by_lua_block {
local checkups = require "resty.checkups.api"
local callback = function(host, port)
local res = ngx.location.capture("/" .. port)
ngx.say(res.body)
return 1
end
local ok, err
-- connect to a dead server, no upstream available
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
-- add server to ups1
ok, err = checkups.update_upstream("ups1", {
{
servers = {
{ host = "127.0.0.1", port = 12350, weight=10, max_fails=3, fail_timeout=10 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
-- add server to new upstream
ok, err = checkups.update_upstream("ups2", {
{
servers = {
{ host="127.0.0.1", port=12351 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
-- add server to ups2, reset rr state
ok, err = checkups.update_upstream("ups2", {
{
servers = {
{ host = "127.0.0.1", port = 12350, weight=10, max_fails=3, fail_timeout=10 },
{ host = "127.0.0.1", port = 12351, weight=10, max_fails=3, fail_timeout=10 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
}
}
}上面定义的 /t 位置的典型输出是
no servers available
12350
12350
12351
12350
12351配置
Lua 配置
checkups 的配置文件是一个 Lua 模块，由两部分组成：全局部分和集群部分。
下面显示了 checkups 的一个示例配置文件：
-- config.lua
-- Here is the global part
_M = {}
_M.global = {
checkup_timer_interval = 15,
checkup_timer_overtime = 60,
default_heartbeat_enable = true,
checkup_shd_sync_enable = true,
shd_config_timer_interval = 1,
}
-- The rests parts are cluster configurations
_M.redis = {
enable = true,
typ = "redis",
timeout = 2,
read_timeout = 15,
send_timeout = 15,
protected = true,
cluster = {
{ -- level 1
try = 2,
servers = {
{ host = "192.168.0.1", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
{ host = "192.168.0.2", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
}
},
{ -- level 2
servers = {
{ host = "192.168.0.3", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
}
},
},
}
_M.api = {
enable = false,
typ = "http",
http_opts = {
query = "GET /status HTTP/1.1\r\nHost: localhost\r\n\r\n",
statuses = {
["500"] = false,
["502"] = false,
["503"] = false,
["504"] = false,
},
},
mode = "hash",
cluster = {
dc1 = {
servers = {
{ host = "192.168.1.1", port = 1234, weight=10, max_fails=3, fail_timeout=10 },
}
},
dc2 = {
servers = {
{ host = "192.168.1.2", port = 1234, weight=10, max_fails=3, fail_timeout=10 },
}
}
}
}
_M.ups_from_nginx = {
timeout = 2,
cluster = {
{ -- level 1
upstream = "api.com",
},
{ -- level 2
upstream = "api.com",
upstream_only_backup = true,
},
},
}
return _M全局配置
checkup_timer_interval：向后端服务器发送心跳的间隔。默认为5。checkup_timer_overtime：checkups 超时并过期定时器键的间隔。在大多数情况下，您无需更改此值。默认为60。default_heartbeat_enable：checkups 是否默认向服务器发送心跳。默认为true。checkup_shd_sync_enable：为每个 worker 创建上游同步器。如果设置为false，则动态上游将无法正常工作。默认为true。shd_config_timer_interval：从共享内存同步上游列表的间隔。默认为checkup_timer_interval。ups_status_sync_enable：如果设置为true，则 checkups 将从 checkups 同步上游状态到 Nginx 上游块。默认为false。ups_status_timer_interval：从 checkups 同步上游状态到 Nginx 上游块的间隔。
集群配置
skey：_M.xxxxx。xxxxx是此集群的skey（服务键）。enable：启用或禁用到服务器的心跳。默认为true。typ：集群类型，必须是general、redis、mysql、http之一。默认为general。general：通过 TCPsock:connect发送心跳。redis：通过 redisPING发送心跳。需要 lua-resty-redis 模块。mysql：通过 mysqldb:connect发送心跳。需要 lua-resty-mysql 模块。http：通过 HTTP 请求发送心跳。您可以在http_opts中设置自定义的 HTTP 请求和响应代码。
timeout：连接到上游服务器的超时时间。默认为5。read_timeout：读取上游服务器数据的超时时间（在心跳过程中不使用）。默认为timeout。send_timeout：写入上游服务器数据的超时时间（在心跳过程中不使用）。默认为timeout。http_opts：HTTP 心跳配置。仅在typ="http"时有效。query：心跳的 HTTP 请求。statuses：如果服务器返回的代码设置为false，则认为服务器已发生故障。
mode：负载均衡模式。可以设置为hash、url_hash或ip_hash。checkups 将根据hash_key、ngx.var.uri或ngx.var.remote_addr对服务器进行负载均衡。默认为wrr。protected：如果设置为true并且集群中的所有服务器都已发生故障，则 checkups 不会将最后一个故障服务器标记为不可用（err），而是将其标记为unstable（在下次尝试时仍然可用）。默认为true。cluster：您可以根据集群优先级配置多个层级，在每个层级中，您可以配置一个servers集群。只有当先前层级中的所有服务器都被认为不可用时，checkups 才会尝试下一层级。您可以通过键配置 checkups 尝试集群，而不是按层级尝试（参见上面的
api集群）。请记住，您还应该将额外的参数（如opts.cluster_key={"dc1", "dc2"}或opts.cluster_key={3, 1, 2}）传递给 checkups.read_ok，以使 checkups 按dc1、dc2或level 3、level 1、level 2的顺序进行尝试。如果您没有将opts.cluster_key传递给 checkups.ready_ok，则 checkups 仍将按层级尝试集群。对于上面的api集群，checkups 最终将返回no servers available。try：重试次数。默认为服务器数量。try_timeout：限制请求响应的时间，类似于 nginxproxy_next_upstream_timeout。servers：servers的配置如下所示：weight：设置服务器的权重。默认为1。max_fails：设置在fail_timeout参数设置的持续时间内与服务器通信失败的尝试次数。默认情况下，失败尝试次数设置为0，这将禁用尝试计数。如果typ="http"，则通过http_opts.statuses定义什么被视为失败尝试，或者通过 checkups.ready_ok 返回nil/false。此选项仅在轮询中可用。fail_timeout：设置在考虑服务器不可用之前与服务器通信失败的尝试次数应发生的持续时间，以及服务器将被视为不可用的时间段。默认情况下，参数设置为10秒。此选项仅在轮询中可用。
名称 ====
lua-resty-checkups - 使用纯 ngx_lua 管理 Nginx 上游服务器
[](https://travis-ci.org/upyun/lua-resty-checkups)
目录 =================
* [名称](#name) * [状态](#status) * [特性](#features) * [概要](#synopsis) * [配置](#configuration) * [Lua 配置](#lua-configuration) * [全局配置](#global-configuration) * [集群配置](#cluster-configuration) * [Nginx 配置](#nginx-configuration) * [API](#api) * [init](#init) * [prepare_checker](#prepare_checker) * [create_checker](#create_checker) * [ready_ok](#ready_ok) * [select_peer](#select_peer) * [get_status](#get_status) * [get_ups_timeout](#get_ups_timeout) * [feedback_status](#feedback_status) * [update_upstream](#update_upstream) * [delete_upstream](#delete_upstream) * [版权和许可](#copyright-and-license)
状态 ======
在大多数情况下可能已准备好投入生产，但尚未在实际环境中得到充分验证。请查看问题列表，如果您有任何问题，请告诉我。
特性 ========
* 定期向上游服务器发送心跳 * 主动和被动健康检查 * 动态更新上游服务器 * 使用加权轮询或一致性哈希进行负载均衡 * 与 Nginx 上游块同步 * 按层级或键尝试集群
兼容性 =============
* [ngx_http_lua_module](https://github.com/openresty/lua-nginx-module): v0.9.20 或更高版本。
概要 ========
```lua -- config.lua
_M = {}
_M.global = {
checkup_timer_interval = 15,
checkup_shd_sync_enable = true,
shd_config_timer_interval = 1,
}
_M.ups1 = {
cluster = {
{
servers = {
{ host = "127.0.0.1", port = 4444, weight=10, max_fails=3, fail_timeout=10 },
}
},
},
}
return _M
``````lua -- nginx.conf
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict state 10m;
lua_shared_dict mutex 1m;
lua_shared_dict locks 1m;
lua_shared_dict config 10m;
server {
listen 12350;
return 200 12350;
}
server {
listen 12351;
return 200 12351;
}
init_by_lua_block {
local config = require "config"
local checkups = require "resty.checkups.api"
checkups.init(config)
}
init_worker_by_lua_block {
local config = require "config"
local checkups = require "resty.checkups.api"
checkups.prepare_checker(config)
checkups.create_checker()
}
server {
location = /12350 {
proxy_pass http://127.0.0.1:12350/;
}
location = /12351 {
proxy_pass http://127.0.0.1:12351/;
}
location = /t {
content_by_lua_block {
local checkups = require "resty.checkups.api"
local callback = function(host, port)
local res = ngx.location.capture("/" .. port)
ngx.say(res.body)
return 1
end
local ok, err
-- connect to a dead server, no upstream available
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
-- add server to ups1
ok, err = checkups.update_upstream("ups1", {
{
servers = {
{ host = "127.0.0.1", port = 12350, weight=10, max_fails=3, fail_timeout=10 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
ok, err = checkups.ready_ok("ups1", callback)
if err then ngx.say(err) end
-- add server to new upstream
ok, err = checkups.update_upstream("ups2", {
{
servers = {
{ host="127.0.0.1", port=12351 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
-- add server to ups2, reset rr state
ok, err = checkups.update_upstream("ups2", {
{
servers = {
{ host = "127.0.0.1", port = 12350, weight=10, max_fails=3, fail_timeout=10 },
{ host = "127.0.0.1", port = 12351, weight=10, max_fails=3, fail_timeout=10 },
}
},
})
if err then ngx.say(err) end
ngx.sleep(1)
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
ok, err = checkups.ready_ok("ups2", callback)
if err then ngx.say(err) end
}
}
}
```上面定义的 `/t` 位置的典型输出是
no servers available
12350
12350
12351
12350
12351配置 =============
Lua 配置 -----------------
checkups 的配置文件是一个 Lua 模块，由两部分组成：全局部分和集群部分。
下面显示了 checkups 的一个示例配置文件：
```lua -- config.lua
-- Here is the global part
_M = {}
_M.global = {
checkup_timer_interval = 15,
checkup_timer_overtime = 60,
default_heartbeat_enable = true,
checkup_shd_sync_enable = true,
shd_config_timer_interval = 1,
}
-- The rests parts are cluster configurations
_M.redis = {
enable = true,
typ = "redis",
timeout = 2,
read_timeout = 15,
send_timeout = 15,
protected = true,
cluster = {
{ -- level 1
try = 2,
servers = {
{ host = "192.168.0.1", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
{ host = "192.168.0.2", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
}
},
{ -- level 2
servers = {
{ host = "192.168.0.3", port = 6379, weight=10, max_fails=3, fail_timeout=10 },
}
},
},
}
_M.api = {
enable = false,
typ = "http",
http_opts = {
query = "GET /status HTTP/1.1\r\nHost: localhost\r\n\r\n",
statuses = {
["500"] = false,
["502"] = false,
["503"] = false,
["504"] = false,
},
},
mode = "hash",
cluster = {
dc1 = {
servers = {
{ host = "192.168.1.1", port = 1234, weight=10, max_fails=3, fail_timeout=10 },
}
},
dc2 = {
servers = {
{ host = "192.168.1.2", port = 1234, weight=10, max_fails=3, fail_timeout=10 },
}
}
}
}
_M.ups_from_nginx = {
timeout = 2,
cluster = {
{ -- level 1
upstream = "api.com",
},
{ -- level 2
upstream = "api.com",
upstream_only_backup = true,
},
},
}
return _M
```全局配置 ---------------------
* `checkup_timer_interval`：向后端服务器发送心跳的间隔。默认为 `5`。 * `checkup_timer_overtime`：checkups 超时并过期定时器键的间隔。在大多数情况下，您无需更改此值。默认为 `60`。 * `default_heartbeat_enable`：checkups 是否默认向服务器发送心跳。默认为 `true`。 * `checkup_shd_sync_enable`：为每个 worker 创建上游同步器。如果设置为 `false`，则动态上游将无法正常工作。默认为 `true`。 * `shd_config_timer_interval`：从共享内存同步上游列表的间隔。默认为 `checkup_timer_interval`。 * `ups_status_sync_enable`：如果设置为 `true`，则 checkups 将从 checkups 同步上游状态到 Nginx 上游块。默认为 `false`。 * `ups_status_timer_interval`：从 checkups 同步上游状态到 Nginx 上游块的间隔。
集群配置 ----------------------
* `skey`：`_M.xxxxx`。`xxxxx` 是此集群的 `skey`（服务键）。 * `enable`：启用或禁用到服务器的心跳。默认为 `true`。 * `typ`：集群类型，必须是 `general`、`redis`、`mysql`、`http` 之一。默认为 `general`。 * `general`：通过 TCP `sock:connect` 发送心跳。 * `redis`：通过 redis `PING` 发送心跳。[lua-resty-redis](https://github.com/openresty/lua-resty-redis) 模块是必需的。 * `mysql`：通过 mysql `db:connect` 发送心跳。[lua-resty-mysql](https://github.com/openresty/lua-resty-mysql) 模块是必需的。 * `http`：通过 HTTP 请求发送心跳。您可以在 `http_opts` 中设置自定义的 HTTP 请求和响应代码。 * `timeout`：连接到上游服务器的超时时间。默认为 `5`。 * `read_timeout`：读取上游服务器数据的超时时间（在心跳过程中不使用）。默认为 `timeout`。 * `send_timeout`：写入上游服务器数据的超时时间（在心跳过程中不使用）。默认为 `timeout`。 * `http_opts`：HTTP 心跳配置。仅在 `typ="http"` 时有效。 * `query`：心跳的 HTTP 请求。 * `statuses`：如果服务器返回的代码设置为 `false`，则认为服务器已发生故障。
* `mode`：负载均衡模式。可以设置为 `hash`、`url_hash` 或 `ip_hash`。checkups 将根据 `hash_key`、`ngx.var.uri` 或 `ngx.var.remote_addr` 对服务器进行负载均衡。默认为 `wrr`。 * `protected`：如果设置为 `true` 并且集群中的所有服务器都已发生故障，则 checkups 不会将最后一个故障服务器标记为不可用（`err`），而是将其标记为 `unstable`（在下次尝试时仍然可用）。默认为 `true`。 * `cluster`：您可以根据集群优先级配置多个层级，在每个层级中，您可以配置一个 `servers` 集群。只有当先前层级中的所有服务器都被认为不可用时，checkups 才会尝试下一层级。
Instead of trying clusters by levels, you can configure checkups trying clusters by key(see `api` cluster above). Remember you should also pass extra argument like `opts.cluster_key={"dc1", "dc2"}` or `opts.cluster_key={3, 1, 2}` to [checkups.read_ok](#ready_ok) to make checkups trying on the order of `dc1`, `dc2` or `level 3`, `level 1`, `level 2`. If you haven't passed `opts.cluster_key` to [checkups.ready_ok](#ready_ok), checkups will still try clusters by levels. As for the above `api` cluster, checkups will eventually return `no servers available`.
* `try`: Retry count. Default is the number of servers.
* `try_timeout`: Limits the time during which a request can be responsed, likewise nginx `proxy_next_upstream_timeout`.
* `servers`: Configuration for `servers` are listed as follows,
* `weight`: Sets the weight of the server. Default is `1`.
* `max_fails`: Sets the number of unsuccessful attempts to communicate with the server that should happen in the duration set by the `fail_timeout` parameter. By default, the number of unsuccessful attempts is set to `0`, which disables the accounting of attempts. What is considered an unsuccessful attempt is defined by `http_opts.statuses` if `typ="http"` or a `nil`/`false` returned by [checkups.ready_ok](#ready_ok). This options is only available in round-robin.
* `fail_timeout`: Sets the time during which the specified number of unsuccessful attempts to communicate with the server should happen to consider the server unavailable and the period of time the server will be considered unavailable. By default, the parameter is set to `10` seconds. This options is only available in round-robin.
* `upstream`: Name of Nginx upstream blocks. Checkups will extract servers from Nginx conf's upstream blocks in [prepare_checker](#prepare_checker). [lua-upstream-nginx-module](https://github.com/openresty/lua-upstream-nginx-module) module is required.
* `upstream_only_backup`: If set to `true`, checkups will only extract backup servers from Nginx upstream blocks.Nginx 配置 -------------------
将 lua 配置文件和 checkups 的路径添加到 `lua_package_path`，并创建 checkups 使用的 lua 共享字典。您应该将这些行放入 Nginx 配置文件的 `http` 块中。
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict state 10m;
lua_shared_dict mutex 1m;
lua_shared_dict locks 1m;
lua_shared_dict config 10m;如果您使用的是 stream 子系统，则应将这些行放入 Nginx 配置文件的 `stream` 块中。
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict stream_state 10m;
lua_shared_dict stream_mutex 1m;
lua_shared_dict stream_locks 1m;
lua_shared_dict stream_config 10m;API ===
init --------------- **语法:** *init(config)*
**阶段:** *init_by_lua*
将上游服务器从 `config.lua` 复制到 shdict，从 Nginx 上游块中提取服务器，并进行一些基本的初始化。
prepare_checker ---------------
**语法:** *prepare_checker(config)*
**阶段:** *init_worker_by_lua*
将配置从 `config.lua` 复制到 worker checkups，从 Nginx 上游块中提取服务器，并进行一些基本的初始化。
create_checker --------------
**语法:** *create_checker()*
**阶段:** *init_worker_by_lua*
创建心跳定时器和上游同步定时器。在所有 worker 中只会创建一个心跳定时器。强烈建议在 `init_worker` 阶段调用此方法。
ready_ok --------
**语法:** *res, err = ready_ok(skey, callback, opts?)*
**阶段:** *rewrite_by_lua*、*access_by_lua*、*content_by_lua*、*ngx.timer.*
从集群 `skey` 中选择一个可用的 `peer` 并调用 `callback(peer.host, peer.port, opts)`。
`opts` 表接受以下字段：
* `cluster_key`：按 `cluster_key` 尝试集群。checkups 将按 `cluster_key` 的顺序尝试集群。`clusters_key` 可以是集群的名称或集群的层级。集群例如：`{"cluster_name_A", "name_B", "name_C"}`。层级例如：`{3, 2, 1}`。 * `hash_key`：在 `hash` 负载均衡模式中使用的键。如果未设置，则将使用 `ngx.var.uri`。 * `try`：重试次数不超过 `try` 次。 * `try_timeout`：限制请求响应的时间，类似于 nginx `proxy_next_upstream_timeout`。
成功时返回 `callback` 返回的值，否则返回 `nil` 和一个描述错误的字符串。
如果 `callback` 返回 `nil` 或 `false`，则 checkups 将将其视为失败的尝试，并将使用另一个 peer 重试 `callback`。因此，**请务必记住在成功回调后不要返回 `nil` 或 `false`**。
select_peer -----------
**语法:** *peer, err = select_peer(skey)*
**上下文:** *rewrite_by_lua*, *access_by_lua*, *content_by_lua*, *balancer_by_lua*
从集群 `skey` 中选择一个可用的节点。
返回一个包含可用节点 `host` 和 `port` 的表。
如果发生错误，则返回 nil 和一个描述错误的字符串。
get_status ----------
**语法:** *status = get_status()*
**阶段:** *rewrite_by_lua*、*access_by_lua*、*content_by_lua*、*ngx.timer.*
以 `json` 格式返回检查状态。
get_ups_timeout ---------------
**语法:** *connect_timeout, send_timeout, read_timeout = get_ups_timeout(skey)*
**阶段:** *rewrite_by_lua*、*access_by_lua*、*content_by_lua*、*ngx.timer.*
返回集群 `skey` 的超时时间。
feedback_status ---------------
**语法:** *ok, err = feedback_status(skey, host, port, failed)*
**上下文:** *rewrite_by_lua*, *access_by_lua*, *content_by_lua*, *ngx.timer.*, *balancer_by_lua.*
将集群 `skey` 中的服务器 `host:port` 标记为失败(`true`) 或可用(`false`)。
成功返回 `1`，否则返回 `nil` 和一个描述错误的字符串。
update_upstream ---------------
**语法:** *ok, err = update_upstream(skey, upstream)*
**阶段:** *rewrite_by_lua*、*access_by_lua*、*content_by_lua*、*ngx.timer.*
更新集群 `skey`。`upstream` 的格式与 `config.lua` 中的 `cluster` 相同。
成功返回 `true`，否则返回 `false` 和一个描述错误的字符串。
delete_upstream ---------------
**语法:** *ok, err = delete_upstream(skey)*
**阶段:** *rewrite_by_lua*、*access_by_lua*、*content_by_lua*、*ngx.timer.*
从上游列表中删除集群 `skey`。
成功返回 `true`，否则返回 `false` 和一个描述错误的字符串。
版权和许可 =====================
该软件包本身采用 2-clause BSD 许可证授权。
版权所有 (c) 2016，UPYUN(又拍云) Inc。
本模块根据 BSD 许可证的条款授权。
在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否修改
* 源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。* 二进制形式的再分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表和以下免责声明。
本软件由版权持有人和贡献者“按原样”提供，并且不提供任何明示或暗示的保证，包括但不限于适销性和特定用途适用性的暗示保证。在任何情况下，版权持有人或贡献者均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）负责，无论这些损害是如何引起的以及基于何种责任理论，无论是合同、严格责任还是侵权行为（包括疏忽或其他），即使已被告知可能发生此类损害。
另请参阅 ======== * [lua-nginx-module](https://github.com/openresty/lua-nginx-module) upstream：Nginx 上游块的名称。检查程序将在 prepare_checker 中从 Nginx 配置文件的上游块中提取服务器。需要 lua-upstream-nginx-module 模块。upstream_only_backup：如果设置为 true，则检查程序将仅从 Nginx 上游块中提取备份服务器。
Nginx 配置
将 lua 配置文件和检查程序的路径添加到 lua_package_path 中，并创建检查程序使用的 lua 共享字典。您应该将这些行放在 Nginx 配置文件的 http 块中。
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict state 10m;
lua_shared_dict mutex 1m;
lua_shared_dict locks 1m;
lua_shared_dict config 10m;如果您使用的是流子系统，则应将这些行放在 Nginx 配置文件的 stream 块中。
lua_package_path "/path/to/lua-resty-checkups/lib/?.lua;/path/to/config.lua;;";
lua_shared_dict stream_state 10m;
lua_shared_dict stream_mutex 1m;
lua_shared_dict stream_locks 1m;
lua_shared_dict stream_config 10m;API
init
语法: init(config)
阶段: init_by_lua
将上游从 config.lua 复制到 shdict，从 Nginx 上游块中提取服务器并进行一些基本初始化。
prepare_checker
语法: prepare_checker(config)
阶段: init_worker_by_lua
将配置从 config.lua 复制到 worker 检查程序，从 Nginx 上游块中提取服务器并进行一些基本初始化。
create_checker
语法: create_checker()
阶段: init_worker_by_lua
创建心跳计时器和上游同步计时器。在所有 worker 中只会创建一个心跳计时器。强烈建议在 init_worker 阶段调用此方法。
ready_ok
语法: res, err = ready_ok(skey, callback, opts?)
阶段: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*
从集群 `skey` 中选择一个可用的 `peer` 并调用 callback(peer.host, peer.port, opts)。
opts 表接受以下字段：
cluster_key：按cluster_key尝试集群。检查程序将按cluster_key的顺序尝试集群。clusters_key可以是集群的名称或集群的级别。集群示例：{"cluster_name_A", "name_B", "name_C"}。级别示例：{3, 2, 1}。hash_key：在hash负载均衡模式中使用的键。如果未设置，则将使用ngx.var.uri。try：重试次数不超过try次。try_timeout：限制请求响应的时间，类似于 nginxproxy_next_upstream_timeout。
成功时返回 callback 返回的值，否则返回 nil 和一个描述错误的字符串。
如果 callback 返回 nil 或 false，检查程序将认为这是一个失败的尝试，并将使用另一个节点重试 callback。因此，**请务必记住，在成功回调后不要返回 nil 或 false。**
select_peer
语法: peer, err = select_peer(skey)
上下文: rewrite_by_lua*, access_by_lua*, content_by_lua*, balancer_by_lua
从集群 `skey` 中选择一个可用的节点。
返回一个包含可用节点 `host` 和 `port` 的表。
如果发生错误，则返回 nil 和一个描述错误的字符串。
get_status
语法: status = get_status()
阶段: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*
以 json 格式返回检查状态。
get_ups_timeout
语法: connect_timeout, send_timeout, read_timeout = get_ups_timeout(skey)
阶段: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*
返回集群 `skey` 的超时时间。
feedback_status
语法: ok, err = feedback_status(skey, host, port, failed)
上下文: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*, balancer_by_lua.*
将集群 `skey` 中的服务器 host:port 标记为失败(true) 或可用(false)。
成功返回 1，否则返回 nil 和一个描述错误的字符串。
update_upstream
语法: ok, err = update_upstream(skey, upstream)
阶段: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*
更新集群 `skey`。`upstream` 的格式与 `config.lua` 中的 `cluster` 相同。
成功返回 `true`，否则返回 `false` 和一个描述错误的字符串。
delete_upstream
语法: ok, err = delete_upstream(skey)
阶段: rewrite_by_lua*, access_by_lua*, content_by_lua*, ngx.timer.*
从上游列表中删除集群 `skey`。
成功返回 `true`，否则返回 `false` 和一个描述错误的字符串。
版权和许可
该软件包本身采用 2-clause BSD 许可证授权。
版权所有 (c) 2016，UPYUN(又拍云) Inc。
本模块根据 BSD 许可证的条款授权。
在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否修改
源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。
二进制形式的再分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表和以下免责声明。
本软件由版权持有人和贡献者“按原样”提供，并且不提供任何明示或暗示的保证，包括但不限于适销性和特定用途适用性的暗示保证。在任何情况下，版权持有人或贡献者均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）负责，无论这些损害是如何引起的以及基于何种责任理论，无论是合同、严格责任还是侵权行为（包括疏忽或其他），即使已被告知可能发生此类损害。
另请参阅
作者
huangnauh huanglibo2010@gmail.com
许可证
2bsd
版本
-
使用纯 Lua 管理 Nginx 上游 2019-02-01 03:01:35