> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/load-balancing-fields · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 负载均衡字段

本章讲负载均衡器的字段表、重试配置、与密钥组的关系、重试相关环境变量。操作步骤（怎么建一个 LB）见 [创建负载均衡器](/zh-CN/howto/setup-load-balancer.md)，粘性会话见 [开启粘性会话](/zh-CN/howto/enable-sticky-session.md)。

## 字段表

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | string | （必需） | 客户端调用时填的模型名 |
| `aliases` | array | `[]` | 额外可用的名字 |
| `entries` | array | （必需） | 节点列表，每项含 `{upstream, model, weight}` |
| `retry_on_different_node` | bool | `true` | 出错时自动重试到其他节点 |
| `extra_config.sticky_session_enabled` | bool | `true` | 粘性会话开关，**嵌在 `extra_config` 下**（非顶层字段）。启用后同一客户端持续路由到同一节点；关闭则每请求按权重重选 |
| `binding_ttl_secs` | u64 | `300` | 绑定有效期（秒）；`0` = 永久绑定 |
| `binding_key_template` | string | — | 自定义绑定键，支持 `{{access_key_hash}}`、`{{header:X}}` |
| `static_bindings` | array | `[]` | 管理员预设的固定绑定 |
| `enabled` | bool | `true` | |

> **`binding_ttl_secs` 与 `LB_AFFINITY_TTL_SECS` 的关系**：两者都是绑定存活秒数、默认都是 300，但层级不同。`binding_ttl_secs` 是**每个 LB 自己的覆盖值**（每个 LB 可不同，`0` = 永久绑定），作用于该 LB 的粘性绑定；`LB_AFFINITY_TTL_SECS` 是全局缺省（见[环境变量配置参考 → 上游连接重试与路由亲和](/zh-CN/reference/configuration.md#upstream-retry-affinity)）。要给某个 LB 单独调粘性时长，改该 LB 的 `binding_ttl_secs`。

### entries 字段

每个 entry 指定一个上游+模型组合及其权重：

```json
{
  "entries": [
    {"upstream": "openai-us", "model": "gpt-4o", "weight": 5},
    {"upstream": "openai-eu", "model": "gpt-4o", "weight": 3},
    {"upstream": "openai-backup", "model": "gpt-4o", "weight": 0}
  ]
}
```

**权重规则**：
- `weight > 0`：正常节点，按权重比例分配请求（如 5:3 表示 62.5%:37.5%）
- `weight = 0`：备用节点，仅在所有正常节点不可用时启用
- 权重范围 0–255

### static_bindings 字段

```json
{
  "static_bindings": [
    {
      "binding_key": "vip-user-hash",
      "upstream": "openai-us",
      "model": "gpt-4o",
      "access_key": "alice-key"
    },
    {
      "binding_key": "team-a-hash",
      "upstream": "openai-eu",
      "model": "gpt-4o",
      "access_key_group": "team-a"
    }
  ]
}
```

- `binding_key`：手动指定的绑定键值（不是模板，直接写实际值）
- `upstream` + `model`：固定路由目标
- `access_key` / `access_key_group`：限定到某密钥或密钥组（可选）

## 重试配置

故障转移由重试相关环境变量控制（无状态、每请求独立，无跨请求失败记忆）：

| 变量 | 默认值 | 作用 |
|------|--------|------|
| `MAX_UPSTREAM_RETRIES` | `3` | 单请求最大重试次数（跨所有凭据累计） |
| `MAX_KEY_ROTATIONS` | `0` | 最多轮换多少把不同的上游凭据；`0` = 不限 |

> 跨所有重试层（凭据轮换 + LB 节点故障转移）的总尝试上限固定为 6，硬顶防止 N×M 放大，不通过环境变量开放。

当 `retry_on_different_node = true`（默认）时：

1. 请求发到当前选中节点
2. 节点返回可重试错误（5xx、连接超时、读取超时；4xx 与解析错误不可重试，直接失败）
3. 网关自动选下一个节点重试
4. 重试受 `MAX_UPSTREAM_RETRIES` 与固定的总尝试上限双重约束

当所有节点都失败（被排除）或没有可用节点时，网关在重试预算耗尽后返回 `503`，响应携带最后一次错误。

> **流式响应限制**：流式重试仅在发送第一个 SSE 数据块之前尝试。一旦客户端开始接收数据，不支持中途换节点。

## 与密钥组的关系

负载均衡器是密钥组里独立于模型的授权维度：密钥组的 `load_balancers` 列表需包含该负载均衡器的名称（或 `"*"`），密钥才能通过 LB 调用。`models` 维度只管普通模型，「所有模型」不会附带放行负载均衡器：

```json
{
  "name": "full-access",
  "models": ["*"],
  "load_balancers": ["gpt-4o-ha"]
}
```

控制台 → 访问密钥 → 密钥组 → 编辑 → 「负载均衡器」子页签勾选对应 LB。详见 [访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)。

## 常见问题

**Q：所有节点都失败了怎么办？**
网关在重试预算内逐个尝试节点；全部失败后返回 503，响应携带最后一次错误。若上游确实全挂，检查上游配置和连接。

**Q：流式请求中途切换节点吗？**
不支持。流式重试仅在发送第一个 SSE 数据块之前尝试。一旦客户端开始接收数据，即使节点故障也不会中途换节点。

**Q：权重设为 0 的备用节点什么时候会被用到？**
仅在所有 `weight > 0` 的正常节点都不可用时。正常节点恢复后，流量自动切回。

**下一步**：[创建负载均衡器](/zh-CN/howto/setup-load-balancer.md) 看操作步骤；[开启粘性会话](/zh-CN/howto/enable-sticky-session.md) 看绑定键与静态绑定；[环境变量配置参考](/zh-CN/reference/configuration.md) 看全部环境变量；[访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md) 看密钥组的 LB 维度。