访问密钥与密钥组字段
GateLLM 有两类「用户」，务必区分：
- 控制台用户（ConsoleUser）：登录控制台的管理账号（admin / normal_user / monitor）。UI 操作见 控制台用户管理。
- 访问密钥（AccessKey）：调用方调用 API 时带的凭证（
Bearer <key>里的那个 key）。本章讲字段。
两者完全独立：控制台用户管的是「谁能进控制台」，访问密钥管的是「谁能调 API」。
访问密钥与密钥组（Access Keys）
入口：控制台 → 访问密钥。该页有两个页签：Access Keys 和 密钥组。
关系
控制台用户 ──created_by──→ 访问密钥 ──group──→ 密钥组 ──┬→ models[] （能调哪些模型）
├→ load_balancers[] （能调哪些负载均衡器）
└→ mcp_tool_acl （能调哪些 MCP 工具）- 访问密钥归属一个密钥组（
group字段）。 - 密钥组的权限分三个互相独立的维度——模型、负载均衡器、MCP 工具——各有自己的「全部」开关，互不附带：
- 模型列表 决定能访问哪些模型：空 = 无权访问任何模型；
["*"]= 所有模型；具体模型名 = 只能访问列出的（精确匹配模型名，不是别名）。 - 负载均衡器列表 决定能访问哪些负载均衡器：空 = 无权访问任何负载均衡器；
["*"]= 所有负载均衡器；具体名称 = 只能访问列出的（精确匹配负载均衡器名，不是别名）。 - 勾选「所有模型」不附带负载均衡器权限，反之亦然——两个维度要分别勾选。
- 负载均衡器是授权单元：放行一个负载均衡器后，网关不再用「模型列表」去逐个校验该负载均衡器内配置的成员（entry）——该组密钥可到达该负载均衡器的每一个成员，哪怕「模型列表」为空或不含这些模型。把敏感或昂贵的模型放进某负载均衡器的成员里，等于向所有持该负载均衡器权限的密钥开放；若要严格限制某密钥只能用某个模型，应把它配成普通模型并加入「模型列表」，而非放进一个已授权的负载均衡器。
- 模型列表 决定能访问哪些模型：空 = 无权访问任何模型；
- 没有分组的密钥 = 无权访问任何模型与负载均衡器。
管理访问密钥
| 操作 | 怎么做 | 说明 |
|---|---|---|
| 新建 | 「Access Keys」页 → 新建 | 填名称、生成或手填 API 密钥、选分组、启用 |
| 查看完整密钥 | 列表「复制」按钮 | 调 /access-keys/{name}/api-key 取完整值（列表里只显示掩码） |
| 轮换 | 编辑 → 改 API 密钥 | 换一把新值，旧值立即失效 |
| 吊销 | 编辑 → 取消「启用」 | 标记为已吊销，不再生效，记录保留 |
| 删除 | 列表 → 删除 | 彻底移除（建议优先用「吊销」保留审计） |
访问密钥字段
| 字段 | 说明 |
|---|---|
| 名称 | 密钥标识，用于管理与审计；编辑时只读 |
| API 密钥 | 客户端实际带的凭证；列表显示掩码（前后 4 位，如 sk-a***xxxx） |
| 分组 | 所属密钥组，决定模型/MCP 权限 |
| 匿名 | 勾选后该密钥作匿名兜底（见下文），API 密钥字段置空 |
| 启用 | 关闭即吊销 |
| 创建者 | 哪个控制台用户建的；normal_user 只能看到自己建的 |
acl_default_action | allow / deny，无规则命中时的 per-key 回退动作 |
| 模型映射（model_mappings） | 该密钥专属的 from → to 重写规则，可带 when 请求头条件分流；优先级高于所属密钥组的规则；空 = 不映射。映射目标须过出口闸（按真实种类查对应清单：普通模型查 models、负载均衡查 load_balancers），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 配置身份作用域模型映射 |
normal_user角色只能管理自己创建的访问密钥（按created_by过滤），admin 能看全部。控制台用户被删除后，其建的密钥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 回退动作 |
| 模型映射（model_mappings） | 该密钥组共享的 from → to 重写规则（可带 when 请求头条件），作用于组内所有密钥；优先级低于密钥自身规则、高于透传。映射目标须过出口闸（按真实种类查对应清单），源名须在对应清单里（入口闸对真实名按种类查、对虚构名并集回退）。详见 配置身份作用域模型映射 |
匿名访问密钥
设一个访问密钥的「匿名」= true（全局只能有一个）：
- 客户端请求不带
Authorization/x-api-key/x-goog-api-key任何头时，匹配这个匿名密钥。 - 匿名密钥仍需配分组才能获得模型访问权，否则只是「能进门但什么都调不了」。
- 带了无效密钥的请求也会落到匿名分支（等同没带密钥）。
与负载均衡器的关系
负载均衡器是密钥组里独立于模型的授权维度：密钥组的 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：normal_user 看不到别人建的密钥？ 这是设计：normal_user 只能管自己建的密钥。需要管全部让 admin 改你的角色。
Q：想开放免登录访问给内部服务？ 配一个匿名访问密钥（anonymous=true），并给它配一个权限受限的密钥组。注意：匿名意味着任何能连到网关的人都能用，仅适用于受信内网。
Q：访问密钥的 acl_default_action 和密钥组的 acl_default_action 怎么用？ Header ACL 规则全不命中时的回退动作。详见 Header ACL 规则字段。
下一步：Header ACL 规则字段 看 Header ACL 规则的完整字段表；配置 Header ACL 访问规则 看操作步骤与常见用法示例；上游与模型字段 看模型配置；负载均衡字段 看 LB 与密钥组的关系；配置身份作用域模型映射 看按 key / group 重写模型名的操作步骤与运维契约。