# Upstream Probe 该模块为 [stream_upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) 实现了主动健康探测。 ## 配置示例 ```nginx 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"; } ``` #### NOTE 根据 RFC 2616 (HTTP/1.1) 和 RFC 9110 (HTTP Semantics)，HTTP 头部 必须使用 CRLF 序列 (`\r\n`) 分隔，而不是仅使用 `\n`。 ## 指令 ### upstream_probe (PRO) | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `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] [`ping`] [`ping_timeout=`time]; | |--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 为 [upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 组中的服务器定义主动健康探测， 该组在与 `upstream_probe` 指令位于同一 `server` 上下文中的 [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) 指令中指定。 如果对服务器的请求成功，则服务器通过探测，需考虑 `upstream_probe` 指令的所有参数设置以及影响定义它的 `server` 上下文如何使用上游的所有参数，包括 [proxy_next_upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream) 指令。 要使用探测功能， 上游必须具有共享内存区域 ([zone](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone))。 一个上游可以配置多个探测。 接受以下参数： | `name` | 探测的必需名称。 | |----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `port` | 探测请求的备用端口号。 | | `interval` | 探测之间的 [间隔](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)。
默认值 — `5s`。 | | `test` | 探测的条件，定义为变量字符串。
如果变量替换结果为 `""` 或 `"0"`，
则探测未通过。 | | `essential` | 如果设置，将检查服务器的初始状态，因此服务器
在通过探测之前不会接收客户端请求。 | | `persistent` | 设置此参数需要首先启用 `essential`；
在 [配置重载](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile-reloading) 之前被认为健康的
`persistent` 服务器
无需首先通过此探测即可开始接收请求。 | | `fails` | 使服务器变为不健康的连续失败探测次数。
默认值 — 1。 | | `passes` | 使服务器变为健康的连续通过探测次数。
默认值 — 1。 | | `max_response` | 响应的最大内存大小。如果指定零
[值](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)，则禁用响应等待。
默认值 — `256k`。 | | `mode` | 探测模式，取决于服务器的健康状态：

- `always` — 无论服务器状态如何都进行探测；
- `idle` — 探测影响不健康的服务器以及自上次客户端请求以来已过
`interval` 的服务器。
- `onfail` — 仅探测不健康的服务器。

默认值 — `always`。 | | `udp` | 如果指定，则使用 UDP 协议进行探测。
默认情况下，使用 TCP 进行探测。 | | `send` | 为探测发送的数据：带有 `data:` 前缀的内联数据
或文件路径（绝对路径或相对于 `/usr/local/angie/` 的路径）。

使用文件时：

- [工作进程](https://cn.angie.software//angie/docs/configuration/modules/core.md#worker-processes) 在每次访问时打开并读取
文件；内容不会缓存在内存中。
- 文件更改时不需要重新加载配置；
下次访问时将读取新内容。
- 所需的访问权限：文件为 `644`，
目录为 `755`。
- 使用移动命令 (`mv`) 更新文件，
而不是直接编辑。 | | `ping` (PRO) | 使用 ICMP 回显请求代替 TCP/UDP 探测。
需要使用 `--with-stream_upstream_probe_icmp` 构建 Angie。
不兼容 `test`、`port`、
`udp` 或 `send`。 | | `ping_timeout` (PRO) | 等待 ICMP 回显应答的超时时间。
默认值 — `1s`。 | 示例： ```nginx 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](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails)， 则认为服务器不健康且不会接收客户端请求。 - 要使不健康的服务器再次被认为健康， 为其配置的 *所有* 探测必须达到各自的 `passes`； 之后，还会考虑 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails)。 ### upstream_probe_timeout (PRO) | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe_timeout` time; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `upstream_probe_timeout 50s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 设置使用 [upstream_probe (PRO)](#s-u-upstream-probe) 指令配置的健康探测与服务器建立的连接的最大空闲 [时间](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)；如果超过此限制，连接将被关闭。 ## 内置变量 `stream_upstream` 模块支持以下内置变量： ### `$upstream_probe` (PRO) 当前活动的 [upstream_probe](#s-u-upstream-probe) 的名称。 ### `$upstream_probe_response` (PRO) 在由 [upstream_probe](#s-u-upstream-probe) 配置的主动探测期间接收到的响应内容。