Upstream#

提供用于描述可在 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:1935，剩下的连接分别发送到第二和第三个服务器。

如果在与服务器通信时发生错误，连接将被传递到下一个服务器，依此类推，直到尝试所有正常工作的服务器为止。如果与所有服务器的通信都失败，连接将被关闭。

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 指令的 weight 参数。如果由指令和 SRV 记录同时设置权重，则使用指令设置的权重。

此示例将查找 _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

设置服务器在重新投入服务时恢复其权重的时间，适用于使用 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/ (FreeBSD上为 /var/db/angie/state/) 并设置适当的权限来存储这些文件，因此您只需在配置中添加文件名：

upstream backend {

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

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

警告

要在 upstream 块中使用 state 指令，该块中不应有 server 指令，但需要一个共享内存区域 (zone)。

zone#

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

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

backup_switch (PRO)#

Added in version 1.10.0: PRO

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

该指令启用一种能力，使服务器选择不从主要组开始，而是从*活动*组开始，即之前成功找到服务器的组。如果在活动组中找不到服务器处理下一个请求，搜索会转移到备份组，这个备份组成为活动组，后续请求首先定向到该组中的服务器。

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

示例：

upstream media_backend {
    server primary1.example.com:1935;
    server primary2.example.com:1935;

    server reserve1.example.com:1935 backup;
    server reserve2.example.com:1935 backup;

    backup_switch permanent=2m;
}

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

feedback (PRO)#

Added in version 1.7.0: PRO

语法	`feedback` variable [`inverse`] [`factor=`number] [`account=`condition_variable];
默认值	—
上下文	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

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

hash $remote_addr;

该方法与Perl Cache::Memcached 库兼容。

如果指定了 consistent 参数，将使用ketama一致性哈希方法代替上述方法。该方法确保当服务器添加到组中或从组中移除时，只有最少数量的键会重新映射到其他服务器。对缓存服务器使用此方法可提供更高的缓存命中率。该方法与Perl Cache::Memcached::Fast 库兼容，其中ketama_points参数设置为160。

least_conn#

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

指定一种负载均衡方法，其中连接传递给活动连接数最少的服务器，同时考虑服务器权重。如果有多个合适的服务器，则以循环方式（round-robin）选择它们，并考虑其权重。

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

当前值在服务器的 health 对象中显示为 connect_time、first_byte_time 和 last_byte_time，作为API中 upstream metrics 的一部分。

random#

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

指定一种负载均衡方法，其中连接传递给随机选择的服务器，同时考虑服务器权重。

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

response_time_factor (PRO)#

Syntax	`response_time_factor` number;
默认值	`response_time_factor 90;`
Context	upstream

设置 least_time (PRO) 负载均衡方法的平滑因子，在计算平均响应时间时使用**先前**的值，根据`指数加权移动平均<https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average>`__ 公式。

指定的 number 越大，新值对平均值的影响越小；如果指定 90，则将取先前值的90%，而新值仅占10%。有效值范围为0到99（含）。

当前计算结果在服务器的 health 对象中显示为 connect_time`（连接建立时间）、:samp:`first_byte_time`（接收响应第一个字节的时间）和 :samp:`last_byte_time`（接收完整响应的时间），这些都可以在API的 :ref:`upstream metrics <api_status_stream_upstreams> 中找到。

备注

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

sticky#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

语法

sticky route $变量...;

sticky learn zone=区域 create=$创建变量... lookup=$查找变量... [connect] [norefresh] [timeout=时间];

sticky learn lookup=$查找变量... remote_action=uri remote_result=$远程变量 [remote_uri=uri];

默认

—

上下文

upstream

配置客户端连接与后端服务器之间的会话绑定，所使用的模式由第一个参数指定。对于已启用 sticky 的服务器，可以在其 server 块中启用 drain （PRO 版）选项，实现优雅下线。

警告

必须在所有负载均衡方法指令之后使用 sticky 指令，否则不会生效。

使用预定义的路由标识符，可从连接的特定属性中获取（如 SNI）。该模式灵活性较低，但适用于已有路由 ID 的系统。

当客户端建立连接时，后端服务器可为其分配一个路由 ID，并通过某种约定方式返回。此 ID 必须与 server 指令中的 sid 参数相匹配。若配置了 sticky_secret，则该值会被哈希。

客户端后续连接必须包含该标识符，使其进入指定变量。

指令参数为变量列表，Angie 使用第一个非空值进行匹配，若匹配失败，则按常规负载均衡逻辑选择服务器。

示例中，Angie 从 $ssl_preread_server_name 映射得出 $route：

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 变量值将用作会话 ID，例如可以是后端服务器名称。

会话存储在 zone 参数指定的共享内存区域中。若在 timeout （默认 1 小时）内未访问该会话，则会被清除。

默认会在每次使用后刷新超时时间；可使用 norefresh 禁用该行为，使会话固定在指定期限内失效。

客户端连接中的会话 ID 可通过 lookup 变量获取，若无法找到，则视为新连接。

若匹配成功但服务器不可用，将退回使用默认负载均衡策略。

使用 connect 可在与后端建立连接后立即创建会话；若未设置此参数，则需等待连接完成处理后才会创建会话。对于 UDP，这一行为始终在服务器选择后立即发生。

以下示例中，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;
    }
}

使用 remote_action 和 remote_result 与远程存储交互，实现动态分配和管理会话 ID。

与使用 zone 的 learn 模式不同，本模式不进行本地缓存，每次连接都直接查询远程存储。

remote_action 必须指向一个定义在 client 块中的 location。 remote_uri 设置请求路径，默认值为 /，可使用变量。

流程如下：

首先从 lookup 变量中提取会话 ID（取第一个非空）；若为空，则执行普通负载均衡。
向 remote_action 所指定的远程存储发送同步子请求，请求中应包含：
- 会话 ID，即 $sticky_sessid；
- 所选服务器的标识，可通过 sid= 指定，或使用服务器名称的 MD5 值（变量为 $sticky_sid）。
这些变量在 HTTP 环境中以 stream_ 前缀导出：分别为 $stream_sticky_sessid 与 $stream_sticky_sid。可通过 proxy_set_header 发送为 HTTP 请求头。
远程存储返回响应：
- 状态码 200、201 或 204：确认选定服务器；
- 响应头中可以返回新的服务器 ID，可通过 remote_result 指定变量提取；
- 其他状态码或无法解析服务器 ID 时，将使用最初选择的服务器。

示例中，服务器 ID 从响应头中提取（例如 X-Sticky-Sid）：

http {

    client {

        location @sticky_client1 {

            proxy_set_header X-Sticky-Sessid $stream_sticky_sessid;
            proxy_set_header X-Sticky-Sid $stream_sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://127.0.0.1:8080;

            proxy_cache remote;
            proxy_cache_valid 200 1d;
            proxy_cache_key $scheme$proxy_host$request_uri$stream_sticky_sessid;
        }
    }
}

stream {

    upstream u {
        server 127.0.0.1:8081 sid=backend-01;
        server 127.0.0.1:8082 sid=backend-02;

        sticky learn lookup=$remote_addr
                       remote_action=@sticky_client1
                       remote_result=$upstream_http_x_sticky_sid
                       remote_uri=/foo;
    }

    server {
        listen 127.0.0.1:8080;
        proxy_pass u;
    }
}

以下是远程存储响应示例：

HTTP/1.1 200 OK
...
X-Sticky-Sid: backend-01
X-Session-Info: active

Angie 将创建以下变量：

$upstream_http_x_sticky_sid = backend-01
$upstream_http_x_session_info = active

由于在 remote_result 中指定了 $upstream_http_x_sticky_sid， Angie 会使用其值选择对应的服务器。

sticky 指令会参考 upstream 中的服务器状态：

标记为 down 或短期不可用的服务器会被跳过；
达到连接上限的服务器（启用了 max_conns）会被暂时跳过；
启用了 drain （PRO）的服务器在标识符匹配时仍可用于创建新会话；
一旦不可用服务器恢复，sticky 将恢复使用它。

可通过 sticky_secret 和 sticky_strict 进一步调整行为。若无法选择服务器：

若未启用 sticky_strict，则使用默认负载均衡方法；
若启用 sticky_strict on;，则拒绝该连接。

注意：zone 参数所指定的共享内存区域不能在多个 upstream 间共享；每个 upstream 应使用独立 zone。

sticky_secret#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

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

将 string 作为盐值添加到 route 模式下 sticky 指令的 MD5 哈希函数中。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

sticky_strict#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Syntax	`sticky_strict` `on` \| `off`;
默认值	`sticky_strict off;`
Context	upstream

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

内置变量#

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

`$sticky_sessid`#

与 sticky 中的 remote_action 一起使用；存储从 lookup 获取的初始会话标识符。

`$sticky_sid`#

与 sticky 中的 remote_action 一起使用；存储先前与会话关联的服务器标识符。

sticky_sid 包含 upstream 块中 server 指令的 sid= 参数的值（如果指定），或服务器名称的 MD5 哈希值。

`$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`#

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

`$upstream_sticky_status`#

粘性连接的状态。

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

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

Upstream#

配置示例#

指令#

upstream#

server#

state (PRO)#

zone#

backup_switch (PRO)#

feedback (PRO)#

hash#

least_conn#

least_time (PRO)#

random#

response_time_factor (PRO)#

sticky#

sticky_secret#

sticky_strict#

内置变量#

$sticky_sessid#

$sticky_sid#

$upstream_addr#

$upstream_bytes_received#

$upstream_bytes_sent#

$upstream_connect_time#

$upstream_first_byte_time#

$upstream_session_time#

$upstream_sticky_status#

`$sticky_sessid`#

`$sticky_sid`#

`$upstream_addr`#

`$upstream_bytes_received`#

`$upstream_bytes_sent`#

`$upstream_connect_time`#

`$upstream_first_byte_time`#

`$upstream_session_time`#

`$upstream_sticky_status`#