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


# 访问密钥与密钥组字段

GateLLM 有两类「用户」，务必区分：

- **控制台用户（ConsoleUser）**：登录控制台的管理账号，角色为 admin 或 monitor（`normal_user` 不是控制台登录角色）。UI 操作见 [控制台用户管理](/zh-CN/console/user-management.md)。
- **访问密钥（AccessKey）**：调用方调用 API 时带的凭证（`Bearer <key>` 里的那个 key）。本章讲字段。

两者完全独立：控制台用户管的是「谁能进控制台」，访问密钥管的是「谁能调 API」。

## 访问密钥与密钥组（Access Keys）

入口：控制台 → **访问密钥**。该页有三个页签：**Access Keys**、**密钥组** 和 **访问规则**（Header ACL，字段见 [Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)）。

### 关系

```text
控制台用户 ──created_by──→ 访问密钥 ──group──→ 密钥组 ──┬→ models[]         （能调哪些模型）
                                                        ├→ load_balancers[] （能调哪些负载均衡器）
                                                        └→ mcp_tool_acl     （能调哪些 MCP 工具）
```

- 访问密钥归属一个或多个**密钥组**（`groups` 字段，表单里复选；多组时各维度取并集、费用配额取最宽，见「费用配额」）。
- 密钥组的权限分三个**互相独立**的维度——模型、负载均衡器、MCP 工具——各有自己的「全部」开关，互不附带：
  - **模型列表** 决定能访问哪些模型：空 = 无权访问任何模型；`["*"]` = 所有模型；具体模型名 = 只能访问列出的（精确匹配模型名，不是别名）。
  - **负载均衡器列表** 决定能访问哪些负载均衡器：空 = 无权访问任何负载均衡器；`["*"]` = 所有负载均衡器；具体名称 = 只能访问列出的（精确匹配负载均衡器名，不是别名）。
  - 勾选「所有模型」**不**附带负载均衡器权限，反之亦然——两个维度要分别勾选。
  - **负载均衡器是授权单元**：放行一个负载均衡器后，网关不再用「模型列表」去逐个校验该负载均衡器内配置的成员（entry）——该组密钥可到达该负载均衡器的**每一个**成员，哪怕「模型列表」为空或不含这些模型。把敏感或昂贵的模型放进某负载均衡器的成员里，等于向所有持该负载均衡器权限的密钥开放；若要严格限制某密钥只能用某个模型，应把它配成**普通模型**并加入「模型列表」，而非放进一个已授权的负载均衡器。
- 没有分组的密钥 = 无权访问任何模型与负载均衡器。

### 管理访问密钥

| 操作 | 怎么做 | 说明 |
|------|--------|------|
| 新建 | 「Access Keys」页 → 新建 | 填名称、生成或手填 API 密钥、选分组、启用 |
| 查看完整密钥 | 列表「复制」按钮 | 调 `/access-keys/{name}/api-key` 取完整值（列表里只显示掩码） |
| 轮换 | 编辑 → API 密钥右侧「轮换」 | 确认后换新值，旧值立即失效；新密钥仅在成功弹窗里显示一次，请立即复制（其他属性保持不变） |
| 吊销 | 编辑 → 取消「启用」 | 标记为已吊销，不再生效，记录保留 |
| 删除 | 列表 → 删除 | 彻底移除（建议优先用「吊销」保留审计） |

### 访问密钥字段

| 字段 | 说明 | 默认值 |
|------|------|--------|
| 名称 | 密钥标识，用于管理与审计；编辑时只读 | （必需） |
| API 密钥 | 客户端实际带的凭证；列表显示掩码（前后 4 位，如 `sk-a***xxxx`） | 点「生成」自动产生 |
| 分组 | 所属密钥组（复选，可属多个组；多组时模型/LB/MCP 权限取并集），决定模型/MCP 权限 | 无分组（= 无权访问任何模型） |
| 标签（tags） | 自由格式的组织标签，可多个；用于控制台筛选与搜索（搜索框也匹配标签），纯标注不影响权限。可从历史标签直接选，也可输入新建 | 空 |
| 匿名 | 勾选后该密钥作匿名兜底（见下文），API 密钥字段置空 | `false` |
| 启用 | 关闭即吊销 | `true` |
| 创建者 | 哪个控制台用户建的 | 当前登录的控制台用户 |
| `acl_default_action` | `allow` / `deny`，无规则命中时的 per-key 回退动作 | 未设（回退到组、再到全局 Allow） |
| 模型映射（model_mappings） | 该密钥专属的 `from → to` 重写规则，可带 `when` 请求头条件分流；优先级高于所属密钥组的规则。映射目标须过出口闸（按真实种类查对应清单：普通模型查 `models`、负载均衡查 `load_balancers`），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) | 空（不映射） |
| 月度配额（monthly_quota） | 该 key 每月（UTC 自然月）费用上限（USD 金额）。留空 = 继承下级；填值必须 > 0。详见下文「费用配额」 | 空（继承下级） |
| 日度配额（daily_quota） | 该 key 每日（UTC 自然日）费用上限（USD 金额）。同月度配额语义，与月度独立判定 | 空（继承下级） |

> 访问密钥在控制台里由 admin 查看与管理（`normal_user` 不登录控制台，只持有/使用 API key）。控制台用户被删除后，其建的密钥 `created_by` 置空，变成遗留密钥（仅 admin 可见）。

### 管理密钥组

| 操作 | 怎么做 | 说明 |
|------|--------|------|
| 新建 | 「密钥组」页 → 新建 | 填名称、选模型、选负载均衡器、配 MCP 工具 ACL |
| 编辑 | 列表 → 编辑 | 四个子页签：模型 / 负载均衡器 / MCP / 模型映射 |
| 删除 | 列表 → 删除 | 若有密钥引用该组需先改密钥的分组 |

### 密钥组字段

| 字段 | 说明 | 默认值 |
|------|------|--------|
| 名称 | 分组标识 | （必需） |
| 模型 | 可访问的模型列表；按上游分组展示，「All Models」= `*` 全选。与负载均衡器维度互不影响 | 空（无权限） |
| 负载均衡器 | 可访问的负载均衡器列表；「All Load Balancers」= `*` 全选。「All Models」不含负载均衡器，需在此单独勾选 | 空（无权限） |
| MCP | `allowed_tools` / `denied_tools` / `allowed_tags`，控制可调用的 MCP 工具（详见 [MCP 配置](/zh-CN/reference/mcp-config.md)） | 空 |
| `acl_default_action` | `allow` / `deny`，无规则命中时的 per-group 回退动作 | 未设（回退到全局 Allow） |
| 模型映射（model_mappings） | 该密钥组共享的 `from → to` 重写规则（可带 `when` 请求头条件），作用于组内所有密钥；优先级低于密钥自身规则、高于透传。映射目标须过出口闸（按真实种类查对应清单），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) | 空（不映射） |
| 月度配额（monthly_quota） | 组内每个 key 继承的月度（UTC 自然月）费用上限（USD 金额）。**非共享总账**——是组内每个 key 各自一个上限。留空 = 该组不参与折叠（不视为无穷大）；填值必须 > 0 | 空（不参与折叠） |
| 日度配额（daily_quota） | 组内每个 key 继承的日度（UTC 自然日）费用上限。同月度配额语义，与月度独立判定 | 空（不参与折叠） |

## 匿名访问密钥

设一个访问密钥的「匿名」= true（全局只能有一个）：

- 客户端请求**不带** `Authorization` / `x-api-key` / `x-goog-api-key` 任何头时，匹配这个匿名密钥。
- 匿名密钥仍需配分组才能获得模型访问权，否则只是「能进门但什么都调不了」。
- 带了**无效**密钥的请求也会落到匿名分支（等同没带密钥）。

## 费用配额

费用配额（cost quota）限制每个访问密钥的货币消费。配额统一按 **USD** 计价执法——系统级单一汇率源 `FxCache`（`/fx-rates` API 暴露，三级回退：运维 config 覆盖 > Frankfurter ECB 在线 > 静态兜底表）把各币种花费折算成 USD 后累加。配置入口有三层，均在控制台 **访问密钥** 页与 **计费 → 配额** 页签：

- **per-key**：在 access key 表单的「费用配额」区填月度 / 日度上限。
- **per-group**：在密钥组表单填——语义是「组内每个 key 继承的上限」，**不是组内共享一个总账**。
- **全局默认**：**计费 → 配额** 页签编辑 `monthly_limit` / `daily_limit`，对未设自身限额的 key 生效。

### 三层优先级

每个周期独立解析有效限额：

```
per-key || max(已设限成员组的限额，未设限的组不参与) || 全局默认
```

- **月度与日度是两个独立周期**，各自取值、各自判定，任一触顶即拒绝该 key 的后续请求（429）。
- **组限语义 = 组内每个 key 继承的 per-key 上限**（非共享总账）。一个 key 属于多个组、且多组都设了限时取**最宽（max）**——例：team-a=$100、team-b=$500，key 属两组 → 有效 $500。
- **未设限的成员组不参与折叠**（不视为无穷大）——否则一个设了限的 key 只要再进一个没设限的组就立刻无限了。
- 成员组全未设限 → 回落全局默认；全局也没设 → 该周期不限。
- 三层都没设 → 完全不限。

### 取值与周期边界

- 取值：留空 / `null` = 继承下级（key→组→全局），**不是**该窗口无限；填值必须 > 0（`0` 与负数在写侧拒绝，前端同步校验）。想表达"某窗口无限"需在比它高的层级设限、本层留空——或接受"三层都无法表达单窗口无限而其他窗口有限"的取舍。
- 周期边界：**UTC 自然月**（每月 1 日 00:00 UTC 重置）与 **UTC 自然日**（每日 00:00 UTC 重置）。与统计/账单口径一致。
- 限额维度是 **USD 金额**：`record_cost` 按 `pricing.currency` 查 `FxCache` 折成 USD 微单位累加 inflight；`refresh_once` 读 `cost_breakdown`（分币种）各乘汇率求和。前端账单页的 `≈USD` 与配额执法共用同一后端汇率源。Excel 导出仍按币种分列（不跨币种求和，不变）。

### 429 与软限

- 任一周期触顶返回 **429**，错误类型 `quota_exceeded`，报文指明是月度还是日度窗口、限额与已用、重置时间。
- **仅日度窗口**带 `Retry-After` 头（≤86400s）；月度可达约 31 天，对客户端无意义且可能误处理，报文已含重置时间，不发该头。
- 软限：用量 = TTL 缓存的 DB 周期总花费（USD，`refresh_once` 读 `cost_breakdown` 分币种各乘汇率求和）+ 进程内在途累计（USD，`record_cost` 同步折算），约每 30s（日度）/ 5min（月度）刷新；接受分钟级超发窗口。多实例（PG 模式）下 DB 快照共享、在途各实例本地，跨实例同样轻微超发，均在软限语义内接受。ECB 日频汇率，同一币种模型整天按当天汇率折算；缺汇率时 fail-safe 少计（跳过该请求累加，不误拒）。

### 注意事项

- **匿名 key**：匿名流量在统计里本就合并为单一 `"anonymous"` 桶，全部匿名流量共享同一份限额（全局默认对匿名生效）。
- **改 key 名**：用量按 name 聚合，改 key 名后旧用量与新名无法关联（与现存统计语义一致）。
- **`count_tokens` 豁免**：不计费、不进配额判定。
- **模型试调（tryme）**：不进准入检查缝，消耗记入 SystemDiagnostics 假桶，永不计入任何真实 key 的配额。
- **未计价模型**（无 pricing）：cost 0，不耗配额（与账单口径一致）。

## 与负载均衡器的关系

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

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

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

## 常见问题

**Q：客户端报 403 model_access_denied，但密钥是对的？**
密钥所在的密钥组「模型」列表没包含要调的模型。到「密钥组」把该模型加进去，或改成 `*`。调**负载均衡器**报 403 同理——负载均衡器是独立维度，检查组里的「负载均衡器」列表（「All Models」不会附带放行负载均衡器）。

**Q：怎么让某个密钥只能调某几个模型？**
新建一个密钥组，模型列表只填那几个，把密钥的分组指向它。

**Q：访问密钥列表里只看到 `sk-a***xxxx`，怎么拿完整值？**
点该行「复制」按钮，会调接口取完整密钥并复制到剪贴板。匿名密钥不支持取完整值。

**Q：谁能在控制台查看/管理访问密钥？**
控制台里访问密钥由 admin 查看与管理。`normal_user` 不登录控制台——它只持有/使用 API key（调 API 时带的凭证）。

**Q：想开放免登录访问给内部服务？**
配一个匿名访问密钥（anonymous=true），并给它配一个权限受限的密钥组。注意：匿名意味着任何能连到网关的人都能用，仅适用于受信内网。

**Q：访问密钥的 `acl_default_action` 和密钥组的 `acl_default_action` 怎么用？**
Header ACL 规则全不命中时的回退动作。详见 [Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)。

**下一步**：[Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md) 看 Header ACL 规则的完整字段表；[配置 Header ACL 访问规则](/zh-CN/howto/configure-header-acl.md) 看操作步骤与常见用法示例；[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看模型配置；[负载均衡字段](/zh-CN/reference/load-balancing-fields.md) 看 LB 与密钥组的关系；[配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) 看按 key / group 重写模型名的操作步骤与运维契约。