Upstream Probe

该模块为 stream_upstream 实现了主动健康探测。

配置示例

server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}

备注

根据 RFC 2616 (HTTP/1.1) 和 RFC 9110 (HTTP Semantics)，HTTP 头部 必须使用 CRLF 序列 (\r\n) 分隔，而不是仅使用 \n。

指令

upstream_probe (PRO)

语法	upstream_probe name [port=number] [interval=time] [test=condition] [essential [persistent]] [fails=number] [passes=number] [max_response=size] [mode=always | idle | onfail] [udp] [send=string];
默认值	—
上下文	server

为 upstream 组中的服务器定义主动健康探测， 该组在与 upstream_probe 指令位于同一 server 上下文中的 proxy_pass 指令中指定。

如果对服务器的请求成功，则服务器通过探测，需考虑 upstream_probe 指令的所有参数设置以及影响定义它的 server 上下文如何使用上游的所有参数，包括 proxy_next_upstream 指令。

要使用探测功能， 上游必须具有共享内存区域 (zone)。 一个上游可以配置多个探测。

接受以下参数：

name	探测的必需名称。
port	探测请求的备用端口号。
interval	探测之间的 间隔。 默认值 — 5s。
test	探测的条件，定义为变量字符串。 如果变量替换结果为 "" 或 "0"， 则探测未通过。
essential	如果设置，将检查服务器的初始状态，因此服务器 在通过探测之前不会接收客户端请求。
persistent	设置此参数需要首先启用 essential； 在 配置重载 之前被认为健康的 persistent 服务器 无需首先通过此探测即可开始接收请求。
fails	使服务器变为不健康的连续失败探测次数。 默认值 — 1。
passes	使服务器变为健康的连续通过探测次数。 默认值 — 1。
max_response	响应的最大内存大小。如果指定零 值，则禁用响应等待。 默认值 — 256k。
mode	探测模式，取决于服务器的健康状态： always — 无论服务器状态如何都进行探测； idle — 探测影响不健康的服务器以及自上次客户端请求以来已过 interval 的服务器。 onfail — 仅探测不健康的服务器。 默认值 — always。
udp	如果指定，则使用 UDP 协议进行探测。 默认情况下，使用 TCP 进行探测。
send	为探测发送的数据：带有 data: 前缀的内联数据 或文件路径（绝对路径或相对于 /usr/local/angie/ 的路径）。 使用文件时： 工作进程 在每次访问时打开并读取 文件；内容不会缓存在内存中。 文件更改时不需要重新加载配置； 下次访问时将读取新内容。 所需的访问权限：文件为 644， 目录为 755。 使用移动命令 (mv) 更新文件， 而不是直接编辑。

示例：

upstream backend {
    zone backend 1m;

    server a.example.com;
    server b.example.com;
}

map $upstream_probe_response $good {
    ~200    "1";
    default  "";
}

server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        persistent
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}

探测操作的详细信息：

• 最初，服务器在通过为其配置的 所有 essential 探测之前不会接收客户端请求， 如果配置已重载且服务器在此之前被认为健康，则跳过 persistent 探测。 如果没有此类探测，则认为服务器健康。

• 如果为服务器配置的 任何 探测达到 fails 或服务器达到 max_fails， 则认为服务器不健康且不会接收客户端请求。

• 要使不健康的服务器再次被认为健康， 为其配置的 所有 探测必须达到各自的 passes； 之后，还会考虑 max_fails。

upstream_probe_timeout (PRO)

语法	upstream_probe_timeout time;
默认值	upstream_probe_timeout 50s;
上下文	server

设置使用 upstream_probe (PRO) 指令配置的健康探测与服务器建立的连接的最大空闲 时间；如果超过此限制，连接将被关闭。

内置变量

stream_upstream 模块支持以下内置变量：

$upstream_probe (PRO)

当前活动的 upstream_probe 的名称。

$upstream_probe_response (PRO)

在由 upstream_probe 配置的主动探测期间接收到的响应内容。