Upstream

提供一个上下文,用于描述可在 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 和 grpc_pass 指令中使用的服务器组。

相关指南

• 负载均衡：方法、权重、故障、zone 和 sticky。

• Console Light Web 面板：只显示带有 zone 指令的组。

配置示例

upstream backend {
    zone backend 1m;
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server backend3.example.com       service=_example._tcp resolve;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    location / {
        proxy_pass http://backend;
    }
}

指令

backup_switch (PRO)

语法	backup_switch permanent[=time];
默认值	—
上下文	upstream

该指令启用从 活动 组(即上次成功找到服务器的组)而不是主组开始服务器选择的能力。 如果在活动组中无法为下一个请求找到服务器, 并且搜索移动到备份组, 则该组将成为活动组, 后续请求将首先定向到该组中的服务器。

如果定义了 permanent 参数但没有 时间 值, 则该组在选择后保持活动状态, 并且不会自动重新检查较低级别的组。 如果指定了 time, 则该组的活动状态在指定的时间间隔后过期, 负载均衡器将再次检查较低级别的组, 如果服务器正常工作则返回到这些组。

示例:

upstream my_backend {
    zone my_backend 1m;
    server primary1.example.com;
    server primary2.example.com;

    server backup1.example.com backup;
    server backup2.example.com backup;

    backup_switch permanent=2m;
}

如果负载均衡器从主服务器切换到备份组, 所有后续请求将在 2 分钟内由该备份组处理。 2 分钟过后,负载均衡器会重新检查主服务器, 如果它们正常工作,则再次使其成为活动组。

bind_conn (PRO)

语法	bind_conn value;
默认值	—
上下文	upstream

当指定为变量字符串的 value 不等于 "" 和 "0" 时, 允许将服务器连接绑定到客户端连接。

如果绑定的服务器无法通过该客户端连接处理下一个请求（例如在 resolve 将其地址从组中移除之后，或在该服务器不可用期间）， 则绑定的连接将被关闭，并根据所配置的负载均衡方法选择另一台服务器。

警告

bind_conn 指令必须在所有设置负载均衡方法的指令之后使用, 否则将不起作用。 如果与 sticky 指令一起使用, 则 bind_conn 必须在 sticky 之后。

警告

使用该指令时, Proxy 模块设置 必须允许使用持久连接,例如:

proxy_http_version 1.1;
proxy_set_header Connection "";

该指令的典型用例是代理使用 NTLM 身份验证的连接, 其中需要在协商开始时确保客户端到服务器的绑定:

map $http_authorization $ntlm {
    ~*^NTLM       1;
    ~*^Negotiate  1;
}

upstream ntlm_backend {
    zone ntlm_backend 1m;
    server 127.0.0.1:8080;
    bind_conn $ntlm;
}

server {
    # ...
    location / {
        proxy_pass http://ntlm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        # ...
    }
}

feedback (PRO)

语法	feedback variable [inverse] [factor=number] [account=condition_variable] [last_byte];
默认值	—
上下文	upstream

在 upstream 中设置基于反馈的负载均衡机制。 它通过将每个代理服务器的权重乘以平均反馈值来动态调整均衡决策, 该值会根据 variable 的值随时间变化, 并受可选条件的约束。

可以指定以下参数:

variable	从中获取反馈值的变量。 它应该表示性能或健康指标; 假定服务器在响应头或其他方式中提供该值。 该值在服务器的每个响应中进行评估, 并根据 inverse 和 factor 设置 纳入移动平均值。
inverse	如果设置了该参数,则反馈值将被反向解释: 较低的值表示更好的性能。
factor	计算平均值时考虑反馈值的因子。 有效值为 0 到 99 之间的整数。 默认值为 90。 平均值使用 指数平滑 公式计算。 因子越大,新值对平均值的影响越小; 如果指定为 90,则将采用 90% 的先前值 和仅 10% 的新值。
account	指定一个条件变量, 用于控制在计算中考虑哪些响应。 仅当该响应的条件变量 不等于 "" 或 "0" 时, 才会使用该响应的反馈值更新平均值。 备注 默认情况下, 主动检查 期间的响应 不包含在计算中; 将 $upstream_probe 变量 与 account 结合使用可以包含这些响应 或甚至排除其他所有响应。
last_byte	允许在接收到完整响应后处理来自代理服务器的数据, 而不仅仅是响应头。

示例:

upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_http_custom_score $feedback_value {
    "high"                      100;
    "medium"                    75;
    "low"                       50;
    default                     10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}

此配置根据响应头字段中的特定分数 按反馈级别对服务器响应进行分类, 并在 $upstream_probe 上添加条件, 仅考虑来自 high_priority 主动检查的响应 或对常规客户端请求的响应。

hash

语法	hash key [consistent];
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_hash_module 禁用对该指令的支持。

为服务器组指定负载均衡方法,其中客户端到服务器的映射使用哈希键值确定。键可以包含变量。请注意,从组中添加或删除服务器可能会导致大多数键重新映射到不同的服务器。该方法与 Cache::Memcached Perl 库兼容。

hash $remote_addr;

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

server 指令中的名称可以解析为多个地址：在加载配置时解析，或通过 resolve 参数解析。指定 consistent 时，该方法对名称而不是其地址进行哈希（使用 service 参数时，哈希的是 SRV 记录的目标名称）：键映射到某个名称的请求，会通过 加权轮询 负载均衡传递给该名称的某个地址，因此该键不会固定到任何单个地址。未指定 consistent 时，每个地址都被视为一台单独的服务器，但 Angie 不会对地址进行排序，因此在不同的 Angie 实例上，同一个键到达的地址可能不同。有关如何将键固定到单个地址，请参阅 负载均衡指南。

ip_hash

语法	ip_hash;
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_ip_hash_module 禁用对该指令的支持。

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

如果需要临时移除某台服务器,应使用 down 参数标记它,以保持客户端 IP 地址的当前哈希:

upstream backend {
    zone backend 1m;
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

keepalive

语法	keepalive connections;
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_keepalive_module 禁用对该指令的支持。

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

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

备注

需要特别注意的是, keepalive 指令不限制 Angie 工作进程可以打开的到上游服务器的连接总数。connections 参数应设置得足够低,以便让上游服务器也能处理新的传入连接。

备注

缓存的连接按地址与上游服务器匹配。当 resolve 或 API 命令 DELETE 将某个地址从组中移除时， 为该地址缓存的连接不会被关闭：它们会一直占用缓存槽位， 直到服务器关闭它们、keepalive_timeout 到期或它们被逐出； 只有当该地址重新回到组中时，这些连接才会被复用。 proxy_connection_drop、fastcgi_connection_drop、 uwsgi_connection_drop、scgi_connection_drop 和 grpc_connection_drop 指令不会关闭它们：它们只作用于活动连接。

警告

keepalive 指令必须在所有设置负载均衡方法的指令之后使用,否则它将不起作用。

使用 keepalive 连接的 memcached 上游配置示例:

upstream memcached_backend {
    zone memcached_backend 1m;
    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 {
    zone http_backend 1m;
    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 {
    zone fastcgi_backend 1m;
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    #...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
    #    ...
    }
}

备注

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

keepalive_requests

语法	keepalive_requests number;
默认值	keepalive_requests 1000;
上下文	upstream

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

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

keepalive_time

语法	keepalive_time 时间;
默认值	keepalive_time 1h;
上下文	upstream

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

keepalive_timeout

语法	keepalive_timeout timeout;
默认值	keepalive_timeout 60s;
上下文	upstream

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

备注

此超时时间用于与上游服务器之间的空闲连接。 它不是 http、server 或 location 上下文中的客户端 keepalive_timeout， 也不影响 Angie 等待建立新的上游连接的时间， 后者由各协议自身的连接超时设置，例如 proxy_connect_timeout。

least_conn

语法	least_conn;
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_least_conn_module 禁用对该指令的支持。

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

least_time

语法	least_time header | last_byte [factor=number] [account=condition_variable];
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_least_time_module 禁用对该指令的支持。

指定服务器组应使用负载均衡方法,其中活动服务器接收请求的机会与其平均响应时间成反比;响应时间越短,服务器获得的请求越多。

header	该指令计算接收响应头的平均时间。
last_byte	该指令使用接收整个响应的平均时间。

factor	与 response_time_factor 的作用相同,如果设置了该参数,则会覆盖它。
account	指定一个条件变量,用于控制哪些响应包含在计算中。 仅当响应的条件变量不是 "" 或 "0" 时,才会更新平均值。 备注 默认情况下，探测 (PRO) 的响应不包含在计算中; 将 $upstream_probe 变量与 account 结合使用, 可以包含这些响应,甚至排除其他所有响应。

当前值在 API 的 上游指标 中以服务器的 health 对象中的 header_time (仅头部)和 response_time (整个响应)形式呈现。

queue (PRO)

语法	queue number [timeout=time];
默认值	—
上下文	upstream

如果在第一次尝试时无法为请求分配代理服务器(例如,在短暂的服务中断期间或负载激增达到 max_conns 限制时),请求不会被拒绝;相反,Angie 会尝试将其排队等待处理。

该指令的 number 参数设置 工作进程 队列中的最大请求数。如果队列已满,则向客户端返回 502 (Bad Gateway) 错误。

备注

proxy_next_upstream 指令的逻辑也适用于排队的请求。具体来说,如果为请求选择了服务器但无法将其交给该服务器,则请求可能会返回队列。

如果在 timeout 设置的 时间 内(默认为 60 秒)未选择服务器来处理排队的请求,则向客户端返回 502 (Bad Gateway) 错误。过早关闭连接的客户端的请求也会从队列中删除;在 API 中有通过队列的请求状态的计数器。

警告

queue 指令必须在所有设置负载均衡方法的指令之后使用;否则它将不起作用。

random

语法	random [two [least_conn]];
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_random_module 禁用对该指令的支持。

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

如果指定了可选的 two 参数,Angie 会随机选择两个服务器,然后使用 least_conn 方法从中选择一个,即将请求传递给活动连接数最少的服务器。

response_time_factor

语法	response_time_factor number;
默认值	response_time_factor 90;
上下文	upstream

设置在使用 指数加权移动平均 公式计算 least_time 负载均衡方法的平均响应时间时,先前值的平滑因子。

指定的 number 越高,新值对平均值的影响越小;如果指定为 90,则取先前值的 90% 和新值的 10%。有效值范围为 0 到 99(含)。

当前计算结果在 API 的 上游指标 中以服务器 health 对象中的 header_time (仅头部)和 response_time (完整响应)形式呈现。

备注

计算中仅包含成功的响应;什么被视为不成功的响应由 proxy_next_upstream、fastcgi_next_upstream 、uwsgi_next_upstream 、scgi_next_upstream 、memcached_next_upstream 和 grpc_next_upstream 指令确定。此外, header_time 值仅在接收并处理所有头部时重新计算,而 response_time 仅在接收完整响应时重新计算。

server

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

定义服务器的地址和其他参数。地址可以指定为域名或 IP 地址,可带可选端口,或指定为 UNIX 域套接字路径(在 unix: 前缀之后)。如果未指定端口,则使用端口 80。解析为多个 IP 地址的域名会一次性定义多个服务器。

可以定义以下参数:

weight=number	设置服务器的权重。默认值为 1。
max_conns=number	限制到代理服务器的最大同时活动连接数。默认值为 0,表示没有限制。如果服务器组不在 共享内存区 中,则该限制按工作进程生效。

备注

启用 空闲保持连接、多个 工作进程 和 共享内存区 时,到代理服务器的活动和空闲连接总数可能超过 max_conns 值。

max_fails=number — 设置在指定的 fail_timeout 时间段内与服务器通信的失败尝试次数， 达到该次数后服务器将被视为不可用； 之后，将在相同的时间段后再次检查。

失败尝试的定义由 proxy_next_upstream、 fastcgi_next_upstream、uwsgi_next_upstream、 scgi_next_upstream、memcached_next_upstream 和 grpc_next_upstream 指令确定。

当达到 max_fails 时，从 upstream_probe (PRO) 的角度来看， 服务器也被视为不可用；客户端请求将不会被定向到该服务器， 直到检查确定其可用为止。

备注

如果组中的 server 指令解析为多个服务器， 其 max_fails 设置将分别应用于每个服务器。

如果在解析所有 server 指令后， 上游中仅剩一个服务器， 则 max_fails 设置不起作用并将被忽略。

max_fails=1	默认尝试次数；
max_fails=0	禁用尝试计数。

fail_timeout=time — 设置时间段， 在此期间必须发生指定次数的与服务器通信失败尝试 （max_fails），服务器才会被视为不可用。 然后服务器在相同的时间段内保持不可用状态， 之后再次被检查。

默认值为 10 秒。

备注

如果组中的 server 指令解析为多个服务器， 其 fail_timeout 设置将分别应用于每个服务器。

如果在解析所有 server 指令后， 上游中仅剩一个服务器， 则 fail_timeout 设置不起作用并将被忽略。

backup	将服务器标记为备份服务器。当主服务器不可用时，它将接收请求。 如果指定了 backup_switch (PRO) 指令， 其主动备份逻辑也将适用。
down	将服务器标记为永久不可用。
drain	将服务器标记为排空状态；这意味着 它仅接收来自先前通过 sticky 绑定的会话的请求。 否则，行为与 down 模式相同。

警告

backup 和 slow_start 参数不能与 hash、ip_hash 和 random 负载均衡方法一起使用； weight 和 slow_start 参数不能与 least_time 一起使用。

不受支持的组合属于配置错误：Angie 不会启动， 并报告 balancing method does not support parameter 错误。

down 和 drain 参数互斥。

resolve	允许监控与域名对应的 IP 地址列表的变化， 并在不重新加载配置的情况下更新它。 该组必须位于 共享内存 中； 还必须定义 resolver。 当某个地址从组中移除时，为其 缓存 的连接不会被关闭。
service=name	启用 DNS SRV 记录的解析并设置服务名称。要使该参数生效， 必须为服务器指定 resolve 参数， 且主机名中不指定端口。 如果服务名称不包含点，则根据 RFC 标准形成名称： 服务名称前加 _ 前缀， 然后在点后附加 _tcp。 因此，服务名称 http 将变为 _http._tcp。 Angie 通过组合规范化的服务名称和主机名来解析 SRV 记录， 并通过 DNS 获取结果组合的服务器列表， 以及它们的优先级和权重。 具有最高优先级的 SRV 记录 （优先级值最低的记录） 被解析为主服务器， 而其他记录成为备份服务器。 如果 server 设置了 backup， 则具有最高优先级的 SRV 记录被解析为备份服务器， 其他记录被忽略。 权重类似于 server 指令的 weight 参数。 如果在指令本身和 SRV 记录中都指定了权重， 则使用指令中设置的权重。

在此示例中，对记录 _http._tcp.backend.example.com 执行查找：

server backend.example.com service=http resolve;

sid=id

设置组中的服务器 ID。如果未指定该参数， ID 将设置为 IP 地址和端口或 UNIX 套接字路径的 十六进制 MD5 哈希值。

slow_start=time

设置返回服务器权重逐步恢复的 时间， 当使用 轮询 或 least_conn 方法进行负载均衡时。 如果设置了该参数， 并且从 max_fails 和 upstream_probe (PRO) 的角度来看， 服务器在故障后再次被认为可运行， 则该服务器会在给定的时间段内逐步增加到其指定的权重。 如果未设置该参数， 在类似情况下， 服务器会立即以其指定的权重开始运行。

备注

如果上游中仅指定了一个 server， slow_start 将不起作用并会被忽略。

state (PRO)

语法	state file;
默认值	—
上下文	upstream

指定一个 file，用于持久化存储上游服务器列表。 当从 我们的软件包 安装时， 会专门创建目录 /var/lib/angie/state/ （FreeBSD 上为 /var/db/angie/state/） 来存储此类文件，并具有适当的访问权限， 在配置中您只需添加文件名：

upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<FILE_NAME>;
}

这里的服务器列表格式类似于 server。 每当通过配置 API 在 /config/http/upstreams/ 部分更改服务器时， 文件内容就会被修改。 该文件在 Angie 启动或重新加载配置时读取。

警告

要在 upstream 块中使用 state 指令， 其中不能有 server 指令， 但需要共享内存区（zone）。

sticky

语法	sticky cookie name [attr=value]...; sticky route value...; sticky learn zone=zone create=$create_var1... lookup=$lookup_var1... [header] [norefresh] [timeout=time]; sticky learn [zone=zone] lookup=$lookup_var1... remote_action=uri remote_result=$remote_var [norefresh] [timeout=time]; (PRO)
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_sticky_module 禁用对该指令的支持。

配置会话亲和性，以将客户端会话绑定到代理服务器， 模式由第一个参数指定； 要排空配置了 sticky 指令的服务器， 可以在 server 块中使用 drain 选项。

警告

sticky 指令必须在所有指定特定负载均衡方法的指令之后使用， 否则将不起作用。 如果与 bind_conn (PRO) 指令一起使用， 则 bind_conn 必须在 sticky 之后。

cookie 模式route 模式learn 模式带 remote_action 的 learn 模式（PRO）

此模式使用 cookie 来管理会话。 适用于已经使用 cookie 进行会话跟踪的场景。

在应用任何粘性之前，第一个客户端请求 会根据配置的负载均衡方法发送到后端服务器。 然后 Angie 会设置一个标识所选服务器的 cookie。

cookie 名称（name）由 sticky 指令定义， 其值对应于 sid （来自 server 指令）。 如果设置了 sticky_secret，此值会进一步进行哈希处理。

后续携带此 cookie 的请求会被路由到 由其 sid 指定的服务器。 如果该服务器不可用或无法处理请求， 则通过配置的负载均衡方法选择另一个服务器。

您可以在指令中分配 cookie 属性； 默认情况下，仅设置 path=/。 属性值可以包含变量。 要删除某个属性，请将其设置为空值：attr=。 例如，sticky cookie path= 会省略 path 属性。

此示例设置一个名为 srv_id 的 cookie，有效期为 1 小时， 使用来自变量的域名：

upstream backend {
    zone backend 1m;
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie srv_id domain=$my_domain max-age=3600;
}

sticky 指令遵循上游服务器状态：

• 标记为 down 或失败的服务器会被排除。

• 超过 max_conns 限制的服务器会被跳过。

• drain 服务器在 sticky 模式下当标识符匹配时仍可能被选中用于新会话。

• 恢复的服务器会自动重新使用。

您可以使用 sticky_secret 和 sticky_strict 进一步调整行为。 如果粘性失败且 sticky_strict 关闭， 则使用回退负载均衡； 如果开启，则拒绝请求。

sticky 中使用的每个 zone 必须专属于单个 upstream。 区域不能在多个 upstream 块之间共享。

sticky_secret

语法	sticky_secret string;
默认值	—
上下文	upstream

将 string 作为盐值添加到 MD5 哈希函数中， 用于 cookie 和 route 模式下的 sticky 指令。 string 可以包含变量，例如 $remote_addr：

upstream backend {
    zone backend 1m;
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}

盐值会附加到被哈希的值后面； 要独立验证哈希机制：

$ echo -n "<VALUE><SALT>" | md5sum

sticky_strict

语法	sticky_strict on | off;
默认值	sticky_strict off;
上下文	upstream

启用时，如果与会话绑定的服务器 ID 与组中任何服务器都不匹配， 或该服务器不可用， Angie 会向客户端返回 HTTP 502 错误， 而不是回退到负载均衡（默认行为）。

upstream

语法	upstream name { ... }
默认值	—
上下文	http

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

示例：

upstream backend {
    zone backend 1m;
    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,第二个和第三个服务器各接收一个请求。该分配是平滑的:权重较高的服务器的请求会分散到整个轮询周期中,而不是集中成一批连续发送。

如果在与服务器通信期间发生错误，请求将被传递到下一个服务器，依此类推，直到尝试所有正常运行的服务器。如果无法从任何服务器获得成功响应，Angie 将返回自己的错误页面，而不是最后一个服务器的响应。

备注

默认情况下,偶尔出现失败尝试但未达到 max_fails 阈值的服务器会暂时收到较少的请求份额,并在后续请求中逐渐恢复到完整份额。这与 slow_start 不同:后者仅在服务器被标记为不可用并随后恢复后,才使其逐步回到完整权重。

zone

语法	zone name [size];
默认值	—
上下文	upstream

当 从源代码构建 时，可以通过 构建选项 --without-http_upstream_zone_module 禁用对该指令的支持。

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

备注

配置重载无论 size 是否变化都会重新创建区域： 计数器、被动检查状态和累积的均衡历史都从零开始。 带 resolve 参数的服务器所解析出的地址会保留到新区域中； 在 Angie PRO 中， 带 persistent 参数的主动检查所依赖的健康标志也会保留。

备注

仅在配置了此区域时才会收集上游指标。如未配置，该组将不会出现在 /status/http/upstreams/<upstream>、 「HTTP Upstreams」小部件 及 Prometheus 输出中，且不会输出任何警告信息。 参见 配置示例。

内置变量

http_upstream 模块支持以下内置变量:

$sticky_sessid

与 sticky 中的 remote_action 一起使用; 存储从 lookup 获取的初始会话 ID。

$sticky_sid

与 sticky 中的 remote_action 一起使用; 存储由负载均衡方法预先选定的服务器的 ID： 该服务器的 sid= 值或其生成的默认值 （参见 server）。

$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

从上游服务器接收的字节数。来自多个连接的值用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_bytes_sent

发送到上游服务器的字节数。来自多个连接的值用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_cache_key

Added in version 1.11.0.

包含用于请求的缓存键。

$upstream_cache_status

保存访问响应缓存的状态。状态可以是 MISS、BYPASS、EXPIRED、STALE、UPDATING、 REVALIDATED 或 HIT:

• MISS:在缓存中未找到响应, 请求被传递到上游服务器。

• BYPASS:绕过缓存, 请求直接传递到上游服务器。

• EXPIRED:缓存的响应已过期, 向上游服务器传递新请求以更新内容。

• STALE:缓存的响应已过期, 但仍然提供给客户端, 直到最终从上游服务器更新内容。

• UPDATING:缓存的响应已过期, 但仍然提供给客户端, 同时正在进行从上游服务器的更新。

• REVALIDATED:缓存的响应已过期, 但已成功重新验证, 无需从上游服务器更新。

• HIT:响应从缓存中获取。

如果请求绕过缓存而未访问它, 则不设置该变量。

$upstream_connect_time

保存与上游服务器建立连接所花费的时间;时间以秒为单位保存,具有毫秒分辨率。在 SSL 的情况下,包括握手所花费的时间。多个连接的时间用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_cookie_<name>

上游服务器在 Set-Cookie 响应头字段中发送的指定名称的 cookie。仅保存最后一个服务器响应中的 cookie。

$upstream_current_addr (PRO)

Added in version 1.12.0: PRO

为当前连接尝试所选择的被代理服务器的地址； 与 $upstream_addr 不同，后者会累积每次重试所尝试的每个服务器的地址， 而该变量始终只保存单个地址，并且在服务器被选择后立即可用， 包括在对 proxy_bind 变量求值期间。

$upstream_header_time

保存从上游服务器接收响应头所花费的时间;时间以秒为单位保存,具有毫秒分辨率。多个响应的时间用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_http_<name>

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

$upstream_queue_time

保存请求在下一次服务器选择之前在 队列 中花费的时间; 时间以秒为单位保存,具有毫秒分辨率。 多次尝试的时间用逗号和冒号分隔, 类似于 $upstream_addr 变量中的地址。

$upstream_request_method

Added in version 1.11.0.

用于上游请求的请求方法。当缓存将 HEAD 转换为 GET 或设置了 proxy_method 时,它可能与客户端请求方法不同。

$upstream_response_length

保存从上游服务器获取的响应的长度;长度以字节为单位保存。多个响应的长度用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_response_time

保存从上游服务器接收响应所花费的时间;时间以秒为单位保存,具有毫秒分辨率。多个响应的时间用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_status

保存 Angie 为每次上游尝试记录的状态码。对于 DoH 请求，被截断的 UDP 响应记录为 426，已接受的 DNS 响应记录为 200。多次尝试的状态码用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。

$upstream_sticky_status

粘性请求的状态。

""	请求发送到未启用粘性的上游。
NEW	请求不包含粘性信息。
HIT	带有粘性信息的请求发送到所需的服务器。
MISS	带有粘性信息的请求发送到由负载均衡算法选择的服务器。

来自多个连接的状态用逗号和冒号分隔, 类似于 $upstream_addr 变量中的地址。

$upstream_trailer_<name>

保存从上游服务器获取的响应末尾的字段。

$upstream_transport

Added in version 1.12.0.

保存每次上游连接尝试所使用的传输协议 TCP 或 UDP。 多次尝试的值用逗号和冒号分隔，类似于 $upstream_addr 变量中的地址。