$ opm get valdemaras-pipiras/lua-resty-upstream-healthcheck

名称

lua-resty-upstream-healthcheck - 用于 Nginx 上游服务器的健康检查器

状态

该库仍处于早期开发阶段，但已准备好投入生产。

概要

    http {
        lua_package_path "/path/to/lua-resty-upstream-healthcheck/lib/?.lua;;";
    
        # sample upstream block:
        upstream foo.com {
            server 127.0.0.1:12354;
            server 127.0.0.1:12355;
            server 127.0.0.1:12356 backup;
        }
    
        # the size depends on the number of servers in upstream {}:
        lua_shared_dict healthcheck 1m;
    
        lua_socket_log_errors off;
    
        init_worker_by_lua_block {
            local hc = require "resty.upstream.healthcheck"
    
            local ok, err = hc.spawn_checker{
                shm = "healthcheck",  -- defined by "lua_shared_dict"
                upstream = "foo.com", -- defined by "upstream"
                type = "http", -- support "http" and "https"
    
                http_req = "GET /status HTTP/1.0\r\nHost: foo.com\r\n\r\n",
                        -- raw HTTP request for checking
    
                port = nil,  -- the check port, it can be different than the original backend server port, default means the same as the original backend server
                interval = 2000,  -- run the check cycle every 2 sec
                timeout = 1000,   -- 1 sec is the timeout for network operations
                fall = 3,  -- # of successive failures before turning a peer down
                rise = 2,  -- # of successive successes before turning a peer up
                valid_statuses = {200, 302},  -- a list valid HTTP status code
                concurrency = 10,  -- concurrency level for test requests
                -- ssl_verify = true, -- https type only, verify ssl certificate or not, default true
                -- host = foo.com, -- https type only, host name in ssl handshake, default nil
            }
            if not ok then
                ngx.log(ngx.ERR, "failed to spawn health checker: ", err)
                return
            end
    
            -- Just call hc.spawn_checker() for more times here if you have
            -- more upstream groups to monitor. One call for one upstream group.
            -- They can all share the same shm zone without conflicts but they
            -- need a bigger shm zone for obvious reasons.
        }
    
        server {
            ...
    
            # status page for all the peers:
            location = /status {
                access_log off;
                allow 127.0.0.1;
                deny all;
    
                default_type text/plain;
                content_by_lua_block {
                    local hc = require "resty.upstream.healthcheck"
                    ngx.say("Nginx Worker PID: ", ngx.worker.pid())
                    ngx.print(hc.status_page())
                }
            }
    
        # status page for all the peers (prometheus format):
            location = /metrics {
                access_log off;
                default_type text/plain;
                content_by_lua_block {
                    local hc = require "resty.upstream.healthcheck"
                    st , err = hc.prometheus_status_page()
                    if not st then
                        ngx.say(err)
                        return
                    end
                    ngx.print(st)
                }
            }
        }
    }

描述

该库对由名称指定的 NGINX upstream 组中定义的服务器对等方执行健康检查。

方法

spawn_checker

语法: ok, err = healthcheck.spawn_checker(options)

上下文: init_worker_by_lua*

生成基于计时器的后台“轻量级线程”以对指定 NGINX 上游组使用指定的 shm 存储执行定期健康检查。

健康检查器不需要任何客户端流量即可运行。检查以主动方式定期执行。

此方法调用是异步的，并立即返回。

成功时返回 true，否则返回 nil 和描述错误的字符串。

status_page

语法: str, err = healthcheck.status_page()

上下文: 任何

为当前 NGINX 服务器中定义的所有上游生成详细的状态报告。

一个典型的输出是

    Upstream foo.com
        Primary Peers
            127.0.0.1:12354 UP
            127.0.0.1:12355 DOWN
        Backup Peers
            127.0.0.1:12356 UP
    
    Upstream bar.com
        Primary Peers
            127.0.0.1:12354 UP
            127.0.0.1:12355 DOWN
            127.0.0.1:12357 DOWN
        Backup Peers
            127.0.0.1:12356 UP

如果上游没有健康检查器，则它将被标记为 (NO checkers)，如

    Upstream foo.com (NO checkers)
        Primary Peers
            127.0.0.1:12354 UP
            127.0.0.1:12355 UP
        Backup Peers
            127.0.0.1:12356 UP

如果您确实在 init_worker_by_lua* 中生成了健康检查器，那么您应该真正查看 NGINX 错误日志文件以查看是否有任何致命错误中止了健康检查器线程。

多个上游

可以通过在 init_worker_by_lua* 处理程序中多次调用 spawn_checker 方法对多个 upstream 组执行健康检查。例如，

    upstream foo {
        ...
    }
    
    upstream bar {
        ...
    }
    
    lua_shared_dict healthcheck 1m;
    
    lua_socket_log_errors off;
    
    init_worker_by_lua_block {
        local hc = require "resty.upstream.healthcheck"
    
        local ok, err = hc.spawn_checker{
            shm = "healthcheck",
            upstream = "foo",
            ...
        }
    
        ...
    
        ok, err = hc.spawn_checker{
            shm = "healthcheck",
            upstream = "bar",
            ...
        }
    }

不同上游的健康检查器使用不同的键（始终以上游名称作为键的前缀），因此在多个检查器之间共享单个 lua_shared_dict 应该没有任何问题。但您需要为多个用户（即多个检查器）补偿共享字典的大小。如果您有很多上游（数千个甚至更多），那么为每个上游（组）使用单独的 shm 区域将更优化。

安装

如果您使用的是 OpenResty 1.9.3.2 或更高版本，那么您应该默认已经安装了该库（及其所有依赖项）（这也是使用该库的推荐方式）。否则，继续阅读

您需要将 ngx_lua 和 ngx_lua_upstream 模块都编译到您的 Nginx 中。

需要 ngx_lua 的最新 git master 分支。

您需要配置 lua_package_path 指令以将 lua-resty-upstream-healthcheck 源代码树的路径添加到 ngx_lua 的 Lua 模块搜索路径中，如

    # nginx.conf
    http {
        lua_package_path "/path/to/lua-resty-upstream-healthcheck/lib/?.lua;;";
        ...
    }

待办事项

社区

贡献

在打开 PR 之前，使用 make lint 对代码进行 lint。这使用了广泛使用的 LuaFormatter。

代码风格在 `.lua-format` 文件中描述。如果您使用的是 VS Code，您可以通过单击 此处 来安装该格式化程序的包装器。

英文邮件列表

用于说英语的人的 openresty-en 邮件列表。

中文邮件列表

用于说中文的人的 openresty 邮件列表。

错误和补丁

请通过以下方式报告错误或提交补丁

1. 在 GitHub 问题跟踪器 上创建一张票，

2. 或发布到 "OpenResty 社区"。

作者

Yichun “agentzh” Zhang (章亦春) <agentzh@gmail.com>，OpenResty Inc.

版权和许可

该模块根据 BSD 许可证发布。

版权所有 (C) 2014-2017，由 Yichun “agentzh” Zhang，OpenResty Inc.

保留所有权利。

允许以源代码和二进制形式重新分发和使用，无论是否修改，只要满足以下条件

• 重新分发的源代码必须保留上述版权声明、本条件列表以及以下免责声明。

• 二进制形式的重新分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、本条件列表以及以下免责声明。

本软件由版权持有人和贡献者“按现状”提供，不提供任何明示或暗示的担保，包括但不限于对适销性和特定用途适用性的暗示担保。在任何情况下，版权持有人或贡献者均不对任何直接、间接、偶然、特殊、示例性或后果性损害（包括但不限于获取替代商品或服务的费用；使用、数据或利润损失；或业务中断）负责，无论任何责任理论如何，无论是合同、严格责任还是侵权行为（包括疏忽或其他原因）引起，即使已告知其发生此类损害的可能性。

另请参阅

• ngx_lua 模块：https://github.com/openresty/lua-nginx-module

• ngx_lua_upstream 模块：https://github.com/openresty/lua-upstream-nginx-module

• OpenResty：https://openresty.org.cn