模块 ngx_http_upstream_hc_module

ngx_http_upstream_hc_module 模块允许启用对周围位置中引用的组中服务器的定期运行状况检查。服务器组必须驻留在共享内存中。

如果运行状况检查失败，则服务器将被视为不健康。如果为同一组服务器定义了多个运行状况检查，则任何检查的单次失败都将导致相应的服务器被视为不健康。客户端请求不会传递给不健康的服务器和处于“检查”状态的服务器。

请注意，当与运行状况检查一起使用时，大多数变量将具有空值。

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

示例配置

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 [parameters];`
默认	—
上下文	`location`

启用对周围位置中引用的组中服务器的定期运行状况检查。

支持以下可选参数

interval=time

设置两次连续运行状况检查之间的间隔，默认为 5 秒。

jitter=time

设置每个运行状况检查将随机延迟的时间，默认为无延迟。

fails=number

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

passes=number

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

uri=uri

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

mandatory [persistent]

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

persistent 参数 (1.19.7) 设置服务器在重新加载后重新加载后的初始“启动”状态，如果服务器在重新加载前被视为健康。

match=name

指定 match 块，配置响应应通过的测试，以便健康检查通过。默认情况下，响应应具有状态代码 2xx 或 3xx。

port=number

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

type=grpc [grpc_service=name] [grpc_status=code]

启用 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=time

为健康检查启用 keepalive 连接，并指定可以在一个 keepalive 连接中处理请求的时间 (1.21.7)。默认情况下，keepalive 连接处于禁用状态。

语法	`match name { ... }`
默认	—
上下文	`http`

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

可以在响应中测试以下项

状态 200；: 状态为 200
状态！500；: 状态不为 500
状态 200 204；: 状态为 200 或 204
状态！301 302；: 状态既不为 301 也不为 302
状态 200-399；: 状态在 200 到 399 的范围内
状态！400-599；: 状态不在 400 到 599 的范围内
状态 301-303 307；: 状态为 301、302、303 或 307

标头 Content-Type = text/html；: 标头包含“Content-Type”，其值为 text/html
标头 Content-Type != text/html；: 标头包含“Content-Type”，其值不为 text/html
标头 Connection ~ close；: 标头包含“Connection”，其值与正则表达式 close 匹配
标头 Connection !~ close；: 标头包含“Connection”，其值与正则表达式 close 不匹配
标头 Host；: 标头包含“Host”
标头！X-Accel-Redirect；: 标头缺少“X-Accel-Redirect”

正文 ~ “Welcome to nginx!”；: 正文与正则表达式“Welcome to nginx!”匹配
正文！~ “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;
}