上游与负载均衡
上游定义服务的后端目标。它指定目标节点、网关如何在节点之间分发流量（负载均衡），以及如何 监控节点可用性（健康检查）。
在 API7 企业版中，上游通常配置在服务的 upstream 字段中，也可以作为独立对象管理并由多个服务引用。
负载均衡算法
API7 网关支持多种在后端节点之间分发流量的算法。
| 算法 | 说明 | 最适合 |
|---|---|---|
roundrobin | 根据节点权重，依次向各节点分发请求。 | 大多数通用应用。 |
chash | 使用一致性哈希（按 URI、Cookie 等）将请求映射到同一节点。 | 需要会话保持的有状态应用。 |
least_conn | 将请求路由到活动连接数最少的节点。 | 请求处理时间差异较大的工作负载。 |
ewma | 指数加权移动平均（Peak EWMA），选择预测延迟最低的节点。 | 动态响应后端性能波动。 |
一致性哈希键
将 type 设置为 chash 时，网关对每个请求的某个属性进行哈希，并使用该哈希选择后端节点。产生相同值的请求会持续路由到同一节点。以下两个字段控制此行为：
hash_on：读取值的来源，默认为vars。key：从该来源读取的字段。
key 接受的格式取决于 hash_on。保存上游时，网关会验证两者组合，并对无效 key 返回 400 错误。
hash_on | key 指代 | 接受的 key 值 | 示例 |
|---|---|---|---|
vars | NGINX 变量 | 仅限 uri、server_name、server_addr、request_uri、remote_port、remote_addr、query_string、host、hostname、mqtt_client_id，或格式为 arg_<name> 的查询参数。名称不应包含开头的 $。 | remote_addr、arg_device_id |
header | 请求头 | 仅填写请求头名称，不包含 http_ 前缀（支持字母、数字、- 和 _，不区分大小写）。 | X-Api-Key |
cookie | 请求 Cookie | 仅填写 Cookie 名称，不包含 cookie_ 前缀（支持字母、数字、- 和 _）。 | session_id |
consumer | 已完成身份认证的消费者 | 不适用，请省略 key。网关对消费者名称进行哈希。 | — |
vars_combinations | 一个或多个变量 | 任意由 $ 前缀变量引用组成的字符串，按请求解析。 | $request_uri$remote_addr |
备注
hash_on: vars 仅接受上面列出的固定变量集，不接受完整的内置变量列表。要对该集合以外的变量或多个值的组合进行哈希，请使用 hash_on: vars_combinations，并为每个变量添加 $ 前缀，例如 $request_uri$remote_addr。
如果无法为请求解析 key，例如指定的请求头或参数不存在，网关会回退到对 remote_addr 进行哈希。
主要字段
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 负载均衡算法：roundrobin（默认）、chash、least_conn 或 ewma。 |
nodes | array | 静态后端目标的 {host, port, weight, priority} 对象列表。 |
scheme | string | 与后端通信的协议：http、https、grpc 或 grpcs。 |
retries | integer | 请求失败时的重试次数，范围为 0–65535。 |
timeout | object | 超时设置：{connect, send, read}，单位为秒，各项默认值为 60。 |
retry_timeout | number | 继续重试的超时时间，默认值为 0（禁用）。 |
pass_host | string | pass（服务主机）、node（节点主机）或 rewrite（自定义主机）。 |
keepalive_pool | object | 连接池设置：{size, idle_timeout, requests}。 |
hash_on | string | 与 chash 配合使用，选择哈希来源：vars（默认）、header、cookie、consumer 或 vars_combinations。请参阅一致性哈希键。 |
key | string | type 为 chash 时参与哈希的值。除非 hash_on 为 consumer，否则必填；接受的格式取决于 hash_on。请参阅一致性哈希键。 |
服务发现
除了定义静态 nodes，还可以使用服务发现从注册中心动态获取后端目标。
| 字段 | 说明 |
|---|---|
service_name | 注册中心中的服务标识符，例如 <registry_id>/public/group/my-service。 |
discovery_type | 发现机制：kubernetes、nacos 或 consul。 |
健康检查
网关执行健康检查，以识别不健康节点并将其移出负载均衡轮询。
- 主动健康检查：网关定期向后端发送 HTTP 或 TCP 心跳请求。
- 被动健 康检查：网关监控实时流量以识别故障节点，例如观察连续的 5xx 错误。
上游TLS
如果后端要求安全通信，可以配置以下字段：
client_certificate：用于客户端身份认证（mTLS）的证书 ID。ca_certificates：用于验证后端证书的 CA 证书 ID 列表。tls_verify：如果为 true，网关会使用ca_certificates验证后端证书。