ngx_http_upstream_module

upstream

Syntax:	upstream name { ... }
Default:	—
Context:	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，另2个请求分别转发给第二个和第三个服务器。如果在与服务器通信期间发生错误，请求将被传递到下一个服务器，依此类推，直到尝试完所有正常运行的服务器。如果无法从任何服务器获得成功的响应，则客户端将接收到与最后一个服务器的通信结果。

server

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

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

可以定义以下参数：

• weight=number: 设置服务器的权重，默认为1。

• max_conns=number: 限制与代理服务器的最大并发活动连接数（1.11.5）。默认值为零，表示没有限制。如果服务器组不驻留在共享内存中，则每个工作进程的限制都有效。

  如果启用了空闲keepalive连接，多个工作进程和共享内存，则代理服务器的活动和空闲连接总数可能会超过max_conns值。

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

• max_fails=number: 设置应在fail_timeout参数设置的持续时间内发生与服务器通信失败尝试的次数，以考虑服务器在fail_timeout参数设置的持续时间内不可用。即在fail_timeout参数定义的时间段内，如果失败的次数达到此值，nginx就认为服务器不可用。在下一个fail_timeout时间段，服务器不会再被尝试。失败的尝试次数默认为1。设为0就会停止统计尝试次数，并认为服务器是一直可用的。你可以通过proxy_next_upstream、fastcgi_next_upstream、uwsgi_next_upstream、scgi_next_upstream、memcached_next_upstream和grpc_next_upstream指令定义什么是失败的尝试。

• fail_timeout=time:

  • 统计失败尝试次数的时间段。在这段时间中，服务器失败次数达到指定的尝试次数，服务器就被认为不可用。
  • 服务器被认为不可用的时间段。

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

• backup: 将服务器标记为备份服务器。当主服务器不可用时，请求会被传递给这些服务器。

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

zone

Syntax:	zone name [size];
Default:	—
Context:	upstream
该指令出现在1.9.0版本中。

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

state

Syntax:	state file;
Default:	—
Context:	upstream
该指令出现在1.9.7版本中。

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

样例：

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

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

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

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

hash

Syntax:	hash key [consistent];
Default:	—
Context:	upstream
该指令出现在1.7.2版本中。

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

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

ip_hash

Syntax:	ip_hash;
Default:	—
Context:	upstream

指定服务器组的负载均衡方法，其中请求基于客户端IP地址在服务器之间分发。客户端IPv4地址的前三个八位字节或整个IPv6地址用作散列键。该方法确保来自同一客户端的请求将始终传递到同一服务器，除非此服务器不可用。在后一种情况下，客户端请求将被传递到另一个服务器，而且很有可能的是，它也将始终是同一台服务器。可以解决session和cookie的问题，但会导致负载不均衡。

从版本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负载均衡方法为服务器指定权重。

nginx-sticky-module: nginx的一个扩展模块，实现了通过Cookie的会话粘贴效果。

基本原理：客户端首次发起访问请求时，首先根据round-robin随机轮询到某台后端服务器，然后在响应的Set-Cookie上加上“route=md5(upstream)”字段（可能是明文，也可能是md5、sha1等Hash值），第二次请求再处理的时候，发现有route字段，会直接导向原来的那个节点。

keepalive

Syntax:	keepalive connections;
Default:	—
Context:	upstream
该指令出现在1.1.4版本中。

激活对上游服务器的连接进行缓存。

connections参数设置在每个工作进程的缓存中保留的上游服务器的最大空闲keepalive连接数。如果连接数大于这个值时，将关闭最近最少使用的连接。

需要特别注意的是，keepalive指令不限制nginx工作进程可以打开的上游服务器的连接总数。connections参数应该设置的足够小，以便上游服务器也能处理新进来的连接。

使用keepalive连接的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”，并且应清除“Connection”头字段：

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

或者，可以通过将“Connection：Keep-Alive”头字段传递给上游服务器来使用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;
        ...
    }
}

使用除默认round-robin方法之外的负载平衡器方法时，必须在keepalive指令之前激活它们。

SCGI和uwsgi协议没有keepalive连接的概念。

keepalive_requests

Syntax:	keepalive_requests number;
Default:	
keepalive_requests 100;
Context:	upstream
该指令出现在1.15.3版本中。

设置可通过一个keepalive连接提供的最大请求数。在发出最大请求数后，将关闭连接。

keepalive_timeout

Syntax:	keepalive_timeout timeout;
Default:	
keepalive_timeout 60s;
Context:	upstream
该指令出现在1.15.3版本中。

设置超时，在此期间与上游服务器的空闲keepalive连接将保持打开状态。

least_conn

Syntax:	least_conn;
Default:	—
Context:	upstream
该指令出现在1.3.1和1.2.2版本中。

指定服务器组的负载均衡方法，其中请求会被转发到活动连接数最少的服务器上，同时考虑服务器的权重。如果有多个这样的服务器（活动连接数同为最小），则使用加权轮询方法依次尝试它们。

least_time

Syntax:	least_time header | last_byte [inflight];
Default:	—
Context:	upstream
该指令出现在1.7.10版本中。

指定服务器组的负载均衡方法，其中请求会被转发到平均响应时间最小和活动连接数最少的服务器上，同时考虑服务器的权重。如果有多个这样的服务器，则使用加权轮询方法依次尝试它们。

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

在1.11.6版之前，默认情况下会考虑未完成的请求。

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

queue

Syntax:	queue number [timeout=time];
Default:	—
Context:	upstream
该指令出现在1.5.12版本中。

如果在处理请求时无法立即选择上游服务器，则请求将被置于队列中。该指令指定了可以同时在队列中的最大请求数number。如果队列已满，或者在timeout参数中指定的时间段内无法选择要传递请求的服务器，则会返回502 (Bad Gateway)错误给客户端。

timeout参数的默认值为60秒。

使用除默认round-robin方法之外的负载平衡器方法时，必须在queue指令之前激活它们。

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

random

Syntax:	random [two [method]];
Default:	—
Context:	upstream
该指令出现在1.15.1版本中。

指定服务器组的负载均衡方法，其中请求将传递给随机选择的服务器，同时考虑服务器的权重。

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

least_time方法将请求传递给平均响应时间最短且活动连接数最少的服务器。如果指定了least_time=header，则使用接收响应头的时间。如果指定了least_time=last_byte，则使用接收完整响应的时间。