ngx_http_upstream_module

Module ngx_http_upstream_module

示例配置

指令

服务器

哈希

ip_hash

保持进行状态

ntlm

least_conn

least_time

队列

sticky

sticky_cookie_insert

嵌入式变量

该ngx_http_upstream_module模块用于定义可由proxy_pass，fastcgi_pass，uwsgi_pass，scgi_pass和memcached_pass指令引用的服务器组。

示例配置

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

具有定期健康检查的动态可配置组可作为我们商业订阅的一部分：

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;
    server backend3.example.com      resolve;
    server backend4.example.com      service=http resolve;

    server backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

指令

句法：	上游名称{...}
默认：	—
语境：	HTTP

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

例：

upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;

    server backup1.example.com  backup;
}

默认情况下，使用加权轮询平衡方法在服务器之间分配请求。在上面的例子中，每7个请求将分配如下：5个请求转到backend1.example.com一个请求并且对每个第二和第三个服务器发出一个请求。如果在与服务器进行通信期间发生错误，则该请求将被传递到下一个服务器，并依此类推，直到所有正在运行的服务器都将被尝试。如果无法从任何服务器获得成功响应，则客户端将收到与最后一个服务器通信的结果。

句法：	服务器地址参数;
默认：	—
语境：	upstream

定义服务器address和其他parameters服务器。该地址可以指定为域名或IP地址，可选端口或指定为“ unix:”前缀之后指定的UNIX域套接字路径。如果未指定端口，则使用端口80。解析为多个IP地址的域名一次定义多个服务器。

以下参数可以定义：

weight= number设置服务器的权重，默认情况下为1. max_conns= number限制number到代理服务器的同时活动连接的最大数量（1.11.5）。默认值为零，这意味着没有限制。如果服务器组不驻留在共享内存中，则每个工作进程都有限制。

如果空闲保持连接，多个工作者和共享内存被启用，则与代理服务器的活动连接和空闲连接的总数可能会超过该max_conns值。自1.5.9版本以及1.11.5版本之前，此参数作为我们商业订阅的一部分提供。

max_fails= number设置在fail_timeout参数设置的持续时间内应该发生的与服务器通信失败的次数，以便在参数设置的持续时间内将服务器视为不可用fail_timeout。默认情况下，不成功尝试的次数设置为1.零值将禁用尝试的计费。proxy_next_upstream，fastcgi_next_upstream，uwsgi_next_upstream，scgi_next_upstream和memcached_next_upstream指令定义了什么被认为是不成功的尝试。fail_timeout= time集合

指定数量的尝试与服务器通信失败的时间应该发生在考虑服务器不可用的时间内;

以及服务器将被视为不可用的时间段。

默认情况下，该参数设置为10秒。backup将服务器标记为备份服务器。它将在主服务器不可用时传递请求。down将服务器标记为永久不可用。

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

resolve监视与服务器的域名相对应的IP地址的变化，并自动修改上游配置而不需要重新启动nginx（1.5.12）。服务器组必须驻留在共享内存中。

为了使这个参数起作用，必须在http块中指定解析器指令。例：

http {
    resolver 10.0.0.1;

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

route= string设置服务器路由名称。service= name启用解析DNS SRV记录并设置服务name（1.9.13）。为了使此参数起作用，有必要指定服务器的解析参数并指定一个不带端口号的主机名。

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

服务器backend.example.com服务= http解析;

如果服务名称包含一个或多个点，则通过加入服务前缀和服务器名称来构造名称。例如，要查找_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服务器将其重量从零恢复到正常值的时间，当不健康的服务器变得健康时，或者服务器在一段时间后变得可用时认为不可用。默认值为零，即慢启动被禁用。

该参数不能与hash和ip_hash负载平衡方法一起使用。如果组中只有一台服务器max_fails，fail_timeout并且slow_start参数被忽略，并且这样的服务器永远不会被视为不可用。

句法：	区域名称大小;
默认：	—
语境：	upstream

定义name和size其保持组的配置和运行时被工作者进程之间共享状态中的共享存储器区。几个小组可能共享相同的区域。在这种情况下，size仅指定一次就足够了。

此外，作为我们的商业订阅的一部分，此类组允许更改组成员身份或修改特定服务器的设置，而无需重新启动nginx。配置可以通过upstream_conf处理的特殊位置访问。

句法：	状态文件;
默认：	—
语境：	upstream

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

例子：

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

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

配置重新加载或二进制升级期间所做的更改可能会丢失。该指令可作为我们商业订阅的一部分。

句法：	散列键一致;
默认：	—
语境：	upstream

指定客户端 - 服务器映射基于哈希key值的服务器组的负载平衡方法。该key可以包含文本，变量，以及它们的组合。请注意，从组中添加或删除服务器可能导致将大多数密钥重新映射到不同的服务器。该方法与Cache :: Memcached Perl库兼容。

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

句法：	ip_hash;
默认：	—
语境：	upstream

指定组应使用负载平衡方法，其中根据客户端IP地址在服务器之间分配请求。客户端IPv4地址的前三个八位字节或整个IPv6地址用作散列密钥。该方法确保来自同一客户端的请求将始终传递到同一服务器，除非该服务器不可用。在后一种情况下，客户端请求将传递给另一台服务器。最有可能的是，它将始终是同一台服务器。

从版本1.3.2和1.2.2开始支持IPv6地址。

如果需要暂时删除其中一台服务器，则应该使用该down参数进行标记，以便保留客户端IP地址的当前散列。

例：

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

在版本1.3.1和1.2.2之前，无法为使用ip_hash负载平衡方法的服务器指定权重。

句法：	保持连接;
默认：	—
语境：	上游

激活缓存以连接到上游服务器。

该connections参数设置保留在每个辅助进程缓存中的上游服务器的空闲保持连接的最大数量。当这个数字被超过时，最近最少使用的连接被关闭。

应特别注意的是，该keepalive指令不限制nginx工作进程可以打开的上游服务器的连接总数。该connections参数应设置为足以让上游服务器处理新传入连接的数字。

具有保持连接的Memcached上游示例配置：

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

对于HTTP，应将proxy_http_version指令设置为“ 1.1”，并且应清除“连接”标题字段：

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

或者，可以通过将“连接：保持活动”标题字段传递给上游服务器来使用HTTP / 1.0持久连接，尽管不建议使用此方法。

对于FastCGI服务器，需要设置fastcgi_keep_conn以使Keepalive连接正常工作：

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

使用默认循环方法以外的负载均衡器方法时，需要在keepalive指令之前激活它们。SCGI和uwsgi协议没有保持连接的概念。

句法：	NTLM;
默认：	—
语境：	upstream

允许使用NTLM身份验证进行代理请求。一旦客户端发送具有以“ Negotiate”或“ NTLM” 开头的“授权”报头字段值的请求，上游连接就绑定到客户端连接。进一步的客户端请求将通过相同的上游连接进行代理，保持认证上下文。

为了使NTLM身份验证正常工作，有必要启用与上游服务器的保持连接。proxy_http_version指令应设置为“ 1.1”，并且应清除“连接”标题字段：

upstream http_backend {
    server 127.0.0.1:8080;

    ntlm;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

使用默认循环方法以外的负载均衡器方法时，需要在ntlm指令之前激活它们。该指令可作为我们商业订阅的一部分。

Syntax:	least_conn;
Default:	—
Context:	upstream

Specifies that a group should use a load balancing method where a request is passed to the server with the least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.

句法：	least_time标题\| last_byte机上;
默认：	—
语境：	upstream

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

如果header指定了参数，则使用接收响应头的时间。如果last_byte指定了参数，则使用接收完整响应的时间。如果inflight指定参数（1.11.6），则不完整请求也会被考虑。

在版本1.11.6之前，默认情况下会考虑不完整的请求。该指令可作为我们商业订阅的一部分。

句法：	队列号超时=时间;
默认：	—
语境：	upstream

如果在处理请求时不能立即选择上游服务器，请求将被放入队列中。该指令指定number可以同时在队列中的请求的最大数量。如果队列已满，或者服务器传递请求在timeout参数中指定的时间段内无法选择，则502（错误网关）错误将返回给客户端。

该timeout参数的默认值是60秒。

使用默认循环方法以外的负载均衡器方法时，需要在queue指令之前激活它们。该指令可作为我们商业订阅的一部分。

句法：	sticky cookie name expires = time httponly path = path; sticky route $ variable ...; sticky learn create = $ variable lookup = $ variable zone = name：size timeout = time;
默认：	—
语境：	upstream

启用会话亲缘关系，这会导致来自同一个客户端的请求被传递到一组服务器中的同一台服务器。有三种方法可用：

cookie

使用该cookie方法时，有关指定服务器的信息将在由nginx生成的HTTP cookie中传递：

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

来自尚未绑定到特定服务器的客户端的请求被传递到由配置的均衡方法选择的服务器。有了这个cookie的更多请求将被传递给指定的服务器。如果指定的服务器无法处理请求，则选择新的服务器，就好像客户尚未绑定一样。

第一个参数设置要设置或检查的cookie的名称。Cookie值是IP地址和端口的MD5散列值或UNIX域套接字路径的十六进制表示形式。但是，如果route指定了服务器伪指令的“ ”参数，则cookie值将是“ route”参数的值：

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

在这种情况下，“ srv_id”cookie 的值将是a或者b。

其他参数可能如下所示：

expires=time设置time浏览器应该保存cookie的信息。特殊值max会导致cookie在“ 31 Dec 2037 23:55:55 GMT” 上过期。如果未指定参数，则会导致Cookie在浏览器会话结束时过期。domain=domain定义domaincookie的设置。参数值可以包含变量（1.11.5）。httponly将该HttpOnly属性添加到Cookie（1.7.11）。secure将该Secure属性添加到Cookie（1.7.11）。path=path定义pathcookie的设置。

如果省略任何参数，则不设置相应的cookie字段。

route

使用该route方法时，代理服务器会在接收到第一个请求时为客户端分配路由。此客户端的所有后续请求都会将路由信息携带在Cookie或URI中。将此信息与route服务器伪指令的“ ”参数进行比较，以识别请求应该代理到的服务器。如果route未指定“ ”参数，则路由名称将是IP地址和端口的MD5散列值或UNIX域套接字路径的十六进制表示形式。如果指定的服务器无法处理请求，则通过配置的平衡方法选择新服务器，就好像请求中没有路由信息一样。

该route方法的参数指定了可能包含路由信息的变量。第一个非空变量用于查找匹配的服务器。

例：

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P<route>\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P<route>\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

在这里，如果路由是JSESSIONID在请求中出现的，则从“ ”cookie中取出。否则，使用来自URI的路由。

learn

当使用learn方法（1.7.1）时，nginx会分析上游服务器响应并学习服务器启动的会话通常通过HTTP cookie传递。

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

在该示例中，上游服务器通过EXAMPLECOOKIE在响应中设置cookie“ ”来创建会话。有了这个cookie的更多请求将被传递给同一台服务器。如果服务器无法处理请求，则选择新的服务器，就好像客户端尚未绑定一样。

这些参数create和lookup指定变量分别指示如何创建新会话以及如何搜索现有会话。两个参数都可以多次指定，在这种情况下，将使用第一个非空变量。

会话存储在一个共享内存区域中，其中name和size由zone参数配置。一个兆字节的区域可以在64位平台上存储大约8000个会话。在timeout参数指定的时间内未访问的会话将从区域中删除。默认情况下，timeout设置为10分钟。

的header参数（1.13.1）允许正确的从上游服务器接收响应标头之后创建会话。

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

句法：	sticky_cookie_insert name expires = time path = path;
默认：	—
语境：	upstream

该指令自1.5.7版本开始已过时。应该使用具有新语法的等效粘性指令代替：

sticky cookie name expires=time path=path;

嵌入式变量

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

$upstream_addr保留IP地址和端口或上游服务器的UNIX域套接字的路径。如果在请求处理过程中联系了多个服务器，则它们的地址用逗号分隔，例如“ 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”。如果从“X-Accel-Redirect”或error_page发起从一个服务器组到另一个服务器组的内部重定向，则来自不同组的服务器地址由冒号分隔，例如“ 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”。如果无法选择服务器，则该变量将保留服务器组的名称。$upstream_bytes_received从上游服务器收到的字节数（1.11.4）。来自多个连接的值由逗号和冒号分隔，如$ upstream_addr变量中的地址。$upstream_cache_status保持访问响应缓存的状态（0.8.3）。状态可以是“ MISS”，“ BYPASS”，“ EXPIRED”，“”STALE“，” UPDATING“，” REVALIDATED“或” HIT“。$upstream_connect_time保持与上游服务器建立连接的时间（1.9.1）; 时间以毫秒分辨率保持在几秒钟内。在SSL的情况下，包括花在握手上的时间。几个连接的时间由逗号和冒号分隔，如$ upstream_addr变量中的地址。$upstream_cookie_namecookie name由上游服务器在“Set-Cookie”响应头域（1.7.1）中发送的指定。只保存最后一台服务器的响应中的cookie。$upstream_header_time保持从上游服务器接收响应头的时间（1.7.10）; 时间以毫秒分辨率保持在几秒钟内。几个响应的时间由逗号和冒号分隔，如$ upstream_addr变量中的地址。$upstream_http_name保留服务器响应头字段。例如，“服务器”响应标题字段可通过$upstream_http_server变量获得。将头字段名称转换为变量名称的规则与以“$ http_”前缀开头的变量相同。只保存最后一台服务器响应中的标题字段。$upstream_response_length保留从上游服务器获得的响应的长度（0.7.27）; 长度保持字节。几个响应的长度由逗号和冒号分隔，如$ upstream_addr变量中的地址。$upstream_response_time保持花费在接收来自上游服务器的响应上的时间; 时间以毫秒分辨率保持在几秒钟内。几个响应的时间由逗号和冒号分隔，如$ upstream_addr变量中的地址。$upstream_status保留从上游服务器获得的响应的状态码。几个响应的状态码由逗号和冒号分隔，如$ upstream_addr变量中的地址。如果无法选择服务器，则该变量将保留502（错误网关）状态码。