模块 ngx_http_upstream_module

该ngx_http_upstream_module模块用于定义可由proxy_pass、 fastcgi_pass、 uwsgi_pass、 scgi_pass、 memcached_pa​​ss和 grpc_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;
    }
}

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

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

可以定义以下参数：

weight=number

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

max_conns=number

限制number到代理服务器的同时活动连接的最大数量 (1.11.5)。默认值为零，表示没有限制。如果服务器组不驻留在共享内存中，则该限制适用于每个工作进程。

如果启用了空闲keepalive连接、多个worker和共享内存，代理服务器的活动连接和空闲连接总数可能会超过该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和 grpc_next_upstream 指令 定义 。

fail_timeout=time

套

• 尝试与服务器通信失败达到指定次数的时间应视为服务器不可用；
• 以及服务器被视为不可用的时间段。

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

backup

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

该参数不能与hash、ip_hash和随机负载均衡方法 一起使用 。

down

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

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

resolve

监控服务器域名对应的IP地址变化，自动修改上游配置，无需重启nginx（1.5.12）。服务器组必须驻留在共享内存中。

为了使该参数起作用，必须在http块或相应的上游resolver块中指定该指令 。

route=string

设置服务器路由名称。

service=name

启用 DNS SRV记录 解析 并设置服务name(1.9.13)。为了使该参数起作用，需要指定服务器的 解析参数并指定不带端口号的主机名。

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

server backend.example.com service=http resolve;

如果服务名称包含一个或多个点，则该名称是通过连接服务前缀和服务器名称来构造的。例如，要查找_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和随机负载均衡方法 一起使用 。

drain

将服务器置于“耗尽”模式 (1.13.6)。在这种模式下，只有绑定到服务器的请求才会被代理到服务器。

在版本 1.13.6 之前，只能使用API模块 更改参数 。

如果组中只有一台服务器，max_fails、 fail_timeout和slow_start参数将被忽略，这样的服务器永远不会被视为不可用。

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

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

在版本 1.13.3 之前，只能通过upstream_conf 处理的特殊位置访问配置 。

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

例子：

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

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

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

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

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

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

指定组应使用负载平衡方法，其中请求根据客户端 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参数应设置为足够小的数字，以便上游服务器也可以处理新的传入连接。

当使用默认循环方法以外的负载平衡方法时，有必要在指令之前激活它们keepalive。

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

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

keepalive_requests 1000;

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

定期关闭连接对于释放每个连接的内存分配是必要的。因此，使用过高的最大请求数可能会导致内存使用过多，不建议这样做。

在 1.19.10 版本之前，默认值为 100。

keepalive_time 1h;

限制通过一个保活连接可以处理请求的最长时间。达到此时间后，连接将在后续请求处理后关闭。

keepalive_timeout 60s;

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

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

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

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。

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

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

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

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

在版本 1.11.6 之前，默认情况下会考虑不完整的请求。

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

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

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

当使用默认循环方法以外的负载平衡器方法时，有必要在指令之前激活它们queue。

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

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

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

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

该方法可作为我们商业订阅least_time的一部分提供 。

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

resolver 127.0.0.1 [::1]:5353;

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

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

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

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

为了防止 DNS 欺骗，建议在适当保护的受信任本地网络中配置 DNS 服务器。

可选status_zone参数允许 收集 指定 中请求和响应的 DNS 服务器统计信息zone。

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

resolver_timeout 30s;

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

resolver_timeout 5s;

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

启用会话亲和性，这会导致来自同一客户端的请求被传递到一组服务器中的同一服务器。可以使用三种方法：

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 地址和端口或 UNIX 域套接字路径的 MD5 哈希值的十六进制表示形式。但是，如果指定了服务器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=/;
}

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

附加参数可能如下：

expires=time

设置time浏览器应保留 cookie 的时间。特殊值max将导致 cookie 在“ 31 Dec 2037 23:55:55 GMT”到期。如果未指定该参数，将导致 cookie 在浏览器会话结束时过期。

domain=domain

定义domain设置 cookie 的对象。参数值可以包含变量(1.11.5)。

httponly

将HttpOnly属性添加到 cookie (1.7.11)。

samesite=strict| lax| none|$variable

SameSite使用以下值之一将 (1.19.4) 属性 添加到 cookie： Strict、 Lax、 None或使用变量 (1.23.3)。在后一种情况下，如果变量值为空，则该SameSite属性不会添加到cookie中，如果该值被解析为 Strict、 Lax、 或 None，则将分配相应的值，否则Strict将分配该值。

secure

将Secure属性添加到 cookie (1.7.11)。

path=path

定义path设置 cookie 的对象。

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

route

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

该方法的参数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，则从“ ” 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 位平台上，1 MB 区域可以存储大约 4000 个会话。在参数指定的时间内未访问的会话 timeout将从区域中删除。默认情况下，timeout设置为 10 分钟。

参数header(1.13.1) 允许在从上游服务器接收到响应标头后立即创建会话。

参数sync（1.13.8）启用 共享内存区域的 同步。

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

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

sticky cookie name [ expires=time] [ domain=domain] [ 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_bytes_sent

发送到上游服务器的字节数 (1.15.8)。来自多个连接的值由逗号和冒号分隔，就像 $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_name

namecookie ，由上游服务器在“Set-Cookie”响应头字段中 指定发送（1.7.1）。仅保存来自最后一个服务器响应的 cookie。

$upstream_header_time

记录从上游服务器接收响应头所花费的时间（1.7.10）；时间以秒为单位，精度为毫秒。多个响应的时间由逗号和冒号分隔，就像 $upstream_addr变量中的地址一样。

$upstream_http_name

保留服务器响应头字段。例如，“Server”响应头字段可通过$upstream_http_server变量获得。头字段名称转换为变量名称的规则与以“ $http_ ”前缀开头的变量相同。仅保存最后一个服务器响应的标头字段。

$upstream_queue_time

记录请求在上游队列中花费的时间 （1.13.9）；时间以秒为单位，精度为毫秒。多个响应的时间由逗号和冒号分隔，就像 $upstream_addr变量中的地址一样。

$upstream_response_length

保留从上游服务器获得的响应的长度（0.7.27）；长度以字节为单位保存。多个响应的长度由逗号和冒号分隔，就像 $upstream_addr变量中的地址一样。

$upstream_response_time

记录从上游服务器接收响应所花费的时间；时间以秒为单位，精度为毫秒。多个响应的时间由逗号和冒号分隔，就像 $upstream_addr变量中的地址一样。

$upstream_status

保存从上游服务器获得的响应的状态代码。多个响应的状态代码由逗号和冒号分隔，就像 $upstream_addr变量中的地址一样。如果无法选择服务器，该变量将保留 502（错误网关）状态代码。

$upstream_trailer_name

保留从上游服务器 (1.13.10) 获得的响应末尾的字段。