API 密钥
一句话：所有 AI 能力的「账号密码本」——每个模型平台一把钥匙；钥匙一停用，挂在它下面的模型会一起从调用候选里消失。
功能在哪
- 菜单路径：AI → 控制台 → API 密钥
- 地址栏路由：
/ai/console/api-key - 主要权限：菜单可见即可看列表；「新增」要
ai:api-key:create，行内「编辑」要ai:api-key:update，「删除」要ai:api-key:delete
界面认识
| 区域 | 作用 | 常用操作 |
|---|---|---|
| 查询区 | 名称 / 平台 / 状态 | 「搜索」「重置」「新增」 |
| 列表 | 序号 / 所属平台 / 名称 / 密钥（掩码）/ 自定义 API URL / 状态（开关）/ 操作 | 状态列开关；行内「编辑」「删除」 |
| 分页 | 每页 20 条 | 翻页 |
密钥列是打码的，页面上读不到明文
列表里密钥只显示首尾几位、中间一串星号；极短的密钥整串都是星号。这不是显示偷懒——密钥在后端加密存储、出接口前脱敏，任何页面与导出都拿不到明文。真密钥只在你自己手里（厂商控制台），丢了就只能重新生成一把再填进来。
常用操作
新增一把密钥
「新增」弹窗五个字段：所属平台、名称、密钥必填，自定义 API URL 选填，状态默认开启。
- 所属平台决定后端走哪一套协议适配（通义、DeepSeek、OpenAI……），选错平台＝请求格式不对，必失败；
- 名称只是台账名，给人看的，建议写成「【厂商】用途」的格式，列表里一眼能认；
- 自定义 API URL 留空＝走平台官方地址；走代理、私有化部署或兼容中转时才填。多数 OpenAI 兼容的中转服务，平台选 OpenAI、地址填中转地址即可。
启用 / 停用：状态列上的开关
开关上直接印着当前状态（绿「启用」/ 灰「禁用」）。两个方向待遇不同：
- 往启用方向拨：直接生效，不打断你；
- 往停用方向拨：弹二次确认，把后果写全了才让你点确定。
停用一把钥匙＝停用挂在它下面的全部模型
确认框原文：「确认禁用密钥「×××」？禁用后挂在它下面的模型会全部从 AI 调用的候选链里剔除（不只是当前这一个模型）；已经钉住这些模型的进行中任务不会切换，而是直接报『本次任务已钉住模型，它现在不可用』。」
也就是说爆炸半径不是这一行，而是模型配置里所有「API 秘钥」列指向这把钥匙的模型。停之前先想清楚有没有正在跑的对话与工作流。
启用会顺带清掉失败冷却，是排障时最快的「重试」
失败冷却按「模型更新时间 | 密钥更新时间」这个配置指纹判活。点一次「启用」会刷新密钥的更新时间，挂在它下面的模型的冷却立即解除、重新进入候选，不必干等 30 分钟。模型刚修好配置想马上验证，「停用再启用」一次比等冷却快得多。
删除
行内「删除」有二次确认。删除只删钥匙本身：模型行还挂着这个引用，模型配置列表的「API 秘钥」列会显示为空，这些模型随之不可用。不再使用的钥匙，建议先停用观察一段时间，确认没人依赖再删。
视角对照
| 视角 | 看到什么 |
|---|---|
租户管理员 docadmin | 全部钥匙与增删改、启停 |
普通员工 salesman01 | 菜单里根本没有「控制台」这一组；直接敲地址是整页 404（路由按菜单动态注册，没授权的路由不存在） |
进阶
- 钥匙与模型是一对多：一把钥匙挂多个模型，模型页的「API 秘钥」列就是引用这里；
- 状态编码全站统一：0 是开启、1 是关闭，与直觉相反，看接口返回值时别读反；
- 自定义 API URL 是排障利器：厂商换代理、公司统一出口时不用改代码，改这一格即可；
- 密钥失效的典型表现：模型页「测试」弹窗报
401 / Unauthorized / AuthenticationError，见模型配置。
常见问题
Q：密钥列为什么全是星号，我想复制原来的密钥怎么办？ A：复制不到，页面不存明文。去厂商控制台重新生成一把，粘进编辑弹窗保存。
Q：编辑弹窗里没改密钥，保存后这把钥匙怎么就失效了？ A：编辑弹窗带出的密钥是掩码串，原样点「确定」等于把掩码当成新密钥写回。改任何字段时，都要把真密钥整串重新粘进「密钥」框再保存。
Q：停用钥匙后，AI 助手还能用吗？ A：看助手实际用的模型挂在哪把钥匙下：挂在这把钥匙上的模型全部出局；若租户里还有别的启用钥匙挂着别的启用模型，助手会走那些模型。
Q：平台下拉里没有我要的厂商？ A：平台清单来自字典 ai_platform，需要管理员在字典管理里补；若该厂商提供 OpenAI 兼容接口，也可以选 OpenAI 平台 + 自定义 API URL 接入。