模块 ngx_http_upstream_hc_module

ngx_http_upstream_hc_module 模块允许对引用自周边 location 中的服务器组启用周期性健康检查。服务器组必须位于共享内存中。

如果健康检查失败，服务器将被视为不健康。如果为同一组服务器定义了多个健康检查，任何一个检查失败都会导致相应的服务器被视为不健康。客户端请求不会被发送到不健康的服务器和处于“checking”状态的服务器。

请注意，在健康检查中使用大多数变量时，它们的值将为空。

此模块作为我们的商业订阅的一部分提供。

配置示例

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;

    server backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

通过此配置，nginx 将每隔五秒向 backend 组中的每台服务器发送 “/” 请求。如果发生任何通信错误或超时，或者代理的服务器响应状态码不是 2xx 或 3xx，健康检查将失败，服务器将被视为不健康。

健康检查可以配置为测试响应的状态码、某些头部字段及其值的存在性以及响应体内容。测试使用 match 指令单独配置，并在 health_check 指令的 match 参数中引用。

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

此配置表明，要使健康检查通过，健康检查请求的响应必须成功，状态码为 200，并且响应体中包含 “Welcome to nginx!”。

指令

语法	`health_check [参数];`
默认值	—
上下文	`location`

启用对引用自周边 location 中的服务器组的周期性健康检查。

支持以下可选参数：

interval=时间

设置两次连续健康检查之间的间隔时间，默认值为 5 秒。

jitter=时间

设置每次健康检查将被随机延迟的时间范围，默认没有延迟。

fails=数字

设置特定服务器连续失败健康检查的次数，达到此次数后该服务器将被视为不健康，默认值为 1。

passes=数字

设置特定服务器连续通过健康检查的次数，达到此次数后服务器将被视为健康，默认值为 1。

uri=uri

定义健康检查请求中使用的 URI，默认值为 “/”。

mandatory [persistent]

为服务器设置初始的“checking”状态，直到第一次健康检查完成 (1.11.7)。客户端请求不会被发送到处于“checking”状态的服务器。如果未指定此参数，服务器初始将被视为健康。

persistent 参数 (1.19.7) 设置服务器在重载后（如果重载前该服务器被视为健康）的初始“up”状态。

match=名称

指定配置测试的 match 块，响应必须通过这些测试，健康检查才算通过。默认情况下，响应应具有状态码 2xx 或 3xx。

port=端口号

定义连接到服务器执行健康检查时使用的端口 (1.9.7)。默认等于 server 端口。

type=grpc [grpc_service=名称] [grpc_status=代码]

启用对 gRPC 服务器或使用可选的 grpc_service 参数指定的特定 gRPC 服务执行周期性健康检查 (1.19.5)。如果服务器不支持 gRPC 健康检查协议，可以使用可选的 grpc_status 参数指定将被视为健康的非零 gRPC 状态码（例如，状态码“12”/“UNIMPLEMENTED”）。

health_check mandatory type=grpc grpc_status=12;

type=grpc 参数必须在所有其他指令参数之后指定，grpc_service 和 grpc_status 必须跟在 type=grpc 之后。此参数与 uri 或 match 参数不兼容。

keepalive_time=时间

为健康检查启用 keepalive 连接，并指定通过一个 keepalive 连接处理请求的时间 (1.21.7)。默认情况下 keepalive 连接是禁用的。

语法	`match 名称 { ... }`
默认值	—
上下文	`http`

定义用于验证健康检查响应的命名测试集。

可以在响应中测试以下各项：

status 200;: 状态码是 200
status ! 500;: 状态码不是 500
status 200 204;: 状态码是 200 或 204
status ! 301 302;: 状态码既不是 301 也不是 302
status 200-399;: 状态码范围在 200 到 399 之间
status ! 400-599;: 状态码范围不在 400 到 599 之间
status 301-303 307;: 状态码是 301、302、303 或 307

header Content-Type = text/html;: 头部包含 “Content-Type” 字段，其值为 text/html
header Content-Type != text/html;: 头部包含 “Content-Type” 字段，其值不是 text/html
header Connection ~ close;: 头部包含 “Connection” 字段，其值匹配正则表达式 close
header Connection !~ close;: 头部包含 “Connection” 字段，其值不匹配正则表达式 close
header Host;: 头部包含 “Host” 字段
header ! X-Accel-Redirect;: 头部缺少 “X-Accel-Redirect” 字段

body ~ "Welcome to nginx!";: 响应体匹配正则表达式 “Welcome to nginx!”
body !~ "Welcome to nginx!";: 响应体不匹配正则表达式 “Welcome to nginx!”

require $variable ...;: 所有指定的变量都不为空且不等于 “0” (1.15.9)。

如果指定了多个测试，响应只有在通过所有测试时才算匹配。

仅检查响应体的前 256k 内容。

示例

# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}

# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}

# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}

# status is 200 or 204
map $upstream_status $good_status {
    200 1;
    204 1;
}

match server_ok {
    require $good_status;
}