MCPHUB_CREDENTIAL_ENCRYPTION_KEY 且没有有效的已有 .credentials.key 文件时，保存绑定会失败，服务仍可启动。环境变量优先于文件；已有文件继续兼容，JSON 模式仍可自动生成密钥。
选择处理方式
正常部署：保留原密钥升级
- 分别备份数据库和密钥，验证新部署前保留旧容器。
- 已配置环境密钥时保留原值；使用文件时，先从旧容器复制出来，再将文件中的 Base64 值设置为
MCPHUB_CREDENTIAL_ENCRYPTION_KEY。不要生成新密钥替换原密钥。 - 保留其他部署参数，升级镜像；所有共用数据库的实例使用同一密钥。
- 验证已有绑定的 MCP 调用、个人 OAuth 连接和新绑定保存。
.credentials.key。旧部署可能使用 /app/mcp_settings.json.credentials.key，设置了 MCPHUB_SETTING_PATH 时以该路径为准。替换示例中的容器名和路径；尚未删除的停止容器也能复制。新增目录挂载不会自动迁移原文件。
在现有 Compose 服务的 environment 中加入：
.env 文件提供原值。docker run 可通过 --env-file 传入 MCPHUB_CREDENTIAL_ENCRYPTION_KEY=<原密钥的Base64值>。密钥须保存在容器外，供后续部署使用。
升级后失败：能找回原密钥
先暂停修改绑定，从旧部署的环境配置、旧容器、挂载目录或备份中找回密钥。将原值配置到所有实例的MCPHUB_CREDENTIAL_ENCRYPTION_KEY，重启后验证 MCP 调用。也可恢复原密钥文件，设置权限为 0600 并持久化其目录；注意移除错误的环境变量覆盖。
原密钥可恢复对应的旧绑定。如果部分绑定已用另一把密钥重新保存，这些绑定仍需重新填写或授权。
原密钥永久丢失：重置绑定
新密钥无法解密旧数据，回滚镜像或仅恢复数据库也无效。 先备份数据库，再选择下面一种方式。 生成一次新密钥，保存到部署密钥配置中，让所有实例使用同一MCPHUB_CREDENTIAL_ENCRYPTION_KEY；若已配置新的持久化密钥，可继续使用：
方式一：逐个用户重新绑定
配置新密钥并重启所有实例后，用户重新提交全部个人凭据，或先删除旧绑定再填写；个人 OAuth 用户先断开，再重新授权。完成后验证工具调用。 控制台无法加载旧绑定时，可用以下接口删除当前用户的绑定，再重新绑定：
接口需要控制台身份认证，服务器名称需 URL 编码；MCP Bearer 密钥不能用于管理绑定。管理员会话也只操作管理员自己的绑定。
方式二：管理员统一清空绑定
适用于决定让所有用户重新绑定的部署。会删除表中所有用户的个人凭据、个人 OAuth 令牌、客户端注册信息和待完成授权，包括已恢复正常的绑定。 用户账号和服务器定义不受影响。- 停止共用数据库的所有 MCPHub 实例，避免并发写入并清除缓存运行实例；直接 SQL 不会触发应用失效通知。
-
备份数据库，确认目标数据库和 schema，使用
SELECT COUNT(*) FROM credential_bindings;查看记录数量。 -
执行以下 SQL，确认剩余记录为零：
确认无误后单独执行
COMMIT;，否则执行ROLLBACK;。保留表结构；提交后只能通过备份找回记录，解密仍需原密钥。 - 确认所有实例均已配置同一持久化密钥，再启动服务。清空表后也不会自动生成密钥。
- 所有用户重新填写个人凭据或授权 OAuth，并验证工具调用。
后续备份
数据库和密钥须分别备份，升级、扩容和迁移时保持密钥不变。常规配置导出不包含个人绑定和密钥。 JSON 模式需持久化配置文件及其.credentials.json、.credentials.key 文件，或使用持久化环境密钥。另见 Docker 部署和个人凭据。