访问密钥与密钥组字段
GateLLM 有两类「用户」，务必区分：
- 控制台用户（ConsoleUser）：登录控制台的管理账号，角色为 admin 或 monitor（
normal_user不是控制台登录角色）。UI 操作见 控制台用户管理。 - 访问密钥（AccessKey）：调用方调用 API 时带的凭证（
Bearer <key>里的那个 key）。本章讲字段。
两者完全独立：控制台用户管的是「谁能进控制台」，访问密钥管的是「谁能调 API」。
访问密钥与密钥组（Access Keys）
入口：控制台 → 访问密钥。该页有三个页签：Access Keys、密钥组 和 访问规则（Header ACL，字段见 Header ACL 规则字段）。
关系
控制台用户 ──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），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 配置身份作用域模型映射 | 空（不映射） |
| 月度配额（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 配置） | 空 |
acl_default_action | allow / deny，无规则命中时的 per-group 回退动作 | 未设（回退到全局 Allow） |
| 模型映射（model_mappings） | 该密钥组共享的 from → to 重写规则（可带 when 请求头条件），作用于组内所有密钥；优先级低于密钥自身规则、高于透传。映射目标须过出口闸（按真实种类查对应清单），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 配置身份作用域模型映射 | 空（不映射） |
| 月度配额（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 维度只管普通模型，「所有模型」不会附带放行负载均衡器：
{
"name": "full-access",
"models": ["*"],
"load_balancers": ["gpt-4o-ha"]
}控制台 → 访问密钥 → 密钥组 → 编辑 → 「负载均衡器」子页签勾选对应 LB。详见 负载均衡字段。
常见问题
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 规则字段。
下一步：Header ACL 规则字段 看 Header ACL 规则的完整字段表；配置 Header ACL 访问规则 看操作步骤与常见用法示例；上游与模型字段 看模型配置；负载均衡字段 看 LB 与密钥组的关系；配置身份作用域模型映射 看按 key / group 重写模型名的操作步骤与运维契约。