上游#

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

配置示例#

upstream backend {
    hash $remote_addr consistent;
    zone backend 1m;

    server backend1.example.com:1935 weight=5;
    server unix:/tmp/backend3;
    server backend3.example.com service=_example._tcp resolve;

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

resolver 127.0.0.53 status_zone=resolver;

server {
    listen 1936;
    proxy_pass backend;
}

指令#

upstream#

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

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

示例：

upstream backend {
    server backend1.example.com:1935 weight=5;
    server 127.0.0.1:1935 max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:1935 resolve;

    server backup1.example.com:1935 backup;
}

默认情况下，请求在服务器之间使用加权轮询负载均衡方法进行分配。在上面的示例中，每 7 个请求将按如下方式分配：5 个请求发送到 backend1.example.com，剩下的请求分别发送到第二和第三个服务器。

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

server#

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

定义服务器的地址和其他参数。地址可以指定为带有必需端口的域名或 IP 地址，或在 unix: 前缀后指定为 UNIX 域套接字路径。解析为多个 IP 地址的域名一次定义多个服务器。

可以定义以下参数：

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

max_fails=number — 设置在 fail_timeout 指定的时间段内与服务器通信失败的尝试次数，以便认为服务器不可用；然后将在同一时间段后重试。

此处，不成功的尝试是指在与服务器建立连接时发生的错误或超时。

备注

如果上游中的 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`	将服务器标记为备份服务器。当主服务器不可用时，将传递请求给它。
`down`	将服务器标记为永久不可用。
`drain` (PRO)	将服务器设为排出状态；这意味着它仅接收早先通过 sticky 绑定的会话请求。否则它的行为类似于 `down`。

小心

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

down 和 drain 选项是互斥的。

Added in version 1.3.0.

resolve

启用对与域名对应的 IP 地址列表的更改进行监控，更新它而无需重新加载配置。该组应存储在共享内存区中；还需要定义 resolver。

service=name

启用解析 DNS SRV 记录并设置服务名称。要使此参数生效，请指定 resolve 服务器参数，不带端口号提供主机名。

如果服务名称中没有点，名称将根据 RFC 标准形成：服务名称以 _ 为前缀，然后在点后加上 _tcp。因此，服务名称 http 将变成 _http._tcp。

Angie 通过组合规范化的服务名称和主机名解析 SRV 记录，并通过 DNS 获取该组合的服务器列表及其优先级和权重。

最高优先级的 SRV 记录（具有最小优先级值的记录）解析为主服务器，其他记录变为备份服务器。如果在 server 中设置了 backup，最高优先级的 SRV 记录解析为备份服务器，其他记录将被忽略。
权重影响通过分配的容量选择服务器：权重越高，收到的请求越多。如果由 server 指令和 SRV 记录同时设置权重，则使用 server 设置的权重。

此示例将查找 _http._tcp.backend.example.com 记录：

server backend.example.com service=http resolve;

Added in version 1.4.0.

slow_start=time

设置服务器重新上线时恢复 weight 的时间，如果负载均衡使用 round-robin 或 least_conn 方法。

如果设置了该值，并且服务器再次被视为可用和健康（由 max_fails 和 upstream_probe (PRO) 定义），则服务器将在分配的时间内稳步恢复其指定的权重。

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

备注

如果在上游中只有一个 server，则 slow_start 无效并将被忽略。

state (PRO)#

Added in version 1.4.0: PRO

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

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

upstream backend {

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

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

小心

要在 upstream 块中使用 state 指令，该块不应有 server 指令；相反，它必须有一个共享内存区 (zone)。

zone#

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

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

feedback (PRO)#

Added in version 1.7.0: 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` 可以将其包括在内，或甚至排除其他所有内容。

示例：

upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com:1935 weight=1;
    server backend2.example.com:1935 weight=2;
}

map $protocol $feedback_value {
    "TCP"                      100;
    "UDP"                      75;
    default                    10;
}

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

这将根据不同会话使用的具体协议将服务器分类到不同的反馈级别，并且还添加了一个从 $upstream_probe 映射的条件，仅考虑 high_priority 探测或常规客户端会话。

hash#

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

指定服务器组的负载均衡方法，其中客户端-服务器映射基于哈希键值。键可以包含文本、变量及其组合（1.11.2）。使用示例：

hash $remote_addr;

注意，添加或移除服务器可能导致重新映射大多数键到不同的服务器。该方法兼容 Cache::Memcached Perl 库。

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

least_conn#

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

指定一个组使用负载均衡方法，其中连接传递到活动连接数最少的服务器，同时考虑服务器的权重。如果有多个这样的服务器，则通过加权轮询负载均衡方法轮流尝试。

least_time (PRO)#

语法	`least_time` `connect` \| `first_byte` \| `last_byte` [`factor=`number] [`account=`condition_variable];
默认	—
上下文	upstream

设置负载均衡方法，其中连接转发到活动服务器的概率与响应所需的平均时间成反比；响应时间越短，服务器接收的连接越多。

`connect`	指令考虑建立连接所需的平均时间。
`first_byte`	指令使用接收响应第一个字节的平均时间。
`last_byte`	指令使用接收完整响应的平均时间。

Added in version 1.7.0: PRO

`factor`	用于与 response_time_factor (PRO) 相同目的，并在设置时覆盖。
`account`	指定控制哪些连接应包含在计算中的条件变量。平均值仅在连接的条件变量不为 `""` 或 `"0"` 时更新。备注默认情况下，探测不包含在计算中；结合 $upstream_probe 变量与 `account` 可以将其包括在内，或甚至排除其他所有内容。

相应的移动平均值，经过 factor 和 account 调整后，也在服务器的 health 对象中作为 connect_time、first_byte_time 和 last_byte_time 呈现于 API 的 stream upstream metrics 中。

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 越大，新值对平均值的影响越小；如果指定了 90，则取前值的 90%，新值仅占 10%。可接受值范围从 0 到 99（含）。

相应的移动平均值在服务器的 health 对象中作为 connect_time (建立连接所需时间）、first_byte_time (接收响应第一个字节所需时间）和 last_byte_time (接收完整响应所需时间）呈现于 API 的 stream upstream metrics 中。

备注

仅成功响应会被考虑在计算中；什么构成不成功的响应由 proxy_next_upstream 指令决定。

sticky#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

语法

sticky route $variable...;

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

默认

—

上下文

upstream

配置客户端会话绑定到代理服务器的模式；为了从定义了 sticky 的服务器中排空请求，使用 drain 选项在 server 块中。

注意

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

此模式使用预定义的路由标识符，可以嵌入 Angie 可以访问的任何连接属性中。它的灵活性较低，因为它依赖于预定义的值，但如果这些标识符已存在，则可能更适合。

在此，当与代理服务器建立连接时，它可以为客户端分配一个路由，并以双方都知悉的方式返回其标识符。server 指令的 sid 参数的值必须用作路由标识符。注意，如果设置了 sticky_secret 指令，该参数会被额外哈希。

希望使用该路由的客户端的后续连接必须包含服务器发出的标识符，确保其最终位于 Angie 变量中。

指令列出了用于路由的特定变量。选择传入连接路由到的服务器时，使用第一个非空变量；然后将其与 server 指令的 sid 参数进行比较。如果选择服务器失败或所选服务器无法接受连接，则根据配置的负载均衡方法选择另一个服务器。

在此，Angie 在自定义 $route 变量中查找标识符，该变量从 $ssl_preread_server_name 映射（注意必须启用 ssl_preread）：

stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}

此模式使用动态生成的密钥将客户端与特定代理服务器关联；它更灵活，因为它在运行时分配服务器，在共享内存区域存储会话，并支持不同的会话标识符传递方式。

在此，基于来自代理服务器的连接属性创建会话。create 和 lookup 参数列出表示如何创建新会话和查找现有会话的变量。两个参数可以多次出现。

会话标识符是第一个非空变量的值，该变量由 create 指定；例如，这可以是代理服务器的名称。

会话存储在共享内存区域中；其名称和大小由 zone 参数设置。如果会话在 timeout 设置的时间内保持不活动，则会被删除。默认是 1 小时。

希望使用该会话的客户端的后续连接必须包含其标识符，确保其最终位于 lookup 指定的非空变量中；其值将与共享内存中的会话匹配。如果选择服务器失败或所选服务器无法接受连接，则根据配置的负载均衡方法选择另一个服务器。

connect 参数允许在与代理服务器建立连接后立即创建会话。否则，仅在处理连接后创建会话。

在示例中，Angie 使用 $rdp_cookie 变量创建和查找会话：

stream {

    upstream backend {

        server 127.0.0.1:3390 sid=a;
        server 127.0.0.1:3391 sid=b;

        sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
    }

    server {

        listen 127.0.0.1:3389;

        ssl_preread on;

        proxy_pass backend;
    }
}

sticky_strict#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Syntax	`sticky_strict` `on` \| `off`;
Default	`sticky_strict off;`
Context	upstream

启用时，如果所需的服务器不可用，Angie 会向客户端返回连接错误，而不是使用其他可用的服务器，正如当上游中没有服务器可用时那样。

sticky_secret#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Syntax	`sticky_secret` string;
Default	—
Context	upstream

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

upstream backend {
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}

盐值附加在被哈希的值上；要独立验证哈希机制：

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

内置变量#

stream_upstream 模块支持以下内置变量：

`$upstream_addr`#

保持上游服务器的 IP 地址和端口，或 UNIX 域套接字的路径。如果在请求处理期间联系了多个服务器，其地址以逗号分隔，例如：

192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock

如果无法选择服务器，变量保存 server group 的 name。

`$upstream_bytes_received`#

从上游服务器接收的字节数。多个连接的值以逗号分隔，类似于 $upstream_addr 变量中的地址。

`$upstream_bytes_sent`#

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

`$upstream_connect_time`#

连接上游服务器的时间；时间以秒为单位，精确到毫秒。多个连接的时间以逗号分隔，类似于 $upstream_addr 变量中的地址。

`$upstream_first_byte_time`#

接收第一个字节数据的时间；时间以秒为单位，精确到毫秒。多个连接的时间以逗号分隔，类似于 $upstream_addr 变量中的地址。

`$upstream_session_time_<name>`#

会话持续时间，以秒为单位，精确到毫秒。多个连接的时间以逗号分隔，类似于 $upstream_addr 变量中的地址。

`$upstream_sticky_status`#

粘性连接的状态。

`""`	连接路由到上游而未启用粘性。
`NEW`	无粘性信息的连接。
`HIT`	含粘性信息的连接路由到所需的后端。
`MISS`	含粘性信息的连接路由到由负载均衡算法选择的后端。

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

上游#

配置示例#

指令#

upstream#

server#

state (PRO)#

zone#

feedback (PRO)#

hash#

least_conn#

least_time (PRO)#

random#

response_time_factor (PRO)#

sticky#

sticky_strict#

sticky_secret#

内置变量#

$upstream_addr#

$upstream_bytes_received#

$upstream_bytes_sent#

$upstream_connect_time#

$upstream_first_byte_time#

$upstream_session_time_<name>#

$upstream_sticky_status#

`$upstream_addr`#

`$upstream_bytes_received`#

`$upstream_bytes_sent`#

`$upstream_connect_time`#

`$upstream_first_byte_time`#

`$upstream_session_time_<name>`#

`$upstream_sticky_status`#