$ opm get openresty/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",
    
                http_req = "GET /status HTTP/1.0\r\nHost: foo.com\r\n\r\n",
                        -- raw HTTP request for checking
    
                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
            }
            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())
                }
            }
        }
    }

描述

此库对由名称指定的 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 {
        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;;";
        ...
    }

待办事项

社区

英文邮件列表

openresty-en 邮件列表供英语使用者使用。

中文邮件列表

openresty 邮件列表供中文使用者使用。

错误和补丁

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

1. 在 GitHub 问题跟踪器 上创建工单，

2. 或发布到 “OpenResty 社区”。

作者

章亦春 (agentzh) <agentzh@gmail.com>，OpenResty Inc.

版权和许可

此模块在 BSD 许可下获得许可。

版权所有 (C) 2014-2017，由章亦春 (agentzh)，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