ngx_http_upstream_module模块.md

ngx_http_upstream_module

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

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，一个请求到每个第二和第三个服务器。如果在与服务器通信期间发生错误，请求将传递到下一个服务器，依此类推，直到所有正在运行的服务器都将被尝试。如果无法从任何服务器获得成功的响应，则客户端将接收与最后一个服务器的通信结果。

server

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

定义服务器的地址和其他参数。可以将地址指定为域名或IP地址，具有可选端口或作为在“unix：”前缀后指定的UNIX域套接字路径。如果未指定端口，则使用端口80。解析为多个IP地址的域名会一次定义多个服务器。

可以定义以下参数：

weight=number

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

max_conns=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

sets:

与服务器通信的指定次数的失败尝试发生在考虑服务器不可用的时间;
以及服务器将被视为不可用的时间段。

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

backup

将服务器标记为备份服务器。当主服务器不可用时，将传递请求。

down

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

zone

Syntax: zone name [size];
Default:    —
Context:    upstream
This directive appeared in version 1.9.0.

定义共享内存区域的名称和大小，以保持在工作进程之间共享的组的配置和运行时状态。几个组可以共享相同的区域。在这种情况下，只需指定一次大小即可。

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

state

Syntax: state file;
Default:    —
Context:    upstream
This directive appeared in version 1.9.7.

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

例子：

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

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

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

hash

Syntax: hash key [consistent];
Default:    —
Context:    upstream
This directive appeared in version 1.7.2.

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

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

ip_hash

Syntax: ip_hash;
Default:    —
Context:    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负载平衡方法为服务器指定权重。

keepalive

Syntax: keepalive connections;
Default:    —
Context:    upstream
This directive appeared in version 1.1.4.

激活与上游服务器的连接的缓存。

connections参数设置保存在每个工作进程的缓存中的上游服务器的空闲keepalive连接的最大数量。当超过此数量时，最近使用的最少连接将关闭。

应该特别注意的是，keepalive伪指令不限制nginx工作进程可以打开的到上游服务器的连接的总数。连接参数应设置为足够小，以允许上游服务器处理新的传入连接。
memcached上游和keepalive连接的示例配置：

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

当使用除默认循环方法之外的负载平衡器方法时，有必要在keepalive伪指令之前激活它们。
SCGI和uwsgi协议没有keepalive连接的概念。

ntlm

Syntax: ntlm;
Default:    —
Context:    upstream
This directive appeared in version 1.9.2.

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

为了使NTLM身份验证工作，需要启用与上游服务器的keepalive连接。 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指令之前激活它们。
此指令可作为我们商业订阅的一部分。

least_conn

Syntax: least_conn;
Default:    —
Context:    upstream
This directive appeared in versions 1.3.1 and 1.2.2.

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

least_time

Syntax: least_time header | last_byte;
Default:    —
Context:    upstream
This directive appeared in version 1.7.10.

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

如果指定了header参数，则使用接收响应头的时间。如果指定了last_byte参数，则使用接收完整响应的时间。

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

health_check

Syntax: health_check [parameters];
Default:    —
Context:    location

启用周围位置中引用的组中的服务器的定期运行状况检查。
此指令可作为我们商业订阅的一部分。

match

Syntax: match name { ... }
Default:    —
Context:    http

定义用于验证对健康检查请求的响应的命名测试集。
此指令可作为我们商业订阅的一部分。

queue

Syntax: queue number [timeout=time];
Default:    —
Context:    upstream
This directive appeared in version 1.5.12.

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

超时参数的默认值为60秒。