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


# 创建负载均衡器

当同一个模型有多个上游/节点可用时，负载均衡器（LoadBalancer）在它们之间分发请求，提供故障转移、权重分配和粘性会话。

入口：控制台 → **负载均衡器**（仅 admin）。

前置：**已配好至少一个上游及其模型**——LB 的每个 entry 都引用一个「上游 + 模型」组合，没有可引用的上游就建不了有效的 entry。上游怎么配见 [快速部署](/zh-CN/quickstart/docker-single-node.md)。

## 核心概念

> （原文此处为负载均衡概念图，详见上方来源链接对应的渲染页。）

- **LoadBalancer 本身就是一个"模型名"**：客户端用 LB 的 `name`（如 `gpt-4o-ha`）调用，跟调用普通模型一样。`entries` / `weight` 的含义见 [多上游负载均衡](/zh-CN/quickstart/multi-upstream-load-balancing.md#core-concepts)。

## 创建负载均衡器

控制台 → 负载均衡器 → 新建：

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| 名称 | string | （必需） | 客户端调用时填的模型名 |
| 别名 | string[] | `[]` | 额外可用的名字 |
| entries | array | （必需） | 节点列表，每项含 `{upstream, model, weight}` |
| 出错换节点 | bool | `true` | `retry_on_different_node`，出错时自动重试到其他节点 |
| 粘性会话 | bool | `true` | 启用后同一客户端持续路由到同一节点（默认开启） |
| 粘性 TTL | u64 | `300` | 绑定有效期（秒）；`0` = 永久绑定 |
| 绑定键模板 | string | — | 自定义绑定键，支持 `{{access_key_hash}}`、`{{header:X}}` |
| 静态绑定 | array | `[]` | 管理员预设的固定绑定 |
| 启用 | bool | `true` | |

## Entries 配置

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

在 LB 表单的**条目**区点 **+ 添加条目**，逐行填（上游是下拉选、模型下拉随上游联动只列该上游下的模型、权重填 0–255）：

| 上游 | 模型 | 权重 |
|------|------|------|
| `openai-us` | `gpt-4o` | `5` |
| `openai-eu` | `gpt-4o` | `3` |
| `openai-backup` | `gpt-4o` | `0`（备用） |

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

## 验证

保存后用 LB 的 `name` 当模型名发一条请求，确认能路由到某个节点：

```bash
curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-ha","messages":[{"role":"user","content":"hi"}]}'
```

收到回复即 LB 生效。再到控制台 → 负载均衡器 → 点该 LB → **Entries** 面板，确认各节点状态为 healthy、有效权重等于配置权重。若报 403，是密钥组的 `load_balancers` 维度没放行该 LB（见[与密钥组的关系](#key-group-relationship)）。

## 故障转移

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

1. 请求发到当前选中节点
2. 节点返回可重试错误（5xx、连接超时、读取超时）
3. 网关自动选下一个节点重试
4. 重试次数受 `MAX_UPSTREAM_RETRIES` 控制

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

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

## 与密钥组的关系 {#key-group-relationship}

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

控制台 → 访问密钥 → 密钥组 → 新建 `full-access`：**模型**页签点「所有模型」（`*`）→ **负载均衡器**页签勾选 `gpt-4o-ha`。

**LB 是授权单元**：网关只在请求进入时校验一次 LB 名称是否在密钥组的 `load_balancers` 白名单内，**不会**再用密钥组的 `models` 列表去逐个校验该 LB 内配置的 entry。也就是说，一旦密钥组放行了某个 LB，该组密钥就能到达该 LB 里配置的**每一个** entry——哪怕这些密钥的 `models` 列表为空、或不含这些 entry 的模型名。

> **配 LB 时的注意点**：把一个模型放进某 LB 的 entry，等于向所有持该 LB 权限的密钥开放该模型。LB 的 entry 集合 = 所有持该 LB 权限密钥的可达并集。若要严格限制某密钥只能用某个模型，应把它配成**普通模型**并加入该密钥组的 `models` 列表，而非放进一个已被授权的 LB。

控制台 → 访问密钥 → 密钥组 → 编辑 → 「负载均衡器」子页签勾选对应 LB。

## 完整案例

OpenAI 高可用（双上游 + 备用）与多供应商故障转移（OpenAI + Azure）两个可复制案例，含完整 JSON 配置与 curl 调用，见 [多上游负载均衡](/zh-CN/quickstart/multi-upstream-load-balancing.md)。本页只讲建 LB 的字段与故障转移/授权机制。

## 常见问题

**Q：LB 的 name 和普通模型的 name 冲突了怎么办？**
LB 和普通模型共享全局唯一名称空间。不能有同名的 LB 和模型。

**Q：怎么让某个密钥不走 LB，直接调某个上游？**
建一个普通模型指向该上游，密钥组的 models 列表包含这个普通模型即可。LB 和普通模型可以同时存在。

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

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

**Q：怎么监控 LB 各节点的状态？**
控制台 → 负载均衡器 → 点该 LB → Entries 面板，看每个节点的状态（healthy/unavailable）与有效权重（等于配置权重）。

**下一步**：[负载均衡字段](/zh-CN/reference/load-balancing-fields.md) 看完整字段表与重试配置；[开启粘性会话](/zh-CN/howto/enable-sticky-session.md) 看粘性会话与静态绑定；[多上游负载均衡 quickstart](/zh-CN/quickstart/multi-upstream-load-balancing.md) 看场景化示例。