ngx_stream_upstream_module 模块

ngx_stream_upstream_module 模块 (1.9.0) 用于定义服务器组，这些服务器组可以通过 proxy_pass 指令引用。

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

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

server {
    listen 12346;
    proxy_pass backend;
}

动态可配置的服务器组，带有周期性的健康检查，可作为我们的商业订阅的一部分提供

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;
    server backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

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

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

定义服务器组。服务器可以监听不同的端口。此外，可以混合使用监听 TCP 和 UNIX 域套接字的服务器。

示例

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

默认情况下，连接使用加权轮询平衡方法在服务器之间分发。在上面的示例中，每 7 个连接将按如下方式分发：5 个连接到 backend1.example.com:12345，其余第二个和第三个服务器各一个连接。如果在与服务器通信期间发生错误，连接将传递到下一个服务器，依此类推，直到尝试完所有正常工作的服务器。如果与所有服务器的通信都失败，连接将被关闭。

定义服务器的地址和其它参数。地址可以指定为带必需端口的域名或 IP 地址，或者指定为在“unix:”前缀后的 UNIX 域套接字路径。解析为多个 IP 地址的域名会同时定义多个服务器。

可以定义以下参数：

weight=数字

设置服务器的权重，默认为 1。

max_conns=数字

限制与代理服务器的同时连接的最大数量 (1.11.5)。默认值为零，表示没有限制。如果服务器组不住在共享内存中，此限制对每个工作进程有效。

在 1.11.5 版本之前，此参数可作为我们的商业订阅的一部分提供。

max_fails=数字

设置在fail_timeout参数设定的持续时间内与服务器通信失败的尝试次数，达到此次数后，服务器将被视为不可用，持续时间也由fail_timeout参数设定。默认情况下，失败尝试次数设置为 1。零值禁用尝试计数。这里的失败尝试指在与服务器建立连接时的错误或超时。

fail_timeout=时间

设置

• 在指定次数的失败尝试与服务器通信应该发生的持续时间，达到此持续时间后服务器将被视为不可用；
• 以及服务器将被视为不可用的持续时间。

默认情况下，参数设置为 10 秒。

backup

将服务器标记为备份服务器。当主服务器不可用时，连接将传递给备份服务器。

此参数不能与 hash 和 random 负载均衡方法一起使用。

down

将服务器标记为永久不可用。

resolve

监视与服务器域名对应的 IP 地址变化，并自动修改 upstream 配置，无需重新启动 nginx。服务器组必须驻留在共享内存中。

为了使此参数生效，必须在 stream 块或相应的 upstream 块中指定 resolver 指令。

在 1.27.3 版本之前，此参数仅作为我们的商业订阅的一部分提供。

service=名称

启用 DNS SRV 记录解析并设置服务名称 (1.9.13)。为了使此参数生效，需要为服务器指定 resolve 参数，并指定不带端口号的主机名。

如果服务名称不包含点号 (“.”)，则会构造符合 RFC 的名称，并将 TCP 协议添加到服务前缀。例如，要查找 _http._tcp.backend.example.com SRV 记录，需要指定指令

server backend.example.com service=http resolve;

如果服务名称包含一个或多个点号，则通过连接服务前缀和服务器名称构造名称。例如，要查找 _http._tcp.backend.example.com 和 server1.backend.example.com SRV 记录，需要指定指令

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

最高优先级的 SRV 记录（具有相同最低优先级值的记录）被解析为主服务器，其余 SRV 记录被解析为备份服务器。如果为服务器指定了 backup 参数，则高优先级 SRV 记录被解析为备份服务器，其余 SRV 记录将被忽略。

在 1.27.3 版本之前，此参数仅作为我们的商业订阅的一部分提供。

此外，以下参数可作为我们的商业订阅的一部分提供：

slow_start=时间

设置服务器从不健康变为健康时，或者在被视为不可用一段时间后变为可用时，权重从零恢复到标称值所需的时间。默认值为零，即禁用慢启动。

此参数不能与 hash 和 random 负载均衡方法一起使用。

如果组中只有单个服务器，则忽略 max_fails、fail_timeout 和 slow_start 参数，并且此类服务器永远不会被视为不可用。

定义共享内存区域的名称和大小，该区域保留在工作进程之间共享的组配置和运行时状态。多个组可以共享同一个区域。在这种情况下，只需指定一次大小即可。

此外，作为我们的商业订阅的一部分，此类组允许更改组成员或修改特定服务器的设置，而无需重新启动 nginx。可通过 API 模块访问配置 (1.13.3)。

在 1.13.3 版本之前，配置只能通过由 upstream_conf 处理的特殊 location 访问。

指定一个文件，该文件保留动态可配置组的状态。

示例

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

当前状态仅限于包含服务器及其参数的列表。在解析配置时读取文件，并在 upstream 配置每次更改时更新。应避免直接更改文件内容。此指令不能与 server 指令一起使用。

在重新加载配置或二进制升级期间所做的更改可能会丢失。

此指令可作为我们的商业订阅的一部分提供。

指定服务器组的负载均衡方法，其中客户端-服务器映射基于哈希计算的键值。键可以包含文本、变量及其组合 (1.11.2)。使用示例

hash $remote_addr;

请注意，从组中添加或删除服务器可能会导致大多数键被重新映射到不同的服务器。此方法与 Cache::Memcached Perl 库兼容。

如果指定了 consistent 参数，则会使用 ketama 一致性哈希方法代替。此方法确保在从组中添加或删除服务器时，只有少量键会被重新映射到不同的服务器。这有助于缓存服务器实现更高的缓存命中率。此方法与设置了 ketama_points 参数为 160 的 Cache::Memcached::Fast Perl 库兼容。

指定组应使用一种负载均衡方法，该方法将连接传递给活动连接数最少的服务器，同时考虑服务器的权重。如果存在多个此类服务器，则使用加权轮询平衡方法依次尝试它们。

指定组应使用一种负载均衡方法，该方法将连接传递给平均时间最短且活动连接数最少的服务器，同时考虑服务器的权重。如果存在多个此类服务器，则使用加权轮询平衡方法依次尝试它们。

如果指定了 connect 参数，则使用到 upstream 服务器的连接时间。如果指定了 first_byte 参数，则使用接收第一个字节数据的时间。如果指定了 last_byte，则使用接收最后一个字节数据的时间。如果指定了 inflight 参数 (1.11.6)，则也会考虑不完整连接。

在 1.11.6 版本之前，默认情况下会考虑不完整连接。

此指令可作为我们的商业订阅的一部分提供。

指定组应使用一种负载均衡方法，该方法将连接传递给随机选择的服务器，同时考虑服务器的权重。

可选的 two 参数指示 nginx 随机选择两个服务器，然后使用指定的method选择一个服务器。默认方法是 least_conn，它将连接传递给活动连接数最少的服务器。

least_time 方法将连接传递给平均时间最短且活动连接数最少的服务器。如果指定了 least_time=connect 参数，则使用到 upstream 服务器的连接时间。如果指定了 least_time=first_byte 参数，则使用接收第一个字节数据的时间。如果指定了 least_time=last_byte，则使用接收最后一个字节数据的时间。

least_time 方法可作为我们的商业订阅的一部分提供。

配置用于将 upstream 服务器名称解析为地址的名称服务器，例如

resolver 127.0.0.1 [::1]:5353;

地址可以指定为域名或 IP 地址，带可选端口。如果未指定端口，则使用端口 53。名称服务器以轮询方式查询。

默认情况下，nginx 在解析时会同时查找 IPv4 和 IPv6 地址。如果不需要查找 IPv4 或 IPv6 地址，可以指定 ipv4=off (1.23.1) 或 ipv6=off 参数。

默认情况下，nginx 使用响应的 TTL 值缓存答案。可选的 valid 参数允许覆盖它

resolver 127.0.0.1 [::1]:5353 valid=30s;

为了防止 DNS 欺骗，建议在适当安全的可信本地网络中配置 DNS 服务器。

可选的 status_zone 参数 (1.17.5) 允许在指定的区域中收集 DNS 服务器请求和响应的统计信息。此参数可作为我们的商业订阅的一部分提供。

自 1.17.5 版本起，且在 1.27.3 版本之前，此指令仅作为我们的商业订阅的一部分提供。

resolver_timeout 30s;

设置名称解析的超时时间，例如

resolver_timeout 5s;

自 1.17.5 版本起，且在 1.27.3 版本之前，此指令仅作为我们的商业订阅的一部分提供。

ngx_stream_upstream_module 模块支持以下嵌入式变量：

$upstream_addr

保留 upstream 服务器的 IP 地址和端口，或 UNIX 域套接字的路径 (1.11.4)。如果在代理期间联系了多个服务器，它们的地址用逗号分隔，例如 “192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”。如果无法选择服务器，变量将保留服务器组的名称。

$upstream_bytes_received

从 upstream 服务器接收的字节数 (1.11.4)。多个连接的值用逗号分隔，类似于 $upstream_addr 变量中的地址。

$upstream_bytes_sent

发送到 upstream 服务器的字节数 (1.11.4)。多个连接的值用逗号分隔，类似于 $upstream_addr 变量中的地址。

$upstream_connect_time

连接到 upstream 服务器的时间 (1.11.4)；时间以秒为单位，精度为毫秒。多个连接的时间用逗号分隔，类似于 $upstream_addr 变量中的地址。

$upstream_first_byte_time

接收到第一个字节数据的时间 (1.11.4)；时间以秒为单位，精度为毫秒。多个连接的时间用逗号分隔，类似于 $upstream_addr 变量中的地址。

$upstream_session_time

会话持续时间，以秒为单位，精度为毫秒 (1.11.4)。多个连接的时间用逗号分隔，类似于 $upstream_addr 变量中的地址。