Nginx官方文档(三十七)【ngx_http_upstream_conf_module|ngx_http_upstream_hc_module】

雨点打透心脏的1/2处 2021-07-05 00:05 363阅读 0赞

# ngx\_http\_upstream\_conf\_module #

*  示例配置
 *  指令
    
     *  upstream\_conf

**直到 1.13.10 版本，它被 1.13.3 中的 ngx\_http\_api\_module 模块所取代。**

`ngx_http_upstream_conf_module` 模块允许通过简单的 HTTP 接口即时配置上游（upstream）服务器组，而无需重新启动 nginx。http 或流服务器组必须驻留在共享内存中。

> 该模块作为[商业订阅][Link 1]部分提供，

## 示例配置 ##

upstream backend {
        zone upstream_backend 64k;
    
        ...
    }
    
    server {
        location /upstream_conf {
            upstream_conf;
            allow 127.0.0.1;
            deny all;
        }
    }

## 指令 ##

### upstream\_conf ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>upstream_conf</strong>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">location</td> 
  </tr> 
 </tbody> 
</table>

在 location 中引入该指令，开启上游配置 HTTP 接口。 应限制访问此 location。

配置命令可用于：

*  查看组配置
 *  查看、修改或删除服务器
 *  添加新服务器

> 由于组中的地址不要求唯一，因此组中的服务器使用 ID 引用。添加新服务器或查看组配置时，会自动分配 ID 并显示 ID。

配置命令作为请求参数传入，例如：

http://127.0.0.1/upstream_conf?upstream=backend

支持以下参数：

*  `stream=`
    
    选择一个 stream 上游服务器组。如果没有此参数，将选择一个 http 上游服务器组。
 *  `upstream=name`
    
    选择要使用的组。此参数是必需的。
 *  `id=number`
    
    选择一个要查看、修改或删除的服务器。
 *  `remove=`
    
    从组中删除一个服务器。
 *  `add=`
    
    向组中添加一个新服务器。
 *  `backup=`
    
    需要添加一个备用服务器。
    
    > 在 1.7.2 版之前，查看、修改或删除现有备用服务器还需要 `backup=` 参数。
 *  `server=address`
    
    与 http 或 stream 上游服务器的 `address` 参数相同。
    
    添加服务器时，可以将其指定为一个域名。这种情况下，将监视与域名对应的 IP 地址的更改并自动应用于上游配置，无需重新启动 nginx（1.7.2）。这需要 http 或 stream 块中的 `resolver` 指令。另请参阅 http 或 stream 上游服务器的 `resolve` 参数。
 *  `service=name`
    
    与 http 或 stream 上游服务器的 `service` 参数相同（1.9.13）。
 *  `weight=number`
    
    与 http 或 stream 上游服务器的 `weight` 参数相同。
 *  `max_conns=number`
    
    与 http 或 stream 上游服务器的 `max_conns` 参数相同。
 *  `max_fails=number`
    
    与 http 或 stream 上游服务器的 `max_fails` 参数相同。
 *  `fail_timeout=time`
    
    与 http 或 stream 上游服务器的 `fail_timeout` 参数相同。
 *  `slow_start=time`
    
    与 http 或 stream 上游服务器的 `slow_start` 参数相同。
 *  `down=`
    
    与 http 或 stream 上游服务器的 `down` 参数相同。
 *  `drain=`  
    将 http 上游服务器置为 `draining` 模式（1.7.5）。在此模式下，只有绑定到服务器的请求才会被代理。
 *  `up=`
    
    与 http 或 stream 上游服务器的 `down` 参数相反。
 *  `route=string`
    
    与 http 上游服务器的 `route` 参数相同。

前三个参数会选择一个对象。这可以是整个 http 或 stream 上游服务器组，也可以是特定服务器。如果没有其他参数，则会显示所选组或服务器的配置。

例如，要查看整个组的配置，请发送：

http://127.0.0.1/upstream_conf?upstream=backend

要查看特定服务器的配置，还要指定其 ID：

http://127.0.0.1/upstream_conf?upstream=backend&id=42

要添加新服务器，请在 `server=` 参数中指定其地址。如果未指定其他参数，添加服务器时将其他参数设置为其默认值（请参阅 http 或 stream 的 `server` 指令）。

例如，要添加一个新的主服务器，请发送：

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080

要添加一个备用服务器，发送：

http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080

要添加一个新的主服务器，将其参数设置为非默认值并将其标记为 `down`，发送：

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down=

删除一个服务器，指定其 ID：

http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42

讲一个现有的服务器标记为 `down`，发送：

http://127.0.0.1/upstream_conf?upstream=backend&id=42&down=

修改一个现有服务器的地址，发送：

http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123

修改一个现有服务器的其他参数，发送：

http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4

以上示例适用于 http 上游服务器组。stream 上游服务器组需要加上 `stream=` 参数。

## 原文档 ##

*  [http://nginx.org/en/docs/http/ngx\_http\_upstream\_conf\_module.html][http_nginx.org_en_docs_http_ngx_http_upstream_conf_module.html]

--------------------

# ngx\_http\_upstream\_hc\_module #

*  示例配置
 *  指令
    
     *  health\_check
     *  match

`ngx_http_upstream_hc_module` 模块允许对周边 location 中引用的组中的服务器进行定期健康检查。服务器组必须驻留在共享内存中。

如果健康检查失败，则服务器将被视为运行状况不佳。如果为同一组服务器定义了多个健康检查，则任何检查的单个故障都将使相应的服务器被视为运行状况不佳。客户端请求不会传递到处于 **checking** 状态的服务器和不健康的服务器。

> 请注意，与健康检查一起使用时，大多数变量都将为空值。

> 该模块作为[商业订阅][Link 2]部分提供。

## 示例配置 ##

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 ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>health_check</strong> <code>[parameters]</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">location</td> 
  </tr> 
 </tbody> 
</table>

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

支持以下可选参数：

*  `interval=time`
    
    设置两次连续健康检查之间的间隔时间，默认为 5 秒
 *  `jitter=time`
    
    设置每个健康检查随机延迟的时间，默认情况下，没有延迟
 *  `fails=number`
    
    设置特定服务器的连续失败健康检查的数量，在此之后，此服务器将被视为不健康，默认情况下为 1。
 *  `passes=number`
    
    设置特定服务器的连续通过健康检查的数量，在此之后服务器将被视为健康，默认情况下为 1。
 *  `uri=uri`
    
    定义健康检查请求中使用的 URI，默认情况下为 `/`。
 *  `mandatory`
    
    设置服务器的初始 **checking** 状态，直到第一次运行健康检查完成（1.11.7）。客户端请求不会传递到处于 **checking** 状态的服务器。如果未指定参数，则服务器开始将被视为健康。
 *  `match=name`
    
    指定 `match` 块配置测试，为响应通过测试做参照，以便通过健康检查。默认情况下，响应的状态码应为 2xx 或 3xx。
 *  `port=number`
    
    定义连接到服务器以执行健康检查时使用的端口（1.9.7）。默认情况下，等于 server 端口。

### match ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>match</strong> <code>name { ... }</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http</td> 
  </tr> 
 </tbody> 
</table>

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

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

*  `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;`
    
    header 包含值为 `text/html` 的 **Content-Type**
 *  `header Content-Type != text/html;`
    
    header 包含 **Content-Type**，其值不是 `text/html`
 *  `header Connection ~ close;`
    
    header 包含 **Connection** ，其值与正则表达式 `close` 匹配
 *  `header Connection !~ close;`
    
    header 包含 **Connection**，其值与正则表达式 `close` 不匹配
 *  `header Host;`
    
    header 包含 **Host**
 *  `header ! X-Accel-Redirect;`
    
    header 没有 **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;
    }

## 原文档 ##

*  [http://nginx.org/en/docs/http/ngx\_http\_upstream\_hc\_module.html][http_nginx.org_en_docs_http_ngx_http_upstream_hc_module.html]

[Link 1]: http://nginx.com/products/?_ga=2.70698388.504417624.1562407216-1811470965.1562407216
[http_nginx.org_en_docs_http_ngx_http_upstream_conf_module.html]: http://nginx.org/en/docs/http/ngx_http_upstream_conf_module.html
[Link 2]: http://nginx.com/products/?_ga=2.72493466.860729840.1564753618-1186072494.1564163363
[http_nginx.org_en_docs_http_ngx_http_upstream_hc_module.html]: http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html