上游#

该模块用于定义可以通过 proxy_passfastcgi_passuwsgi_passscgi_passmemcached_passgrpc_pass 指令引用的服务器组。

配置示例#

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

指令#

bind_conn (PRO)#

语法

bind_conn value;

默认

上下文

upstream

value 被设置为变量字符串并变为非空值 """0" 之外的值时,启用将服务器连接绑定到客户端。

注意

bind_conn 指令必须在所有设置负载均衡方法的指令之后使用; 否则,它将不起作用。 如果同时使用 stickybind_conn 应该出现在 sticky 之后。

注意

使用指令时,配置 http_proxy 模块以允许保持连接,例如:

proxy_http_version 1.1;
proxy_set_header Connection "";

该指令的一个典型用例是代理 NTLM 认证的连接,其中客户端在协商开始时应该绑定到服务器:

map $http_authorization   $ntlm {
    ~*^N(?:TLM|egotiate)  1;
}

upstream ntlm_backend {
    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)#

Added in version 1.6.0: PRO

语法

feedback variable [inverse] [factor=number] [account=condition_variable] [last_byte];

默认

上下文

upstream

启用基于反馈的负载均衡机制用于 upstream。 它动态调整负载均衡决策, 将每个节点的权重乘以其平均反馈值, 该值受随时间变化的 variable 的影响,并受可选条件的制约。

接受以下参数:

variable

反馈值来源的变量。 它应表示性能或健康指标, 并旨在通过节点在头字段或其他方式提供。

在每次从节点的响应中评估该值, 并根据 inversefactor 设置纳入滚动平均值。

inverse

如果设置,反馈值被反向解释, 即较低的值表示更好的性能。

factor

计算平均值时反馈值的权重因子。 有效值为 0 到 99 之间的整数。 默认值 — 90

使用 exponential moving average 公式计算平均反馈。

因子越大,新的值对平均值的影响越小; 如果因子设置为 90, 结果将有 90% 来自先前的值,仅 10% 来自新值。

account

指定一个条件变量 控制应包括哪些响应进行计算。 仅当响应的条件变量不为 """0" 时, 平均值才会使用反馈值进行更新。

备注

默认情况下,来自 probes 的响应 不包括在计算中; 将 $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

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

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

ip_hash#

语法

ip_hash;

默认

上下文

upstream

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

如果需要临时移除其中一台服务器,应使用 down 参数进行标记,以保持当前的客户端 IP 地址哈希。

upstream backend {
    ip_hash;

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

keepalive#

语法

keepalive connections;

默认

上下文

upstream

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

connections 参数设置每个工作进程中保存在缓存中的最大空闲保持连接数。当超过该数字时,将关闭最近最少使用的连接。

备注

特别需要指出的是,keepalive 指令并不限制 Angie 工作进程可以打开的与上游服务器的总连接数。连接参数应设置为足够小的数字,以便让上游服务器处理新的传入连接。

注意

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 以使保持连接工作:

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_requests#

语法

keepalive_requests number;

默认

keepalive_requests 1000;

上下文

upstream

设置可以通过一个保持连接服务的最大请求数。在达到最大请求数后,连接将关闭。

定期关闭连接是必要的,以释放每连接的内存分配。因此,使用过高的最大请求数可能会导致过度的内存使用,不建议使用。

keepalive_time#

语法

keepalive_time time;

默认

keepalive_time 1h;

上下文

upstream

限制可以通过一个保持连接处理请求的最长时间。达到此时间后,连接将关闭,随后处理下一个请求。

keepalive_timeout#

语法

keepalive_timeout 时间;

默认值

keepalive_timeout 60s;

上下文

upstream

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

least_conn#

语法

least_conn;

默认值

上下文

upstream

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

least_time (PRO)#

语法

least_time header | last_byte [factor=number] [account=condition_variable];

默认值

上下文

upstream

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

header

指令仅考虑响应头。

last_byte

指令使用接收整个响应的平均时间。

Added in version 1.7.0: PRO

factor

response_time_factor (PRO) 具有相同的目的,如果设置则覆盖。

account

指定一个条件变量 控制哪些响应应包含在计算中。 平均值仅在响应的条件变量 不是 """0" 时更新。

备注

默认情况下,来自 probes 的响应 不包括在计算中; 将 $upstream_probe 变量 与 account 结合使用可以包括这些响应 或甚至排除其他所有响应。

相应的移动平均值,经过 factoraccount 调整, 也作为 header_timeresponse_time 显示在 服务器的 health 对象中,位于 API 中的 上游指标

queue (PRO)#

Added in version 1.4.0: PRO

语法

queue number [timeout=时间];

默认值

上下文

upstream

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

指令中的数字设置了 worker process 的队列中请求的最大数量。 如果队列已满, 将向客户端返回 502 (Bad Gateway) 错误。

备注

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

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

注意

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

random#

语法

random [two];

默认值

上下文

upstream

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

可选的 two 参数指示 Angie 随机选择两个服务器,然后使用指定的方法选择一个服务器。默认方法是 least_conn,它将请求传递给活动连接数最少的服务器。

response_time_factor (PRO)#

语法

response_time_factor number;

默认值

response_time_factor 90;

上下文

upstream

如果使用 least_time (PRO) 负载均衡方法,设置**前**值的平滑因子 用于使用 指数移动平均 公式计算的平均响应时间。

number 越大,新值对平均值的影响越小;如果 number 设置为 90,结果将有 90% 来自于之前的值,仅有 10% 来自于新值。允许的范围是 0 到 99(包括)。

相应的移动平均值作为 header_time`(仅头部) :samp:`response_time`(整个响应)在服务器的 :samp:`health 对象中显示,位于 API 中的 上游指标

备注

计算仅考虑成功响应;什么被视为 不成功的响应由 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,表示没有限制。如果服务器组不驻留在 共享内存 中,则限制适用于每个工作进程。

备注

如果启用了空闲 keepalive 连接、多个 workers共享内存,则对代理服务器的活动和空闲连接的总数可能会超过 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 时,peers 也会被 upstream_probe (PRO) 探针视为不健康;它将不会接收客户端请求,直到探针重新认为它健康。

备注

如果一个 server 在上游解析为多个 peers, 则其 max_fails 设置适用于每个 peer。

如果在解析所有 server 指令后,上游仅包含一个 peer, 则 max_fails 设置将无效并被忽略。

max_fails=1

不成功尝试的默认次数

max_fails=0

禁用尝试的计数

fail_timeout=时间 — 设置在多长时间内应发生与服务器通信的失败尝试次数 (max_fails) 才能将服务器视为不可用。 然后,服务器在同样的时间内变得不可用 然后才会重试。

默认情况下,这设置为 10 秒。

备注

如果一个 server 在上游解析为多个 peers, 则其 fail_timeout 设置适用于每个 peer。

如果在解析所有 server 指令后,上游仅包含一个 peer, 则 fail_timeout 设置将无效并被忽略。

backup

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

down

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

drain

将服务器设置为排水;这意味着 它仅接收来自之前绑定的会话的请求: sticky。 否则,它的行为类似于 down

小心

参数 backup 不能与 haship_hashrandom 负载均衡方法一起使用。

downdrain 选项是互斥的。

Added in version 1.1.0.

resolve

启用监控与域名对应的 IP 地址列表的更改,更新而无需重新加载配置。 该组应该存储在 共享内存区域; 此外,您需要定义一个 resolver

service=name

启用解析 DNS SRV 记录并设置服务名称。 为了使该参数生效,请指定 resolve 服务器参数, 提供无端口号的主机名。

如果服务名称中没有点, 则该名称根据 RFC 标准形成: 服务名称以 _ 为前缀, 然后在点后添加 _tcp。 因此,服务名称 http 将结果为 _http._tcp

Angie 通过组合归一化的服务名称和主机名解析 SRV 记录,并 通过 DNS 获取组合的服务器列表, 以及它们的优先级和权重。

  • 优先级最高的 SRV 记录 (共享最小优先级值的记录) 解析为主服务器, 其他记录成为备份服务器。 如果 backupserver 设置, 优先级最高的 SRV 记录解析为备份服务器, 其他记录将被忽略。

  • 权重会影响服务器的选择,依据分配的容量: 权重较高的服务器会接收更多的请求。 如果同时通过 server 指令和 SRV 记录设置权重, 则使用 server 设置的权重。

这个示例将查找 _http._tcp.backend.example.com 记录:

server backend.example.com service=http resolve;

Added in version 1.2.0: Angie

Added in version 1.1.0-P1: Angie PRO

sid=id

设置组内的服务器 ID。
如果参数被省略, ID 将设置为 IP 地址和端口或 UNIX 域套接字路径的十六进制 MD5 哈希值。

Added in version 1.4.0.

slow_start=time

设置 time 来恢复服务器的 weight 当它重新上线时, 如果负载均衡使用 round-robinleast_conn 方法。

如果设置了该值, 且服务器被再次视为可用且健康, 按照 max_failsupstream_probe (PRO) 的定义, 服务器将在分配的时间框架内逐渐恢复其指定的权重。

如果未设置该值, 类似情况下的服务器将立即恢复其指定的权重。

备注

如果上游中只有一个 serverslow_start 将无效并被忽略。

state (PRO)#

Added in version 1.2.0: PRO

Syntax

state file;

Default

Context

upstream

指定了上游服务器列表持久化的 file。 从 我们的包 安装时, 会创建一个指定的 /var/lib/angie/state/ (在 FreeBSD 上为 /var/db/angie/state/) 目录,并赋予适当的权限来存储这些文件, 因此您只需在配置中添加文件的基本名称:

upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<文件名>;
}

该服务器列表的格式类似于 server。文件的内容 在通过配置 API 对 /config/http/upstreams/ 部分中的服务器进行任何修改时会发生变化。 该文件在 Angie 启动或配置重载时读取。

小心

要在 upstream 块中使用 state 指令, 该块不能有 server 指令; 而是必须有一个共享内存区域 (zone).

sticky#

Added in version 1.2.0: Angie

Added in version 1.1.0-P1: Angie PRO

Syntax

sticky cookie name [attr=value]...;

sticky route $variable...;

sticky learn zone=zone create=$create_var1... lookup=$lookup_var1... [header] [timeout=time];

sticky learn zone=zone lookup=$lookup_var1... remote_action=uri remote_result=$remote_var [timeout=time];

Default

Context

upstream

配置客户端会话与代理服务器的绑定 采用第一个参数指定的模式; 要从定义了 sticky 的服务器中排出请求, 请在 server 块中使用 drain 选项。

注意

sticky 指令必须在所有设置负载均衡方法的指令之后使用; 否则,它将不起作用。 如果同时使用 bind_conn (PRO)bind_conn 应该出现在 sticky 之后。

此模式使用 cookie 来保持会话持久性。 它更适合于已经使用 cookie 进行会话管理的情况。

在这里,客户的请求, 尚未绑定到任何服务器, 被发送到根据配置的负载均衡方法选择的服务器。 此外,Angie 设置了一个具有唯一值的 cookie 来标识服务器。

cookie 的名称 (name) 由 sticky 指令设置, 值 (value) 对应于 sid 参数 的 server 指令。 请注意,如果设置了 sticky_secret 指令, 参数还会被额外哈希。

随后的客户请求如果包含此 cookie, 将转发到由 cookie 值标识的服务器, 即具有指定 sid 的服务器。 如果选择服务器失败, 或所选服务器无法处理请求, 则根据配置的负载均衡方法选择另一台服务器。

该指令允许为 cookie 分配属性; 默认情况下,唯一设置的属性是 path=/。 属性值被指定为带有变量的字符串。 要移除一个属性,可以为其设置一个空值:attr=。 因此,sticky cookie path= 会创建一个没有 path 的 cookie。

在这里, Angie 创建一个名为 srv_id 的 cookie,生命周期为一小时, 以及一个变量指定的域:

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

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

sticky_secret#

Added in version 1.2.0: Angie

Added in version 1.1.0-P1: Angie PRO

语法

sticky_secret string;

默认值

上下文

upstream

string 作为盐值添加到 MD5 哈希函数中 用于 sticky 指令在 cookieroute 模式下。 string 可以包含变量,例如,$remote_addr

upstream backend {
    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#

Added in version 1.2.0: Angie

Added in version 1.1.0-P1: Angie PRO

语法

sticky_strict on | off;

默认值

sticky_strict off;

上下文

upstream

启用时,如果所需的服务器不可用,Angie 将返回 HTTP 502 错误给客户端, 而不是在没有可用服务器时使用任何其他可用的服务器。

upstream#

语法

upstream name { ... }

默认值

上下文

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,每个第二和第三个服务器各 1 个请求。

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

zone#

语法

zone name [size];

默认值

上下文

upstream

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

内置变量#

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

$sticky_sessid#

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

$sticky_sid#

remote_action 一起使用于 sticky; 存储暂时与会话相关联的服务器 ID。

$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

如果无法选择服务器,该变量将保留 server groupname

$upstream_bytes_received#

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

$upstream_bytes_sent#

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

$upstream_cache_status#

保存访问响应缓存的状态。状态可以是 MISSBYPASSEXPIREDSTALEUPDATINGREVALIDATEDHIT

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

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

  • EXPIRED:缓存的响应过期, 并向上游服务器发送用于更新内容的新请求。

  • STALE:缓存的响应过期, 但将提供给客户端 直到最终从上游服务器获取更新。

  • UPDATING:缓存的响应过期, 但将提供给客户端 直到当前正在进行的来自上游服务器的更新完成。

  • REVALIDATED:缓存的响应过期, 但已成功重新验证 并且不需要来自上游服务器的更新。

  • HIT:响应是从缓存中提供的。

如果完全绕过缓存而未访问它, 则该变量未设置。

$upstream_connect_time#

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

$upstream_header_time#

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

$upstream_http_<name>#

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

$upstream_queue_time#

保存请求在 queue 中花费的时间 在选择服务器之前; 该时间以毫秒为单位,保留到秒。 多个选择尝试的时间用逗号和冒号分隔, 类似于 $upstream_addr 变量中的地址。

$upstream_response_length#

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

$upstream_response_time#

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

$upstream_status#

保存从上游服务器获取的响应的状态代码。多个响应的状态代码用逗号和冒号分隔,类似于 $upstream_addr 变量中的地址。如果无法选择服务器,则该变量保留 502(坏网关)状态代码。

$upstream_sticky_status#

粘性请求的状态。

""

没有启用粘性的请求发送到上游。

NEW

没有粘性信息的请求。

HIT

带有粘性信息的请求路由到所需的后端。

MISS

带有粘性信息的请求路由到通过 负载均衡算法选择的后端。

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

$upstream_trailer_<name>#

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