模块 ngx_http_upstream_module

模块 用于定义可引用的服务器组 通过 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 和 grpc_pass Directives。ngx_http_upstream_module

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

定义服务器的 and other。 地址可以指定为域名或 IP 地址， 带有可选端口，或作为 UNIX 域套接字路径 在 “” 前缀后指定。 如果未指定端口，则使用端口 80。 解析为多个 IP 地址的域名定义 一次多个服务器。addressparametersunix:

可以定义以下参数：

weight=number

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

max_conns=number

限制同时活动的最大数量 连接到代理服务器 （1.11.5）。 默认值为零，这意味着没有限制。 如果服务器组不驻留在共享内存中，则 该限制适用于每个 worker 进程。number

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

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

max_fails=number

设置与 服务器通信的失败尝试次数 这应该发生在参数设置的持续时间内，以将服务器视为在参数设置的持续时间内不可用。 默认情况下，失败尝试的次数设置为 1。 零值将禁用尝试的计数。 被视为不成功的尝试由 proxy_next_upstream、fastcgi_next_upstream、uwsgi_next_upstream、scgi_next_upstream、memcached_next_upstream 和 grpc_next_upstream Directives定义。fail_timeoutfail_timeout

fail_timeout=time

集

• 指定次数的失败尝试 与 server 通信时应恰好认为 server 不可用;
• 以及服务器将被视为不可用的时间段。

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

backup

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

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

down

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

resolve

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

为了使此参数起作用， Directives 必须在 HTTP 块中指定 或在相应的上游区块中。resolver

在版本 1.27.3 之前，此参数仅作为我们商业订阅的一部分提供。

service=name

启用 DNS SRV 记录的解析并设置服务 （1.9.13）。 为了使此参数正常工作，必须指定 服务器的 resolve 参数 并指定不带端口号的主机名。name

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

server backend.example.com service=http resolve;

如果服务名称包含一个或多个点，则构造名称 通过联接服务前缀和服务器名称。 例如，要查找 和 SRV 记录， 需要指定Directives：_http._tcp.backend.example.comserver1.backend.example.com

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

最高优先级的 SRV 记录 （具有相同 lowest-number 优先级值的记录） 解析为主服务器， 其余的 SRV 记录被解析为备份服务器。 如果为服务器指定了 backup 参数，则 高优先级 SRV 记录被解析为备份服务器， 其余的 SRV 记录将被忽略。

在版本 1.27.3 之前，此参数仅作为我们商业订阅的一部分提供。

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

route=string

设置服务器路由名称。

slow_start=time

设置服务器将恢复其权重的期间 从 0 到标称值，当运行状况不佳的服务器变为运行状况良好时， 或者当服务器在一段时间后变为可用时 它被认为不可用。 默认值为零，即禁用慢启动。time

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

drain

将服务器置于 “draining” 模式（1.13.6）。 在该模式下，仅绑定到服务器的请求 将被代理到它。

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

如果组中只有一个服务器，则 、 和 参数 被忽略，并且此类服务器永远不会被视为不可用。max_failsfail_timeoutslow_start

定义共享的 和 内存区域，该区域保持组的配置和运行时状态 在 worker 进程之间共享。 多个组可以共享同一区域。 在这种情况下，指定 only once 就足够了。namesizesize

此外 作为我们商业订阅的一部分， 此类组允许更改组成员资格 或修改特定服务器的设置 无需重新启动 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

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

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

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

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

如果指定了该参数，则 将改用 Ketama 一致性哈希方法。 该方法确保只有几个键 将重新映射到不同的服务器 在组中添加或删除服务器时。 这有助于为缓存服务器实现更高的缓存命中率。 该方法与参数设置为 160 的 Cache：：Memcached：：Fast Perl 库兼容。consistentketama_points

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

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

如果需要暂时删除其中一台服务器，则应将其 使用 以保留客户端 IP 地址的当前哈希值。down

例：

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

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

该参数设置最大数量的 与 upstream server 的空闲 keepalive 连接，这些连接保留在 每个工作进程的缓存。 超过此数量时，最近最少使用的连接数 已关闭。connections

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

当使用默认 round-robin 方法，则需要在之前激活它们 Directives。keepalive

具有 keepalive 连接的 memcached upstream 的示例配置：

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 Directives应设置为 “” 并且应清除 “Connection” 标头字段：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 "";
        ...
    }
}

或者，可以通过传递 “Connection： Keep-Alive” 标头字段连接到上游服务器， 尽管不建议使用此方法。

对于 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 连接处理请求。 达到此时间后，连接将关闭 在后续请求处理之后。

keepalive_timeout 60s;

设置空闲 keepalive 与上游服务器的连接将保持打开状态。

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

为了使 NTLM 身份验证正常工作， 必须启用与上游服务器的 keepalive 连接。 proxy_http_version Directives应设置为 “” 并且应清除 “Connection” 标头字段：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 "";
        ...
    }
}

当使用默认 round-robin 方法，则需要在之前激活它们 Directives。ntlm

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

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

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

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

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

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

无法立即选择上游服务器时 在处理请求时， 该请求将被放入队列中。 该Directives指定最大请求数 可以同时在队列中。 如果队列已满， 或者无法在 参数中指定的时间段 502 （Bad Gateway） 错误将返回给客户端。numbertimeout

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

当使用默认 round-robin 方法，则需要在之前激活它们 Directives。queue

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

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

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

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

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

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

resolver 127.0.0.1 [::1]:5353;

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

默认情况下，nginx 将在解析时查找 IPv4 和 IPv6 地址。 如果不需要查找 IPv4 或 IPv6 地址， （1.23.1） 或 可以指定该参数。ipv4=offipv6=off

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

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

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

可选参数 （1.17.5） 启用请求和响应的 DNS 服务器统计信息的收集 在指定的 . 该参数作为我们商业订阅的一部分提供。status_zonezone

从 1.17.5 版本到 1.27.3 版本之前， 该Directives仅作为我们商业订阅的一部分提供。

resolver_timeout 30s;

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

resolver_timeout 5s;

从 1.17.5 版本到 1.27.3 版本之前， 该Directives仅作为我们商业订阅的一部分提供。

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

cookie

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

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

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

来自尚未绑定到特定服务器的客户端的请求 将传递到由配置的 balancing 方法选择的服务器。 使用此 cookie 的进一步请求将传递到指定的服务器。 如果指定的服务器无法处理请求，则新服务器为 选中，就好像客户端尚未绑定一样。

由于负载平衡方法始终尝试均匀分配负载 考虑到已绑定的请求， 具有较高活动绑定请求的服务器 获取新的 unbound 请求的可能性较小。

第一个参数设置要设置或检查的 cookie 的名称。 cookie 值为 IP 地址和端口的 MD5 哈希值的十六进制表示形式， 或 UNIX 域套接字路径。 但是，如果指定了 server Directives的 “” 参数，则 cookie 值将为 “” 参数的值：routeroute

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_idab

其他参数可能如下所示：

expires=time

设置浏览器应为其保留 Cookie。 特殊值将导致 Cookie 过期 “”. 如果未指定该参数，则会导致 Cookie 过期 浏览器会话的结束。timemax31 Dec 2037 23:55:55 GMT

domain=domain

定义为其设置 Cookie 的 Cookie。 参数值可以包含变量 （1.11.5）。domain

httponly

将属性添加到 cookie （1.7.11）。HttpOnly

samesite=strict| | |laxnone$variable

将 （1.19.4） 属性添加到 cookie 替换为以下值之一：、、 或 using 变量 （1.23.3）。 在后一种情况下，如果变量值为空， 该属性不会添加到 Cookie 中， 如果该值解析为 、 或 、 将分配相应的值， 否则将分配该值。SameSiteStrictLaxNoneSameSiteStrictLaxNoneStrict

secure

将属性添加到 cookie （1.7.11）。Secure

path=path

定义为其设置 Cookie 的 Cookie。path

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

route

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

该方法的参数指定 可能包含路由信息。 第一个非空变量用于查找匹配的服务器。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;
}

此处，路由取自 “” Cookie 如果存在在请求中。 否则，将使用来自 URI 的路由。JSESSIONID

learn

当使用方法 （1.7.1） 时，nginx 分析上游服务器响应并学习服务器发起的会话 通常以 HTTP Cookie 的形式传递。learn

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

在此示例中，上游服务器通过设置 Cookie “” 在响应中。 使用此 Cookie 的进一步请求将传递到同一服务器。 如果服务器无法处理请求，则新服务器为 选中，就好像客户端尚未绑定一样。EXAMPLECOOKIE

参数和指定变量，用于指示新会话的创建和现有方式 分别搜索会话。 这两个参数都可以多次指定，在这种情况下，第一个 使用非空变量。createlookup

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

参数 （1.13.1） 允许创建会话 在收到来自上游服务器的响应标头之后。header

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

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

该Directives自 1.5.7 版本起已过时。 应该使用具有新语法的等效 sticky Directives：

sticky cookie name [expires=time] [domain=domain] [path=path];

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

$upstream_addr

保留 IP 地址和端口， 或上游服务器的 UNIX 域套接字的路径。 如果在请求处理期间联系了多个服务器， 它们的地址用逗号分隔，例如 “”. 如果发生从一个服务器组到另一个服务器组的internal重定向， 发起人 “X-Accel-Redirect” 或 error_page， 然后来自不同组的服务器地址用冒号分隔，例如 “”. 如果无法选择服务器， 该变量保留 Server 组的名称。192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock192.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）。 状态可以是 “”、 “”, “”, “”, “”, “” 或 “”。MISSBYPASSEXPIREDSTALEUPDATINGREVALIDATEDHIT

$upstream_connect_time

保留与上游服务器建立连接所花费的时间 （1.9.1）; 该时间以秒为单位，分辨率为毫秒。 如果是 SSL，则包括握手所花费的时间。 多次连接的时间 用逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_cookie_name

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

$upstream_header_time

保持时间 用于从上游服务器接收响应标头 （1.7.10）; 该时间以秒为单位，分辨率为毫秒。 多次响应的次数 用逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。

$upstream_http_name

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

$upstream_last_server_name

保留最后选择的上游服务器的名称 （1.25.3）; 允许通过 SNI 传递它：

proxy_ssl_server_name on;
proxy_ssl_name        $upstream_last_server_name;

此变量作为我们商业订阅的一部分提供。

$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 （Bad Gateway） 状态代码。

$upstream_trailer_name

保留响应末尾的字段 从上游服务器 （1.13.10） 获取。