Module ngx_stream_upstream_module

• Example Configuration
• Directives
  • upstream
  • server
  • zone
  • state
  • hash
  • least_conn
  • least_time
  • random
  • resolver
  • resolver_timeout
• Embedded Variables
  

ngx_stream_upstream_module模块(1.9.0)用于定义可由proxy_pass指令引用的服务器组。

Example Configuration

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;
}

周期性health checks的动态可配置组可作为我们commercial subscription的一部分使用：

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;
}

Directives

Syntax:	upstream name { ... }
Default:	—
Context:	stream

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

Example:

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

Syntax:	server address [parameters];
Default:	—
Context:	upstream

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

可以定义以下参数：

weight= number

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

max_conns= number

• 限制到代理服务器的同时连接的最大number(1.11.5)。默认值为零，表示没有限制。如果服务器组不在shared memory中，则此限制在每个工作进程中均有效。

max_fails= number

• 设置在fail_timeout参数设置的持续时间内应与服务器通信失败的尝试次数，以认为服务器在fail_timeout参数设置的持续时间内不可用。默认情况下，未成功尝试的次数设置为 1.零值将禁用对尝试的记帐。在这里，不成功的尝试是与服务器构建连接时出现错误或超时。

fail_timeout= time

• sets

• 在指定次数的不成功尝试与服务器通信的时间范围内，应考虑服务器不可用；

• 以及服务器将不可用的时间段。

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

backup

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

down

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

此外，以下参数是我们的commercial subscription的一部分：

resolve

• 监视与服务器域名对应的 IP 地址的更改，并自动修改上游配置，而无需重新启动 nginx。服务器组必须位于shared memory中。

为了使该参数起作用，必须在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，当不正常的服务器变为healthy或在一段时间后服务器变为unavailable可用时，服务器会将其重量从零恢复到标称值。默认值为零，即禁用慢速启动。

Syntax:	zone name [size];
Default:	—
Context:	upstream

定义共享内存区域的name和size，该区域保留工作进程之间共享的组的配置和运行时状态。几个组可以共享同一区域。在这种情况下，仅指定一次size就足够了。

另外，作为commercial subscription的一部分，此类组允许更改组成员身份或修改特定服务器的设置，而无需重新启动 nginx。可通过API模块(1.13.3)访问该配置。

Syntax:	state file;
Default:	—
Context:	upstream

该指令出现在 1.9.7 版中。

指定一个file，以保留动态可配置组的状态。

Examples:

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

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

Syntax:	hash key [consistent];
Default:	—
Context:	upstream

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

hash $remote_addr;

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

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

Syntax:	least_conn;
Default:	—
Context:	upstream

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

Syntax:	least_time connect | first_byte | last_byte [inflight];
Default:	—
Context:	upstream

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

如果指定了connect参数，则使用到上游服务器connect的时间。如果指定了first_byte参数，则使用接收first byte数据的时间。如果指定了last_byte，则使用接收last byte数据的时间。如果指定了inflight参数(1.11.6)，则还将考虑不完整的连接。

Syntax:	random [two [method]];
Default:	—
Context:	upstream

该指令出现在 1.15.1 版中。

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

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

least_time方法将连接以最少的平均时间和最少的活动连接数传递给服务器。如果指定了least_time=connect参数，则使用到上游服务器connect的时间。如果指定了least_time=first_byte参数，则使用接收first byte数据的时间。如果指定least_time=last_byte，则使用接收last byte数据的时间。

Syntax:	resolver address ... [valid=time] [ipv6=on|off] [status_zone=zone];
Default:	—
Context:	upstream

该指令出现在 1.17.5 版中。

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

resolver 127.0.0.1 [::1]:5353;

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

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

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

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

可选的status_zone参数启用zone中指定请求和响应的 DNS 服务器统计信息的collection。

Syntax:	resolver_timeout time;
Default:	resolver_timeout 30s;
Context:	upstream

该指令出现在 1.17.5 版中。

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

resolver_timeout 5s;

Embedded Variables

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