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地址的更改，并在不需要重新启动nginx的情况下自动修改上游配置。服务器组必须驻留在共享内存中。

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

service=name

启用解析DNS SRV记录，并设置服务name (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记录被忽略。

slow_start=time

设置服务器从零恢复其权重到名义值的time时间，在不健康的服务器变为健康或在服务器在被认为不可用的一段时间后变为可用时。默认值为零，即禁用慢启动。

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

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

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

此外，作为我们 商业订阅 的一部分，这些组允许更改组成员身份或修改特定服务器的设置，而无需重启 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

当前状态仅限于带有其参数的服务器列表。解析配置时读取文件，并且每次更改上游配置时都会更新文件。应避免直接更改文件内容。该指令不能与 server 指令一起使用。

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

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

为服务器组指定基于散列 key 值的负载均衡方法，客户端-服务器映射基于此散列值。 key 可包含文本、变量及其组合（1.11.2）。用法示例：

hash $remote_addr;

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

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

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

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

如果指定了connect参数，则使用连接到上游服务器的时间。如果指定了first_byte参数，则使用接收到的数据的第一个字节的时间。如果指定了last_byte，则使用接收到的数据的最后一个字节的时间。如果指定了inflight参数（1.11.6），还将考虑不完整的连接。

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

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

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

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

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

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

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

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` 参数启用对指定的 `zone` 中 DNS 服务器请求和响应的统计信息的 收集。

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

resolver_timeout 30s;

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

resolver_timeout 5s;

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

`ngx_stream_upstream_module` 模块支持以下内嵌变量：

$upstream_addr

保留上游服务器的 IP 地址和端口，或者 UNIX 域套接字的路径（1.11.4）。如果在代理过程中联系了多台服务器，它们的地址将用逗号分隔，例如 “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 变量中的地址一样。