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


# 多租户隔离

多租户隔离的目标是让每个租户只能到达被授权的模型、看到自己的用量与费用、受自己的限流约束。网关用「密钥组 + 访问密钥 + Header ACL + 模型映射 + 限流」五层组合实现。

## 隔离的五个维度

| 维度 | 机制 | 配置处 |
|------|------|--------|
| 模型可达 | 密钥组的 `models` 列表 | 控制台 → 密钥组 |
| 负载均衡器可达 | 密钥组的 `load_balancers` 列表 | 控制台 → 密钥组 |
| 客户端身份 | 访问密钥 + Header ACL 规则 | 控制台 → 访问密钥 / Header ACL |
| 模型名重写 | 访问密钥/密钥组的 `model_mappings`（`from→to`，可按 `when` 请求头条件分流） | 控制台 → 访问密钥 / 密钥组 |
| 用量约束 | 每密钥限流（RPM / 并发 / TPM） | 控制台（密钥/组 `rate_limit` + `max_concurrency`，全局默认在 `/settings/rate-limit`） |

## 用密钥组切分模型与负载均衡器

每个租户一个密钥组，`models` 列出该租户能调的模型名，`load_balancers` 列出能调的 LB 名。租户的访问密钥挂到对应密钥组。字段见 [访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)。

::: warning LB 是独立的授权维度
密钥组的 `models` 与 `load_balancers` 是两个独立列表。「所有模型」（`*`）**不**附带 LB 权限，反之亦然——两个维度要分别勾选。这是多租户场景最常见的配错点。详见 [创建负载均衡器](/zh-CN/howto/setup-load-balancer.md) 的「与密钥组的关系」。
:::

## 按租户重写模型名（身份模型映射）

让不同租户请求同一个客户端模型名时被路由到不同上游，用身份作用域模型映射：在访问密钥或密钥组上声明 `from → to` 规则，网关在入口闸之后自动重写模型名，还可加 `when` 请求头条件按租户分流（如带 `X-Tenant: vip` 走优质线路）。映射目标仍要过该身份的权限白名单——配映射不等于发放权限。完整语义、通配符、优先级与运维契约见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md)。

## 负载均衡器是授权单元（易错点） {#lb-is-auth-unit}

网关只在请求进入时校验一次 LB 名称是否在密钥组的 `load_balancers` 白名单内，**不会**再用 `models` 列表逐个校验该 LB 内的 entry。也就是说，一旦密钥组放行了某 LB，该组密钥就能到达该 LB 里的**每一个** entry。

::: danger 严格隔离时别用 LB
若要严格限制某租户只能用某个模型，把它配成**普通模型**并加入该租户密钥组的 `models` 列表，**不要**放进一个已被多租户授权的 LB——LB 的 entry 集合是所有持权密钥的可达并集。
:::

## 用请求头规则区分客户端

同一密钥组下想按客户端进一步分流，用 Header ACL 规则按请求头（如 `X-Tenant`）匹配，做白名单/黑名单。规则字段见 [Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)，配置示例见 [配 Header ACL](/zh-CN/howto/configure-header-acl.md) 的白名单模式。

## 每租户限流与配额

- 每访问密钥的 RPM / 并发 / TPM 上限在控制台配置——密钥/组的 `rate_limit`（RPM/TPM）与 `max_concurrency` 字段，另有全局默认 `/settings/rate-limit`（见 [审计与安全配置](/zh-CN/reference/audit-and-security-config.md)）。
- 多实例部署时限流走 Redis 共享，否则每实例独立、阈值被分散。见 [做到高可用](/zh-CN/usecases/high-availability.md#multi-instance-shared-state)。

## 计费口径

[定价与计费](/zh-CN/howto/setup-pricing-and-billing.md) 配置价格快照后，月度账单按模型 + 访问密钥维度汇总。每个租户用自己的密钥组与访问密钥，账单天然按租户拆分。

## 常见问题

**Q：同一把访问密钥能给多个租户用吗？**
不能。访问密钥挂在一个密钥组上，权限由该组决定。多租户要每租户独立的密钥组与访问密钥。

**Q：密钥组的 `models` 写别名行吗？**
不行。密钥组的模型 ACL 只匹配**规范名称**（`name` 字段），不解析别名。见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 的「模型别名与隐藏名称」。

**Q：怎么让某租户的限流不互相干扰？**
每租户独立访问密钥，限流按密钥计。多实例配 Redis 让限流跨实例共享。

**下一步**：[配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) 看按租户重写模型名；[满足合规与审计要求](/zh-CN/usecases/compliance-audit.md) 看合规；[访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md) 看字段；[访问控制设计](/zh-CN/practices/access-control.md) 看设计原则。