nginx中文文档-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;
}

upstream

语法:upstream name { … }
默认:—
上下文:stream

定义一个服务器组。服务器可以监听不同的端口。另外,服务器可以混合的监听TCP和UNIX-domain socket。
例子:

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,第二、第三个服务器各分配一个连接。如果在与服务器通信过程中发生了一个错误,连接将会传递给下一个服务器上,直到所有的服务器都尝试了。如果与所有服务器的通信都失败了,连接将被关闭。

server

语法:server address [parameters]
默认:—
上下文:upstream

定义地址和服务器的其他参数。地址可以定义为域名或IP地址和必须的端口号,或UNIX-domain socket路径指定在“unix:”前缀之后。域名解析成多个IP地址会一次定义多个服务器。
下面的参数可以被定义:
weight=number
设置服务器权重,默认是1。

max_fails=number
设置发生在由fail_timeout参数设置的期间与服务器通信不成功的尝试次数,这个次数会在由fail_timeout参数设置的期间认为是不可用的。默认情况下,不成功的尝试次数设置为1。零值禁用尝试计数。这里,一次不成功的尝试是在与服务器建立连接时发生错误或超时。

fail_timeout=time
设置

  • 一个时间,在这期间指定与服务器通信不成功的尝试次数会认为服务器不可用
  • 一个时间段,在此期间服务器会被认为不可用

默认情况下,该参数为10秒。

backup
标记服务器为备份服务器。当主服务器都不可用时,连接会被传递给备份服务器。

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

下面的参数在商业版本可用(商业版本不进行翻译):

max_conns=number
limits the maximum number of simultaneous connections to the proxied server. Default value is zero, meaning there is no limit.

resolve
monitors changes of the IP addresses that correspond to a domain name of the server, and automatically modifies the upstream configuration without the need of restarting nginx. The server group must reside in the shared memory.
In order for this parameter to work, the resolver directive must be specified in the stream block. Example:

stream {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com:12345 resolve;
    }
}

service=name
enables resolving of DNS SRV records and sets the service name (1.9.13). In order for this parameter to work, it is necessary to specify the resolve parameter for the server and specify a hostname without a port number.
If the service name does not contain a dot (“.”), then the RFC-compliant name is constructed and the TCP protocol is added to the service prefix. For example, to look up the _http._tcp.backend.example.com SRV record, it is necessary to specify the directive:
server backend.example.com service=http resolve;
If the service name contains one or more dots, then the name is constructed by joining the service prefix and the server name. For example, to look up the _http._tcp.backend.example.com and server1.backend.example.com SRV records, it is necessary to specify the directives:
server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;
Highest-priority SRV records (records with the same lowest-number priority value) are resolved as primary servers, the rest of SRV records are resolved as backup servers. If the backup parameter is specified for the server, high-priority SRV records are resolved as backup servers, the rest of SRV records are ignored.

slow_start=time
sets the time during which the server will recover its weight from zero to a nominal value, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled.
If there is only a single server in a group, max_fails, fail_timeout and slow_start parameters are ignored, and such a server will never be considered unavailable.

zone

语法:zone name [size]
默认:—
上下文:upstream

定义用于保存组配置及运行时共享于工作进程的状态的共享内存区域名称和大小。多个组可以共享相同的区域。这种情况下,指定一次区域大小是足够的。
作为商业版本的一部分,这个组允许改变组成员或修改服务器设置而不用重启nginx。配置可以通过特殊的location由upstream_conf处理。

state

语法:state file
默认:—
上下文:upstream
版本:1.9.7+

指定一个文件用于保存动态配置的组的状态。状态目前限制于带参数的服务器列表。文件在解析配置时以及每次upstream 配置改变进行更新时会读取。直接改变文件的内容应该避免。指令不能同server指令一同使用。
在配置重载 或二进制文件升级过程中的改变可能会被丢失。
该指令在商业版本中可用。

hash

语法:hash key [consistent]
默认:—
上下文:upstream

为服务器组指定负载均衡方法:客户端-服务器映射基于哈希键值。目前,只支持的值是指定为$remote_addr的客户端远程地址。注意从组中添加或移除服务器会导致重映射关键字到不同的服务器。该方法与Perl库中的Cache::Memcached一致。
如果指定consistent参数,ketama一致性哈希方法会被使用。该方法确保在服务器从组中添加或删除时只有很少重映射到不同的服务器。这有助于缓存服务器的更高的缓存命中率。该方法与Perl库带ketama_points参数设置为160时的Cache::Memcached::Fast一致。

least_conn

语法:least_conn
默认:—
上下文:upstream

指定一个服务器组的负载均衡方法:连接会传递给最少活跃连接的服务器中,会考虑服务器权重。如果有多个这样的服务器,它们会通过使用带权重的轮询负载均衡方法轮流尝试。

least_time

语法:least_time connect | first_byte | last_byte
默认:—
上下文:upstream

指定一个组使用的负载均衡方法:连接将传递给平均时间最少和活跃连接最少的服务器上,会考虑服务器权重。如果由多个服务器满足,它们会通过带权重的负载均衡方法轮流尝试。
如果指定了connect参数,会使用连接到上游服务器的时间。如果first_byte参数指定,使用收到数据的第一个字节的时间。如果指定了last_byte,使用受到数据的最后一个字节的时间。
该指令在商业版本上可用。

health_check

语法:health_check [parameters]
默认:—
上下文:server

启用组中服务器的健康检查。
支持下面的参数:
interval=time
设置两次连续的健康检查时间间隔,默认是5秒。

fails=number
设置一个服务器连续的健康检查失败次数,在这之后服务器会被认为是不健康的,默认是1。

passes=number
设置一个服务器连续的健康检查通过次数,在这之后服务器会被认为是健康的,默认是1。

match=name
指定match块配置测试,该测试用于健康检查通过。默认,能够建立TCP连接就是通过。

port=number
定义用于连接服务器进行健康检查的端口(1.9.7+)。默认等于服务器的端口。

udp
指定使用UDP协议进行健康检查而不是默认的TCP协议(1.9.13+)。需要带send和expect参数的match块。
例如,

server {
    proxy_pass backend;
    health_check;
}

将每5秒钟检测backend组中的每个服务器能否建立TCP连接。当到服务器的连接不能建立时,健康检查失败,服务器会被认为是不健康的。客户端连接将不会传递给不健康的服务器。
健康检查也可以配置为检测服务器获取的数据。测试配置单独使用match指令和match参数中的引用。
服务器组必须在同一个共享内存中。
如果多个健康检查为同一个组定义,任何健康检查失败都会使相应的服务器视为不健康的。
该指令是商业版本中的一部分。

health_check_timeout

语法:health_check_timeout timeout
默认:health_check_timeout 5s
上下文:stream, server

覆盖健康检查的proxy_timeout值。
该指令是商业版的一部分。

match

语法:match name { … }
默认:—
上下文:stream

定义命名的测试,用于验证服务器响应的健康检查。
下面的参数可以配置:
send string;
向服务器发送字符串。

expect string | ~ regex;
一个从服务器获取的数据中需要匹配的字面字符串(1.9.12+)或正则表达式。正则表达式指定以“~*”开头(大小写不敏感匹配)或“~”开头(大小写敏感匹配)。send和expect参数都可以包含十六进制的字面量,前缀“\x”跟着两个16进制数字,例如“\x80”(1.9.12+)。
如果:

  • TCP连接成功建立
  • 如果指定了send参数的字符串,并发送了
  • 如果指定了字符串或正则表达式,从服务器收到的数据匹配字符串或expect参数的正则表达式
  • 时间没有超过health_check_timeout指令指定的值

健康检查通过。
示例:

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}

只有从服务器获取的第一个proxy_buffer_size字节的数据会被检查。
该指令为商业版本的一部分。