全栈攻城狮

Appearance

模块 ngx_http_upstream_module ​

提示

来自deepseek解释

这是 ngx_http_upstream_module 模块的官方文档中文翻译。

该模块用于定义一组上游（后端）服务器，这些服务器可以被 proxy_pass、fastcgi_pass 等指令所引用。Nginx 会根据配置的负载均衡算法，将客户端请求分发到这些服务器上。

介绍 ​

ngx_http_upstream_module 模块用于定义服务器组（server groups），这些服务器组可以被 proxy_pass、 fastcgi_pass、 uwsgi_pass、 scgi_pass、 memcached_pass 和 grpc_pass 等指令引用。

示例配置 ​

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

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

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

指令 ​

upstream ​

属性说明
语法upstream name { ... }
默认值—
上下文http

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

示例

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

默认情况下，请求使用加权轮询（weighted round-robin）方法在服务器之间进行分发。在上面的示例中，每 7 个请求会按如下方式分发：5 个请求发送到 backend1.example.com，其余两台服务器各收到一个请求。

如果在与服务器通信期间发生错误，请求将被传递给下一个服务器，依此类推，直到尝试完所有正常工作的服务器。如果无法从任何服务器获得成功响应，客户端将收到与最后一个服务器通信的结果。

server ​

属性说明
语法server address [parameters];
默认值—
上下文upstream

定义服务器的地址（address）和其他参数（parameters）。地址可以指定为域名或 IP 地址，并带上可选的端口，或者指定为以 unix: 前缀标识的 UNIX 域套接字路径。如果未指定端口，则使用 80 端口。如果域名解析到多个 IP 地址，则会一次性定义多个服务器。

可用参数 ​

  • weight=number
    • 设置服务器的权重，默认为 1。
  • max_conns=number
    • 限制到代理服务器的最大并发活动连接数（自 1.11.5 版本起）。默认值为 0，表示没有限制。
  • max_fails=number
    • 设置在由 fail_timeout 参数设定的时间内，与服务器通信的失败尝试次数达到多少时，服务器将被视为不可用。默认值为 1。0 值表示禁用对失败尝试的计数。
    • 失败尝试的定义由 proxy_next_upstream 等指令决定。
  • fail_timeout=time
    • 设定两个功能的时间范围：
      1. 用于累计 max_fails 次失败尝试的时间。
      2. 服务器被标记为不可用的持续时间。
  • backup
    • 将服务器标记为备份服务器。当主服务器都不可用时，请求才会被传递给它。
    • 该参数不能与 hash、ip_hash 和 random 负载均衡方法同时使用。
  • down
    • 将服务器标记为永久不可用。
  • resolve
    • 监控与服务器域名对应的 IP 地址的变化，并自动修改上游配置，无需重启 Nginx（自 1.5.12 版本起）。服务器组必须驻留在共享内存中。为使此参数生效，必须在 http 块或相应的 upstream 块中指定 resolver 指令。
  • service=name
    • 启用 DNS SRV 记录的解析，并设置服务名称（自 1.9.13 版本起）。
  • slow_start=time
    • 当不健康的服务器变为健康状态时，或者当服务器从不可用状态恢复后，其权重从 0 恢复到正常值所需的时间（商业订阅功能）。默认值为 0，表示禁用慢启动。
  • drain
    • 将服务器置于“排空”（draining）模式（自 1.13.6 版本起）。在此模式下，只有绑定到该服务器的请求才会被代理给它（商业订阅功能）。

zone ​

属性说明
语法zone name [size];
默认值—
上下文upstream
版本自 1.9.0 版本起

定义共享内存区域的名称（name）和大小（size）。该区域用于在工作进程之间共享组的配置和运行时状态。多个组可以共享同一个区域。作为商业订阅的一部分，此类组允许在不重启 Nginx 的情况下更改组成员或修改特定服务器的设置。

state ​

属性说明
语法state file;
默认值—
上下文upstream
版本自 1.9.7 版本起

指定一个文件来保存动态可配置组的状态（商业订阅功能）。

hash ​

属性说明
语法hash key [consistent];
默认值—
上下文upstream
版本自 1.7.2 版本起

为服务器组指定一种负载均衡方法，其中客户端-服务器的映射关系基于哈希的 key 值。key 可以包含文本、变量及其组合。如果指定了 consistent 参数，则使用 ketama 一致性哈希算法。

ip_hash ​

属性说明
语法ip_hash;
默认值—
上下文upstream

指定一个负载均衡方法，使得请求基于客户端 IP 地址的哈希值在服务器之间进行分发。IPv4 地址使用前三个八位字节，IPv6 地址使用整个地址。该方法可以保证来自同一客户端的请求始终传递到同一台服务器，除非该服务器不可用。

least_conn ​

属性说明
语法least_conn;
默认值—
上下文upstream

指定一个负载均衡方法，其中请求会传递给当前活动连接数最少的服务器，并会考虑服务器的权重。

keepalive ​

属性说明
语法keepalive connections;
默认值—
上下文upstream

为上游服务器启用长连接（keepalive），设置每个工作进程与上游服务器之间缓存的最大空闲长连接数。当超过此数量时，最久未使用的连接将被关闭。

keepalive_requests ​

属性说明
语法keepalive_requests number;
默认值keepalive_requests 1000;
上下文upstream
版本自 1.15.3 版本起

设置通过一条 keepalive 连接可以处理的最大请求数。达到最大请求数后，连接将被关闭。

keepalive_time ​

属性说明
语法keepalive_time time;
默认值keepalive_time 1h;
上下文upstream
版本自 1.19.10 版本起

限制通过一条 keepalive 连接处理请求的最大时长。达到该时间后，连接将在处理完后续请求后关闭。

keepalive_timeout ​

属性说明
语法keepalive_timeout timeout;
默认值keepalive_timeout 60s;
上下文upstream
版本自 1.15.3 版本起

设置空闲的 keepalive 连接保持打开状态的超时时间。

ntlm ​

属性说明
语法ntlm;
默认值—
上下文upstream

允许代理使用 NTLM 认证的请求（商业订阅功能）。

random ​

属性说明
语法random [two [method]];
默认值—
上下文upstream

指定一个负载均衡方法，其中请求会被随机传递给服务器。可选的 two 参数指示 Nginx 先随机选择两台服务器，再根据指定的 method 选择其中一台。method 默认为 least_conn。

sticky ​

属性说明
语法sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=...] [secure] [path=path];
sticky route $variable ...;
sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
默认值—
上下文upstream

启用会话亲和性（session affinity），确保来自同一客户端的请求被传递到同一台服务器（商业订阅功能）。

该指令提供了三种实现方法：

  • cookie：Nginx 通过一个 HTTP Cookie 将会话信息传递给客户端，后续请求根据 Cookie 值路由到指定的服务器。
  • route：代理服务器在收到第一个请求时，会为客户端分配一个“路由”（route）。Nginx 后续会使用客户端请求中附带的 route 信息来决定将请求转发给哪个上游服务器。
  • learn：Nginx 通过分析服务器响应中的 session 信息来“学习”并维护客户端与服务器之间的映射关系。

其他指令摘要 ​

指令说明
least_time header | last_byte [inflight];选择平均响应时间最短或处理请求时间最短的服务器。
queue number [timeout=time];当没有可用的上游服务器时，允许将请求放入队列中处理。
resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];配置用于解析上游服务器域名的 DNS 服务器。
resolver_timeout time;为域名解析设置超时时间。
upstream_conf通过一个特殊的 location 来访问和管理上游配置。

内置变量 ​

ngx_http_upstream_module 模块提供了一系列内置变量，用于记录与上游服务器通信的详细信息：

  • $upstream_addr：保存上游服务器的 IP 地址和端口，或 UNIX 域套接字的路径。如果请求被重试，多个地址会以逗号或冒号分隔。
  • $upstream_cache_status：保存访问响应缓存的状态，例如 MISS、HIT、EXPIRED 等。
  • $upstream_connect_time：保存与上游服务器建立连接所花费的时间。
  • $upstream_header_time：保存从上游服务器接收响应头所花费的时间。
  • $upstream_response_time：保存从上游服务器接收完整响应所花费的时间。
  • $upstream_http_ name：保存上游服务器返回的响应头字段。例如，$upstream_http_server 变量保存“Server”响应头的值。
  • $upstream_bytes_received：保存从上游服务器接收到的响应字节数。
  • $upstream_response_length：保存从上游服务器接收到的响应内容的长度。
  • $upstream_status：保存上游服务器返回的 HTTP 响应的状态码。
  • $upstream_cookie_ name：保存上游服务器通过 “Set-Cookie” 响应头发送的 Cookie。