> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 凭据密钥升级与恢复

> 升级时保留原密钥，密钥丢失后重置个人凭据

**数据库保存凭据密文，不保存加密密钥。升级时必须保留原密钥；密钥永久丢失后只能重新绑定。** 本文适用于个人凭据和个人上游 OAuth。

数据库模式不再自动生成本地密钥：未配置 `MCPHUB_CREDENTIAL_ENCRYPTION_KEY` 且没有有效的已有 `.credentials.key` 文件时，保存绑定会失败，服务仍可启动。环境变量优先于文件；已有文件继续兼容，JSON 模式仍可自动生成密钥。

## 选择处理方式

| 当前情况 | 处理方式 |
| - | - |
| 正常使用，已配置环境密钥 | 保留原值后升级。 |
| 正常使用，依赖本地密钥文件 | 删除旧容器前备份文件，将原值配置为环境密钥。 |
| 升级后失败，能找回原密钥 | 恢复原密钥并重启。 |
| 原密钥永久丢失 | 配置新密钥，逐个重新绑定或统一清空绑定。 |
| 从未保存个人绑定 | 生成一次密钥并持久化后使用。 |

## 正常部署：保留原密钥升级

1. 分别备份数据库和密钥，验证新部署前保留旧容器。
2. 已配置环境密钥时保留原值；使用文件时，先从旧容器复制出来，再将文件中的 Base64 值设置为 `MCPHUB_CREDENTIAL_ENCRYPTION_KEY`。**不要生成新密钥替换原密钥。**
3. 保留其他部署参数，升级镜像；所有共用数据库的实例使用同一密钥。
4. 验证已有绑定的 MCP 调用、个人 OAuth 连接和新绑定保存。

复制当前 Docker 默认路径下的密钥：

```bash theme={null}
mkdir -m 700 ./mcphub-key-backup
docker cp mcphub:/app/data/mcp_settings.json.credentials.key ./mcphub-key-backup/credentials.key
chmod 600 ./mcphub-key-backup/credentials.key
```

文件路径为实际配置路径加上 `.credentials.key`。旧部署可能使用 `/app/mcp_settings.json.credentials.key`，设置了 `MCPHUB_SETTING_PATH` 时以该路径为准。替换示例中的容器名和路径；尚未删除的停止容器也能复制。新增目录挂载不会自动迁移原文件。

在现有 Compose 服务的 `environment` 中加入：

```yaml theme={null}
environment:
  MCPHUB_CREDENTIAL_ENCRYPTION_KEY: ${MCPHUB_CREDENTIAL_ENCRYPTION_KEY:?Set the persistent credential encryption key}
```

通过部署平台或限制访问权限、不进入版本控制的 Compose `.env` 文件提供原值。`docker run` 可通过 `--env-file` 传入 `MCPHUB_CREDENTIAL_ENCRYPTION_KEY=<原密钥的Base64值>`。密钥须保存在容器外，供后续部署使用。

## 升级后失败：能找回原密钥

先暂停修改绑定，从旧部署的环境配置、旧容器、挂载目录或备份中找回密钥。将原值配置到所有实例的 `MCPHUB_CREDENTIAL_ENCRYPTION_KEY`，重启后验证 MCP 调用。也可恢复原密钥文件，设置权限为 `0600` 并持久化其目录；注意移除错误的环境变量覆盖。

原密钥可恢复对应的旧绑定。如果部分绑定已用另一把密钥重新保存，这些绑定仍需重新填写或授权。

## 原密钥永久丢失：重置绑定

**新密钥无法解密旧数据，回滚镜像或仅恢复数据库也无效。** 先备份数据库，再选择下面一种方式。

生成一次新密钥，保存到部署密钥配置中，让所有实例使用同一 `MCPHUB_CREDENTIAL_ENCRYPTION_KEY`；若已配置新的持久化密钥，可继续使用：

```bash theme={null}
openssl rand -base64 32
```

### 方式一：逐个用户重新绑定

配置新密钥并重启所有实例后，用户重新提交全部个人凭据，或先删除旧绑定再填写；个人 OAuth 用户先断开，再重新授权。完成后验证工具调用。

控制台无法加载旧绑定时，可用以下接口删除当前用户的绑定，再重新绑定：

| 类型 | 接口 |
| - | - |
| 个人凭据 | `DELETE /api/credentials/:name` |
| 个人 OAuth | `DELETE /api/servers/:name/oauth/personal` |

接口需要控制台身份认证，服务器名称需 URL 编码；MCP Bearer 密钥不能用于管理绑定。管理员会话也只操作管理员自己的绑定。

### 方式二：管理员统一清空绑定

适用于决定让所有用户重新绑定的部署。**会删除表中所有用户的个人凭据、个人 OAuth 令牌、客户端注册信息和待完成授权，包括已恢复正常的绑定。** 用户账号和服务器定义不受影响。

1. 停止共用数据库的所有 MCPHub 实例，避免并发写入并清除缓存运行实例；直接 SQL 不会触发应用失效通知。
2. 备份数据库，确认目标数据库和 schema，使用 `SELECT COUNT(*) FROM credential_bindings;` 查看记录数量。
3. 执行以下 SQL，确认剩余记录为零：

   ```sql theme={null}
   BEGIN;
   DELETE FROM credential_bindings;
   SELECT COUNT(*) AS remaining_bindings FROM credential_bindings;
   ```

   确认无误后单独执行 `COMMIT;`，否则执行 `ROLLBACK;`。保留表结构；提交后只能通过备份找回记录，解密仍需原密钥。
4. 确认所有实例均已配置同一持久化密钥，再启动服务。**清空表后也不会自动生成密钥。**
5. 所有用户重新填写个人凭据或授权 OAuth，并验证工具调用。

两种重置方式都不能撤销无法读取的旧 OAuth 令牌；有需要时，用户应在上游服务中撤销旧授权。

## 后续备份

数据库和密钥须分别备份，升级、扩容和迁移时保持密钥不变。常规配置导出不包含个人绑定和密钥。

JSON 模式需持久化配置文件及其 `.credentials.json`、`.credentials.key` 文件，或使用持久化环境密钥。另见 [Docker 部署](https://docs.mcphub.app/zh/configuration/docker-setup.md)和[个人凭据](https://docs.mcphub.app/zh/features/per-user-credentials.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.