模块 ngx_stream_upstream_module

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

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以及与第二台和第三台服务器各有一个连接。 如果在与服务器通信期间发生错误，则连接将 传递给下一个服务器，依此类推，直到所有正常运行的 服务器将被试用。 如果与所有服务器的通信失败，连接将关闭。

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

可以定义以下参数：

weight=number

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

max_conns=number

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

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

max_fails=number

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

fail_timeout=time

集

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

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

backup

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

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

down

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

resolve

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

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

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

service=name

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

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

server backend.example.com service=http resolve;

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

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

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

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

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

定义name和size共享的 内存区域，该区域保持组的配置和运行时状态 在 worker 进程之间共享。 多个组可以共享同一区域。 在这种情况下，指定size只有一次。

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

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

指定file保持 state 动态可配置的组。

例子：

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

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

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

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

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

hash $remote_addr;

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

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

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

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

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

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

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

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

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

这least_time方法将连接传递给服务器 平均时间和最少的活动连接数。 如果least_time=connectparameter 时， 使用连接到上游服务器的时间。 如果least_time=first_byteparameter 时， 使用接收第一个字节数据的时间。 如果least_time=last_byte指定， 使用接收数据最后一个字节的时间。

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

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

resolver 127.0.0.1 [::1]:5353;

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

默认情况下，nginx 将在解析时查找 IPv4 和 IPv6 地址。 如果不需要查找 IPv4 或 IPv6 地址， 这ipv4=off（1.23.1） 或 这ipv6=offparameter 的

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

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

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

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

从 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） 的路径。 如果在代理期间联系了多个服务器， 它们的地址用逗号分隔，例如 “192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”. 如果无法选择服务器， 该变量保留 Server 组的名称。

$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 变量中的地址一样。