DeepSeek Harness 的最小权限 API Key:模型调用需要什么、哪些权限不能给
最小权限 API Key 的判据只有一句:它刚好能列模型、发对话、查自己需要的数据,做不了任何管理动作。 多给的每一项权限,在泄露时都会变成额外的处置成本。
最小权限 API Key 的判断原则
Key 能做什么,由签发时的权限决定,不由客户端决定。 同一个界面里,管理员 Key 与只读 Key 看起来一样,能做的事却完全不同。
所以先定用途,再要 Key。 用途没定清楚就发 Key,最后一定是「给大了省事」,然后长期收不回来。
按使用者划分 API Key 权限:个人、CI 与插件
按使用者分类,比按功能分类更好落地。 对照如下:
| 使用者 | 需要的能力 | 不该有的能力 |
|---|---|---|
| 个人开发 | 列模型、对话 | 成员管理、计费修改 |
| CI / 脚本 | 列模型、对话 | 人工后台操作、成员管理 |
| 余额 / 计费插件 | 查额度或用量的只读能力 | 对话、成员管理 |
三类里最容易给大的是插件。 插件只是为了显示数字,却常被直接塞一把主 Key,泄露后影响等同于主账号。
个人开发:按人一把
按人发 Key 是隔离的起点。 做法:
- 一人一把,命名带姓名缩写或工号;
- 只授予列模型与对话;
- 入职发放、离职撤销,形成固定动作;
- 不共用、不转借,出问题能定位到人;
- 定期核对在用 Key 与成员名单是否一致。
按人发不等于按人信任。 它的价值是「能单独撤销」,而不是「更安全」。
CI / 脚本:按环境一把
CI 的 Key 要按「任务」而不是按「人」分配。 特征:
- 只跑固定流程,权限可以压到最低;
- 有明确的调用时间窗与额度上限;
- 泄露后可以整把撤销,不影响开发同学;
- 日志里不打印 Key,也不把 Key 写进构建产物;
- 用完即撤或定期轮换。
CI Key 的最大风险是进入构建缓存与镜像层。 一旦被打进镜像,撤销 Key 也删不掉历史层,只能重建。
插件:只读一把
插件按「它要显示什么」给权限。 做法:
- 余额类插件只需要查询额度,不需要对话;
- 计费类插件只需要读取用量,不需要写;
- 单独发一把 Key,命名标注插件名;
- 插件来源不明时,先不给 Key,或只在隔离环境试;
- 插件卸载后撤销对应 Key。
插件是第三方代码,权限要按第三方对待。 它的更新不受你控制,今天只读不代表下个版本仍然只读。
哪些 API Key 权限不能给
三类权限无论如何都不该出现在普通 Key 上。 分别是:
- 成员与账号管理:能改权限的 Key 等于能提权;
- 计费与充值相关:能改账单的 Key 风险高于能花额度;
- 删除与重置类操作:误操作与恶意操作的结果都不可逆。
判断方法:问「这个动作出错后能不能撤销」。 不能撤销的,一律不给普通 Key。
怎么验证 API Key 权限「刚好够」
用最小流程验证,不用功能清单验证。 五步:
- 用这把 Key 列出可用模型,确认成功;
- 发一条最短消息,确认有输出;
- 查一次该 Key 对应的用量或余额(如果它是插件 Key);
- 尝试一个不该允许的管理动作,确认被拒绝;
- 记录结果,作为这把 Key 的权限说明。
第 4 步是关键。 只验证「能用」不够,还要验证「不能用的确实不能用」,否则你不知道权限边界在哪。
API Key 分发与泄露后的影响
权限越小,泄露后的处置越简单。 对比两种情况:
- 一把主 Key 泄露:要停所有调用、排查所有环境、通知所有使用方;
- 一把只读插件 Key 泄露:撤销一把,其他环境不受影响。
分发时只给「用得到的那一把」。 不要把主 Key 复制给所有人再口头约定「别乱用」,约定拦不住误操作。
共享机器上尤其要注意。 多人共用环境时,Key 的可见范围要单独设计,相关做法在 dsh 多用户与局域网。
下一步:先定 API Key 的权限,再谈轮换
先定权限,再谈轮换。 想看 Key 从创建到撤销的完整流程,读 API Key 全生命周期;想看 Key 报错怎么修,读 API Key 报错排查;想看余额类插件怎么配,读 余额与用量插件。
常见问题
只用来聊天和调模型的 API Key,最少需要「查看模型列表」与「发起对话」两类权限。前者决定客户端能否自动发现模型,后者决定能否实际生成;两者之外的管理类权限都不必给。
CI 与个人开发不应该用同一把 API Key,也不该有相同权限。CI 只需要调用模型与读取模型列表,且应限制调用时间窗与额度;个人 Key 可以按人撤销,互不影响。
余额或计费类插件通常需要一把 Key 查询额度或用量,但不需要对话权限。单独发一把只读的 Key 给插件,既能查数,也能在插件来源不可信时把影响限制住。
验证 API Key 权限是否「刚好够」,方式是只用它跑一次最小流程:列模型、发一条消息、查一次用量。三项都成功说明够用;如果还能做删改类操作,说明权限过大,应换一把更小的。
相关术语
- 最小权限
- 最小权限是只授予完成当前任务所必需的权限,不多给、不预支,目的是缩小凭据泄露后的影响范围。— DeepSeek 官方 API 文档
- 模型列表权限
- 模型列表权限是允许客户端查询可用模型的能力,决定自动发现与模型选择能否工作。— DeepSeek 官方 API 文档
- 对话权限
- 对话权限是允许发起模型调用并接收生成结果的能力,是聊天与大多数插件的基础权限。— DeepSeek 官方 API 文档
- 凭据隔离
- 凭据隔离是按人、按环境或按用途分配不同凭据的做法,使其中一把失效时不影响其他使用方。— DeepSeek Harness 官方文档
来源
- DeepSeek 官方 API 文档· DeepSeek
- DeepSeek Harness 官方文档· deepseek-harness
- dsh CLI README· deepseek-ai