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

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

可以定义以下参数：

weight=number

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

max_conns=number

number限制代理服务器的 最大同时连接数 (1.11.5)。默认值为零，表示没有限制。如果服务器组不驻留在共享内存中，则该限制适用于每个工作进程。

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

max_fails=number

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

fail_timeout=time

套

• 尝试与服务器通信失败达到指定次数的时间应视为服务器不可用；
• 以及服务器被视为不可用的时间段。

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

backup

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

该参数不能与哈希、随机负载均衡方法 一起使用 。

down

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

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

resolve

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

为了使该参数起作用，必须在流块或相应的上游resolver块中指定该指令 。

service=name

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

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

server backend.example.com service=http resolve;

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

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

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

slow_start=time

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

该参数不能与哈希、随机负载均衡方法 一起使用 。

如果组中只有一台服务器，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

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

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

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

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

hash $remote_addr;

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

如果consistent指定了该参数， 则将使用ketama一致性哈希方法。该方法确保当服务器添加到组或从组中删除时，只有少数密钥将被重新映射到不同的服务器。这有助于缓存服务器实现更高的缓存命中率。该方法兼容 Cache::Memcached::Fast Perl库，参数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参数允许 收集 指定 中请求和响应的 DNS 服务器统计信息zone。

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

resolver_timeout 30s;

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

resolver_timeout 5s;

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

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

$upstream_addr

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