模块 ngx_stream_upstream_module

模块 （1.9.0） 用于定义可引用的服务器组 由 proxy_pass Directives。ngx_stream_upstream_module

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

定义服务器的 and other。 地址可以指定为域名或 IP 地址 具有强制端口，或作为 UNIX 域套接字路径 在 “” 前缀后指定。 解析为多个 IP 地址的域名定义 一次多个服务器。addressparametersunix:

可以定义以下参数：

weight=number

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

max_conns=number

限制最大同时 连接到代理服务器 （1.11.5）。 默认值为零，这意味着没有限制。 如果服务器组不驻留在共享内存中，则 该限制适用于每个 worker 进程。number

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

max_fails=number

设置与 服务器通信的失败尝试次数 这应该发生在参数设置的持续时间内，以将服务器视为在参数设置的持续时间内不可用。 默认情况下，失败尝试的次数设置为 1。 零值将禁用尝试的计数。 此处，不成功的尝试是错误或超时 同时与服务器建立连接。fail_timeoutfail_timeout

fail_timeout=time

集

• 指定次数的失败尝试 与 server 通信时应恰好认为 server 不可用;
• 以及服务器将被视为不可用的时间段。

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

backup

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

该参数不能与 hash 和随机负载均衡方法一起使用。

down

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

resolve

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

为了使此参数起作用， Directives 必须在 Stream 块中指定 或在相应的上游区块中。resolver

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

service=name

启用 DNS SRV 记录的解析并设置服务 （1.9.13）。 为了使此参数正常工作，必须指定 服务器的 resolve 参数 并指定不带端口号的主机名。name

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

server backend.example.com service=http resolve;

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

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

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

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

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

slow_start=time

设置服务器将恢复其权重的期间 从 0 到标称值，当运行状况不佳的服务器变为运行状况良好时， 或者当服务器在一段时间后变为可用时 它被认为不可用。 默认值为零，即禁用慢启动。time

该参数不能与 hash 和随机负载均衡方法一起使用。

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

定义共享的 和 内存区域，该区域保持组的配置和运行时状态 在 worker 进程之间共享。 多个组可以共享同一区域。 在这种情况下，指定 only once 就足够了。namesizesize

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

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

指定一个保持状态 动态可配置的组。file

例子：

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

该状态当前仅限于服务器及其参数的列表。 该文件在解析配置时读取，每次更新时 上游配置已更改。 应避免直接更改文件内容。 不能使用该Directives 以及 server Directives。

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

该Directives作为我们商业订阅的一部分提供。

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

hash $remote_addr;

请注意，在组中添加或删除服务器 可能会导致将大多数密钥重新映射到不同的服务器。 该方法与 Cache：：Memcached Perl 库兼容。

如果指定了该参数，则 将改用 Ketama 一致性哈希方法。 该方法确保只有几个键 将重新映射到不同的服务器 在组中添加或删除服务器时。 这有助于为缓存服务器实现更高的缓存命中率。 该方法与参数设置为 160 的 Cache：：Memcached：：Fast Perl 库兼容。consistentketama_points

指定组应使用负载平衡方法，其中连接 传递到活动连接数最少的服务器， 考虑到服务器的重量。 如果有多个这样的服务器，则使用 加权循环平衡方法。

指定组应使用负载平衡方法，其中连接 传递到平均时间最短的服务器，并且 最少的活动连接数，考虑到服务器的权重。 如果有多个这样的服务器，则使用 加权循环平衡方法。

如果指定了该参数，则 使用连接到上游服务器的时间。 如果指定了该参数，则 使用接收第一个字节数据的时间。 如果指定了 the ， 使用接收数据最后一个字节的时间。 如果指定了该参数 （1.11.6）， 不完整的连接也会被考虑在内。connectfirst_bytelast_byteinflight

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

该Directives作为我们商业订阅的一部分提供。

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

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

该方法将连接传递给服务器 平均时间和最少的活动连接数。 如果指定了 parameter，则 使用连接到上游服务器的时间。 如果指定了 parameter，则 使用接收第一个字节数据的时间。 如果指定，则 使用接收数据最后一个字节的时间。least_timeleast_time=connectleast_time=first_byteleast_time=last_byte

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

配置用于解析上游服务器名称的名称服务器 转换为地址，例如：

resolver 127.0.0.1 [::1]:5353;

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

默认情况下，nginx 将在解析时查找 IPv4 和 IPv6 地址。 如果不需要查找 IPv4 或 IPv6 地址， （1.23.1） 或 可以指定该参数。ipv4=offipv6=off

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

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

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

可选参数 （1.17.5） 启用请求和响应的 DNS 服务器统计信息的收集 在指定的 . 该参数作为我们商业订阅的一部分提供。status_zonezone

从 1.17.5 版本到 1.27.3 版本之前， 该Directives仅作为我们商业订阅的一部分提供。

resolver_timeout 30s;

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

resolver_timeout 5s;

从 1.17.5 版本到 1.27.3 版本之前， 该Directives仅作为我们商业订阅的一部分提供。

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

$upstream_addr

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

$upstream_bytes_received

从上游服务器接收的字节数 （1.11.4）。 来自多个连接的值 用逗号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_bytes_sent

发送到上游服务器的字节数 （1.11.4）。 来自多个连接的值 用逗号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_connect_time

连接到上游服务器的时间 （1.11.4）; 该时间以秒为单位，分辨率为毫秒。 多次连接的时间 用逗号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_first_byte_time

接收第一个字节数据的时间 （1.11.4）; 该时间以秒为单位，分辨率为毫秒。 多次连接的时间 用逗号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_session_time

会话持续时间（以秒为单位），毫秒分辨率 （1.11.4）。 多次连接的时间 用逗号分隔，就像 $upstream_addr 变量中的地址一样。