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


# 批量配置（模型与负载均衡器）

批量配置把多个**模型**与**负载均衡器**的变更攒成一批：先暂存（不写库）、预览这批操作对命名空间的影响（释放/占用/冲突）、确认后**原子提交**——要么全部生效，要么一条都不写。适合一次性迁移、重命名一组互相引用的实体等场景，避免逐个保存造成的中间不一致状态。

入口：控制台 → **工具** → **批量配置** 页签（仅 admin 可见）。

> v1 范围：只有**模型**与**负载均衡器**参与批量（它们是共享全局唯一命名空间的实体）。上游、访问密钥等其余实体仍走各自的单条编辑页。

## 工作流程

```
暂存操作（新建/更新/重命名/删除，可多条）
    → 预览（POST /config/batch/preview，命名空间影响 + 完整冲突集，不写库）
    → 确认无误 → 提交（POST /config/batch，一个事务原子提交）
```

1. **暂存操作**：在批量配置页对模型 / 负载均衡器做新建、编辑、重命名、删除。每步只是**暂存**进待提交列表，不会立即写库——页面会列出当前暂存的全部操作。
2. **预览影响**：提交前先看预览——这批操作会**释放**哪些名字、**占用**哪些名字、与现有配置有无**冲突**。预览是只读干跑，不落任何数据。
3. **原子提交**：确认无冲突后提交。整批在**一个事务**里写入；任何一个操作冲突或失败，**整批回滚**，不会出现写了一半的状态。

> **重命名怎么来的**：编辑某个已有实体时改了它的名字，暂存时自动识别为一次**重命名**操作（旧名释放、新名占用），无需单独选「重命名」。

## 预览读什么

预览给出这批操作的命名空间影响：

- **释放（freed）**：本批会空出来的名字（如删除、重命名让出的旧名）。
- **占用（taken）**：本批要占用的名字（如新建、重命名的新名）。
- **冲突（conflicts）**：与现有配置的命名冲突。预览返回**完整冲突集**（不是只报第一个），便于一次看清所有问题。

无冲突时提示「该批量可提交」；有冲突则先解决再提交。

## Console API

| 端点 | 说明 |
|------|------|
| `POST /console/api/config/batch/preview` | 干跑一批操作，返回命名空间影响与冲突集；不写库、不加锁 |
| `POST /console/api/config/batch` | 原子提交一批操作（一个事务，任一冲突即整批回滚） |

每个操作是一个带 `kind` 标签的对象（`create` / `update` / `rename` / `delete`），`entity_type` 取 `models` / `load_balancers`，`entity` 是与单条新建/编辑相同的表单载荷。提交成功后触发配置 reload 并跨实例广播。

## 常见问题

**Q：暂存了一半不想提交了怎么办？**
暂存的操作只在当前页面的待提交列表里，没写库；离开页面或清空列表即放弃，不影响线上配置。

**Q：提交时报冲突？**
预览阶段就会列出完整冲突集（名字被占用等）。按提示改名或调整后再提交。原子提交保证冲突时不会有半套写入。

**Q：能批量改访问密钥 / 上游吗？**
v1 只有模型与负载均衡器参与批量。其余实体在各自的管理页单条操作。

**下一步**：[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看模型字段；[负载均衡字段](/zh-CN/reference/load-balancing-fields.md) 看 LB 字段；[控制台登录与角色](/zh-CN/console/login-and-roles.md) 看页面权限。