处理 litellm mcp 风险时,经常需要收回管理权限或更换共享凭据。开始之前先区分 master key、salt key、虚拟密钥和供应商 api key,否则可能把一次权限调整变成数据库解密故障。下面按现有环境判断和具体执行顺序展开。
先把四类凭据对应到用途
| 材料 | 用途 | 处理重点 |
|---|---|---|
| Master key | 代理管理认证,部分部署还用于存储凭据加密。 | 先查是否承担加密职责,再确定轮换分支。 |
| LITELLM_SALT_KEY | 配置后用于存储凭据的加密和解密。 | 保存原值和备份,避免随意修改或移除。 |
| 虚拟密钥 | 业务调用模型或工具。 | 按应用负责人、授权和使用记录单独处理。 |
| 供应商密钥 | 网关连接模型平台或其他上游。 | 在供应商侧更换,并更新网关保存的对应值。 |
登记凭据的负责人、保存位置、使用者和最后更换时间,记录密钥版本引用而不是原文。检查代码仓库、CI 变量和共享文档中是否保存了管理密钥,把普通业务接入改为范围受限的业务凭据。

轮换前先保住数据库和配置
对当前数据库建立可恢复备份,保存部署配置、镜像版本以及原有加密材料。另取一个隔离副本演练,验证旧数据可读、轮换后的模型连接正常。检查 config.yaml 是否把 master key 写成固定字符串,固定值可能覆盖环境变量配置。
记录代理实际启动环境中的 salt key 是否存在,不在日志里打印它的值。多副本需要使用同一套有效加密材料,并在维护期间减少配置写入,避免新旧实例混用不同密钥处理同一数据库。
已经设置 salt key 的环境怎么换?
保留原 salt key,生成新的强随机 master key,更新秘密存储和所有实例的引用,再协调重启。这个分支通过换认证密钥和重启完成,无需为了换 master key 而重新加密数据库。

较旧版本中,调用带 new_master_key 的再生接口可能把数据改为另一套加密方式,因此采用官方 salt-key 分支的直接更新和重启流程。执行前仍应核对实际版本的轮换文档。
更新后用新管理凭据完成授权验证,用原有业务虚拟密钥调用数据库中保存的模型。旧管理凭据应失效,业务虚拟密钥不一定随 master key 改动而撤销,需要按自身风险决定是否另行替换。
未设置 salt key,怎么迁移已有加密数据?
先确认现有 master key 可从受控秘密存储取回。对于支持官方启动迁移机制的版本,可使用旧 master key 作为迁移来源,同时设置新的 master key。下面展示变量职责,实际值由秘密管理系统提供。
# 放入实际部署的受控环境配置,尖括号部分需替换 LITELLM_MASTER_KEY=<新的强随机管理密钥> LITELLM_MIGRATE_FROM_MASTER_KEY=<原有管理密钥>
在维护窗口启动相应实例,检查数据库连接和迁移完成日志。成功后验证模型凭据及 MCP 凭据仍能解析,再移除旧值的迁移变量并重启验证。迁移尚未完成时,保留同一组新旧引用并排查失败原因。
迁移期间保持 salt key 原先的配置状态。临时添加新 salt key 会改变解密预期,可能使启动迁移无法按计划处理已有数据。若日志提示部分数据仍用旧密钥加密,需要先解决并发写入或数据库问题,再按当前版本支持的恢复步骤继续。
供应商密钥和虚拟密钥按什么顺序换?
仅 master key 泄露时,先评估攻击者是否可能访问管理接口和保存的上游凭据。如果已有主机执行或凭据读取迹象,应扩大到进程可接触的模型平台、数据库与云身份,逐个登记受影响材料。
普通计划轮换可先在供应商创建新密钥,更新网关并进行低成本测试,随后撤销旧密钥。已确认泄露时,根据实际风险缩短过渡期或立即撤销。每一步检查调用错误、额度和计费,避免所有业务长时间继续使用旧凭据。
虚拟密钥按照应用或团队逐个发放替代值、切换调用端并撤销旧值。自动轮换和宽限期能力与版本及许可有关,应先核对可用功能;暂时没有这些能力时,使用受控创建、切换和撤销流程。

同时清理管理员与 MCP 授权
审查 proxy admin、团队管理员、SSO 组映射及自动化管理账户。选择一个普通测试账户和一个管理员账户,分别验证工具使用、配置新增和测试操作,记录允许与拒绝结果。共享登录难以区分操作者,可逐步迁移到可追溯个人身份。
修改登录方式前,先验证新的管理员登录和恢复入口。更改 master key 后已有 UI 会话可能需要重新登录,出现 401 时应先检查登录与实际加载密钥,避免通过放松认证恢复访问。
轮换后模型全部报错怎么排查?
先检查原 salt key 是否被改变、配置固定值是否覆盖环境变量、旧副本是否仍接流量,再查看数据库迁移是否完整。不要反复生成不同新值尝试启动,这会让故障定位和恢复更加困难。
需要恢复时,使用匹配的数据库备份与加密材料,在隔离环境验证后再按计划恢复。交付记录应包括备份编号、新密钥版本引用、各副本加载时间、模型测试结果及旧凭据撤销时间。
维护窗口怎样避免新旧密钥混用?
先停止非必要的管理写入,确认备份时间和秘密存储版本。将密钥更换与数据库迁移分成明确阶段,每个阶段都记录已完成的副本和验证结果。秘密存储内容已经更新,并不代表运行中的进程已经重新读取。
对无 salt key 的加密迁移,先在隔离副本用已有合法模型和 MCP 凭据验证完整流程。生产变更期间避免旧进程继续以旧密钥写入新记录。若迁移日志报告剩余数据,保存同一对新旧密钥引用,查清并发写入或数据库错误后再继续。
测试成功后,按当前版本流程移除临时迁移变量,核对下次重启仍可读取模型。清理工单附件和临时导出中的明文,保留必要的备份和秘密版本,按组织要求限制访问和保留期限。
需要对外说明哪些结果?
向应用负责人分别通知管理入口、虚拟密钥和上游密钥的影响。业务密钥更换应有明确切换时间、失败联系人和回退条件;已经确认泄露的旧密钥则记录撤销时间及历史使用调查。
给安全团队的记录包括谁曾持有管理凭据、哪些权限已撤销、哪些供应商完成轮换,以及尚未确认的范围。凭据轮换完成后仍需调查此前操作,尤其是陌生工具配置、异常模型端点和网关主机子进程。

















