DeepSeek Harness 的 API Key 全生命周期:创建、落盘、轮换、撤销与残留检查
DeepSeek Harness 的 API Key 有五个阶段:创建、落盘、使用、轮换、撤销,每个阶段都有各自的失败模式,配一次能用只是第一阶段结束。 多数「Key 突然失效」「卸载后还有调用」的问题,都出在轮换与撤销没做完整。
为什么要把 API Key 当生命周期管理
Key 是凭据,不是配置项;配置写错可以改,凭据泄露只能撤销。 五个阶段对应五个问题:这把 Key 给谁用、存在哪、谁会读到、怎么换、怎么作废,任何一环缺失都会在事故时才暴露。
DeepSeek Harness API Key 的创建与落盘:命名与存放
Key 的第一条规则是可区分。 命名与分配方式决定后续能不能单独撤销:
- 一个环境一把:本地开发、测试、生产各一把,不要共用;
- 一个用途一把:日常会话、CI、插件(余额或计费类)分开;
- 命名带信息:包含环境与用途,例如
dsh-dev-local、dsh-ci-nightly; - 记录归属:谁申请的、什么时候创建、用在哪台机器;
- 不把 Key 写进示例配置或文档。
共用的代价是撤不干净。 一把 Key 给五个人用,泄露时只能全停,所有人都受影响。
创建只是第一步,第二步是决定它落在哪里。DeepSeek Harness 把凭据与普通配置分开存放。 默认目录是 DSH_HOME(~/.dsh):
| 内容 | 典型位置 | 说明 |
|---|---|---|
| 普通配置 | settings.yaml | 模型、端口、界面等非敏感项 |
| 凭据 | 凭据文件 | Key 等敏感信息,与配置分离 |
| 会话 | sessions/ | 对话记录,可能引用模型名 |
| 插件 | profiles/ | 依赖与插件配置 |
文件权限要收紧。 确认只有当前用户可读,别用 chmod 777 图省事;共享机器上权限过宽等于公开 Key。
改动后要重启验证。 只改文件不重启,运行中的进程可能仍持有旧值,表现为「明明改了却不生效」。
DeepSeek Harness 里谁会读到这把 API Key
不止主程序会读 Key,插件与脚本也可能读。 三类常见读取方:
- 模型调用层:发起对话时使用;
- 余额与计费类插件:查询额度或用量;
- 自定义脚本与 CI:通过环境变量注入。
排查时最容易泄露 Key 的三个地方: 终端历史、配置导出文件、截图。贴日志前先搜一遍 sk- 前缀并替换。
插件按最小权限使用。 只查余额的插件不需要对话权限,能单独发一把就单独发。
轮换 API Key:先加后删
轮换的目标是不中断,所以顺序固定。 五步:
- 在服务商后台创建新 Key,命名带日期;
- 把新 Key 写入凭据文件或环境变量,保留旧 Key;
- 重启服务,发一条最小消息验证成功;
- 确认插件与 CI 也切到新 Key,各自验证一次;
- 全部通过后,在后台撤销旧 Key。
先删后加会造成空窗。 一旦新 Key 还没生效,服务直接不可用,排查时又分不清是 Key 问题还是网络问题。
轮换后观察一天用量。 新旧 Key 的调用量应出现交接,旧 Key 用量归零才说明切换彻底(来源)。
API Key 撤销、残留检查与泄露止损
撤销 Key 不等于清理本机。 两件事都要做:
- 在服务商后台撤销或删除 Key,确认状态变为失效;
- 清理本机凭据文件里的旧值,别只注释掉;
- 检查终端历史、CI 变量、容器镜像与环境变量;
- 检查备份与配置导出文件;
- 卸载场景下,确认数据目录是否被保留。
卸载不会让 Key 失效。 程序没了,凭据还在,别把卸载当成安全动作。残留检查的完整清单在 卸载后 API Key 怎么办。
残留之外还有更急的情况:泄露。先止血,再排查,最后复盘,顺序不能反:
- 立即在后台撤销泄露的 Key;
- 启用备用 Key,恢复服务;
- 查看该 Key 的用量与调用记录,判断影响范围;
- 清理泄露源:日志、截图、仓库、聊天记录;
- 复盘为什么会泄露,调整命名与分发方式。
不要先删日志再撤销。 日志是判断影响范围的依据,撤销才是止血动作,两者顺序反了会失去证据。
API Key 一页检查表与下一步
五个阶段,各一条底线。 对照:
| 阶段 | 底线 |
|---|---|
| 创建 | 一环境一把,命名可追溯 |
| 落盘 | 权限仅本人可读 |
| 使用 | 插件按最小权限 |
| 轮换 | 先加后删,两端验证 |
| 撤销 | 后台失效 + 本机清理 |
五条都做到,才算把 Key 管住。 只做创建与落盘,等于把风险留到以后。
下一步:先分清 API Key 的权限,再谈管理。 想看 Key 报错怎么修,读 API Key 报错排查;想看卸载后的凭据处理,读 卸载后 API Key 怎么办;想看提供方怎么配,读 模型提供方怎么配。
常见问题
DeepSeek Harness 的凭据默认落在 DSH_HOME 下的凭据文件里,与 settings.yaml 分开存放。正常日志不会打印完整 Key,但配置导出、截图和自定义脚本仍可能带出,排查前先脱敏。
轮换 API Key 要先加新 Key 再删旧 Key,保证切换过程中服务不中断。加完后重启并验证一次调用,确认新 Key 生效,再撤销旧 Key,避免两边都不可用。
卸载 DeepSeek Harness 不会让 API Key 自动失效,凭据可能仍留在数据目录或别处。卸载只移除程序本体,Key 必须在服务商后台单独撤销,并检查残留文件。
多环境共用一个 API Key 会导致无法追溯来源,泄露后只能全部停用。按环境分 Key 后,可以单独撤销某一个环境,也能通过用量差异发现异常调用。
相关术语
- API Key
- API Key 是调用模型服务时用于身份与权限校验的凭据,由服务方签发,可单独撤销与轮换。— DeepSeek 官方 API 文档
- 凭据文件
- 凭据文件是 DeepSeek Harness 存放密钥等敏感信息的本地文件,通常位于 DSH_HOME 下,与普通配置分开。— DeepSeek Harness 官方文档
- 轮换
- 轮换是在不中断服务的前提下用新凭据替换旧凭据的过程,标准做法是先启用新 Key 再撤销旧 Key。— DeepSeek 官方 API 文档
- 残留
- 残留是卸载或迁移后仍留在磁盘或配置里的凭据与缓存,需要单独检查与清理。— DeepSeek Harness 官方文档
来源
- DeepSeek 官方 API 文档· DeepSeek
- DeepSeek Harness 官方文档· deepseek-harness
- dsh CLI README· deepseek-ai