MCPHub 数据库配置

概述

MCPHub 支持将配置数据存储在 PostgreSQL 数据库中，作为 mcp_settings.json 文件配置的替代方案。数据库模式为生产环境和企业级部署提供了更强大的持久化和扩展能力。

为什么使用数据库配置？

核心优势：

✅ 更好的持久化 - 配置数据存储在专业数据库中，支持事务和数据完整性
✅ 高可用性 - 利用数据库复制和故障转移能力
✅ 企业级支持 - 符合企业数据管理和合规要求
✅ 备份恢复 - 使用成熟的数据库备份工具和策略

环境变量

数据库模式必需变量

# 数据库连接 URL（PostgreSQL）
# 只需设置 DB_URL 即可自动启用数据库模式
DB_URL=postgresql://user:password@localhost:5432/mcphub

# 或显式控制 USE_DB（覆盖自动检测）
# USE_DB=true

简化配置：您只需设置 DB_URL 即可启用数据库模式。MCPHub 会自动检测 DB_URL 是否存在并启用数据库模式。如果需要在设置了 DB_URL 的情况下禁用数据库模式，可以显式设置 USE_DB=false。

设置说明

1. 使用 Docker

方案 A：使用外部数据库

如果您已有 PostgreSQL 数据库：

docker run -d \
  -p 3000:3000 \
  -v ./mcp_settings.json:/app/mcp_settings.json \
  -e DB_URL="postgresql://user:password@your-db-host:5432/mcphub" \
  samanhappy/mcphub

方案 B：将 PostgreSQL 作为独立服务

创建 docker-compose.yml 文件：

version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: mcphub
      POSTGRES_USER: mcphub
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  mcphub:
    image: samanhappy/mcphub:latest
    environment:
      USE_DB: "true"
      DB_URL: "postgresql://mcphub:your_secure_password@postgres:5432/mcphub"
      PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - postgres

volumes:
  pgdata:

运行：

docker-compose up -d

2. 手动设置

步骤 1：设置 PostgreSQL 数据库

# 安装 PostgreSQL（如果尚未安装）
sudo apt-get install postgresql postgresql-contrib

# 创建数据库和用户
sudo -u postgres psql <<EOF
CREATE DATABASE mcphub;
CREATE USER mcphub WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mcphub TO mcphub;
EOF

步骤 2：安装 MCPHub

npm install -g @samanhappy/mcphub

步骤 3：设置环境变量

创建 .env 文件：

# 只需设置 DB_URL 即可启用数据库模式（USE_DB 会自动检测）
DB_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
PORT=3000

步骤 4：运行迁移（可选）

如果您有现有的 mcp_settings.json 文件，可以进行迁移：

# 运行迁移脚本
npx tsx src/scripts/migrate-to-database.ts

或者让 MCPHub 在首次启动时自动迁移。

步骤 5：启动 MCPHub

mcphub

从基于文件迁移到数据库

MCPHub 在启用数据库模式首次启动时提供自动迁移功能。您也可以手动运行迁移。

自动迁移

当您首次使用 USE_DB=true 启动 MCPHub 时：

MCPHub 连接到数据库
检查数据库中是否存在任何用户
如果未找到用户，自动从 mcp_settings.json 迁移
创建所有表并导入所有数据

个人凭据绑定

个人凭据和个人上游 OAuth 绑定会从配置文件旁的 .credentials.json 独立迁移，即使数据库已有用户也会补充导入。切换前应保留相同配置路径旁的原 .credentials.key，或将其原值设置为 MCPHUB_CREDENTIAL_ENCRYPTION_KEY，不要生成新密钥替换。导入新批次前，MCPHub 会验证待导入的新绑定及数据库已有绑定均可使用当前密钥解密。密钥缺失或不匹配时，启动会在配置迁移前中止；恢复原密钥后重试。导入采用事务，不覆盖已有的 (serverName, username) 绑定。内部表 credential_binding_imports 记录已处理的密文，避免保留的源文件恢复后来已删除的绑定。恢复时清空 credential_bindings 应保留这些迁移记录。源文件保持不变，密钥需独立于数据库备份。另见凭据密钥升级与恢复。

手动迁移

运行迁移脚本：

# 使用 npx
npx tsx src/scripts/migrate-to-database.ts

# 或使用 Node
node dist/scripts/migrate-to-database.js

迁移将：

✅ 如果不存在则创建数据库表
✅ 导入所有用户（包含哈希密码）
✅ 导入所有 MCP 服务器配置
✅ 导入所有分组
✅ 导入系统配置
✅ 导入用户特定配置
✅ 跳过已存在的记录（可安全多次运行）

迁移后的配置

在数据库模式下运行时，所有配置更改都存储在数据库中：

通过 /api/users 进行用户管理
通过 /api/servers 进行服务器管理
通过 /api/groups 进行分组管理
通过 /api/system/config 进行系统设置

Web 仪表板的工作方式完全相同，但现在将更改存储在数据库中而不是文件中。启用数据库模式时，mcp_settings.json 仅在首次初始化时作为一次性种子配置使用。首次迁移后，PostgreSQL 是唯一的配置来源；之后对 mcp_settings.json 的修改不会自动导入。数据库模式下可通过仪表板、API 或 CLI 管理配置，或启用下面的启动同步。

声明式服务器与分组（GitOps）

在数据库模式下设置 MCPHUB_SETTINGS_SYNC=upsert，每次启动都会从 mcp_settings.json 同步 mcpServers 和 groups。可用 MCPHUB_SETTING_PATH 指向只读 ConfigMap。修改文件后需重启；暂不支持文件监听或 SIGHUP。

USE_DB=true
MCPHUB_SETTINGS_SYNC=upsert
MCPHUB_SETTING_PATH=/etc/mcphub/mcp_settings.json

按全局唯一名称匹配并保留已有数据库 ID。同名条目以文件为准，包括通过仪表板创建或修改的条目。
文件声明控制整个条目的配置；省略的可选字段会清空或恢复默认值。服务器默认启用且为私有。分组成员、别名、选择列表及固定工具以文件为准。
接管已有配置时，省略 owner 会清除现有所有者，包括非管理员所有者。要保留所有权，请显式声明 owner；省略 sharedWithUsers 也会清空共享用户。已有部署启用同步前应检查这些字段。
在 upsert 模式下，文件中未声明的条目保持不变。移除或重命名条目不会删除原数据库条目。
在 upsert 模式下，仅同步服务器和分组声明。用户、Bearer 密钥、MCPHub OAuth 客户端及令牌、个人凭据绑定、系统配置等运行数据仍保存在数据库中。用户表为空时仍执行原有的首次初始化迁移。
同步忽略文件中的上游 OAuth access/refresh token 和待授权状态。连接目标及 OAuth 声明不变时保留数据库中的运行授权状态，包括动态注册的客户端凭据；变化时清除旧状态，可能需要重新授权。服务器内部可空的 settingsSyncHash 列用于检测声明变化（包括字段移除和环境变量值变化），不保存展开后的密钥。指纹采用 PBKDF2-SHA256（600,000 次迭代），每个服务器使用独立随机盐，后续启动复用已有盐。
首次接管已有服务器时，仅在连接目标及所有显式声明的 OAuth 字段与数据库一致时保留授权。未声明的自动发现字段会保留至声明发生变化。
环境变量占位符保持原样持久化，由现有运行逻辑展开。文件缺失、JSON 或声明格式错误、重复分组名、不支持的同步模式以及数据库错误都会导致启动失败。服务器与分组写入在同一事务中执行。

不设置 MCPHUB_SETTINGS_SYNC 时保持原有的一次性初始化行为；该开关仅适用于数据库模式。启用后不会向配置文件回写，包括首次初始化迁移。

服务器 ID 与工具策略

同步按名称匹配已有条目。将服务器 ID 用于工具策略前，从 GET /api/servers/:name 获取 data.config.id，并将同一个值固定在文件声明中：

{
  "mcpServers": {
    "time": {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

将 time 改名为 clock 时，只改条目名称并保留 id，同时更新分组引用。不固定 ID 时，新名称会获得不同身份，旧服务器拒绝规则不再限制它；prune 模式还会删除旧条目及其运行凭据。固定 ID 保留的是策略身份，不代表自动迁移按名称绑定的个人凭据或其他引用，请单独核对。同名声明中的 id 与数据库不一致时，保留数据库 ID 并输出冲突警告。启动会在同步后记录策略引用缺失警告，请在依赖规则前处理这些提示。

清理托管条目

设置 MCPHUB_SETTINGS_SYNC=prune，可在创建、更新声明的同时，删除曾由配置托管、但已从文件移除的服务器和分组。此模式需显式启用；upsert 和未设置变量时的行为保持不变。

两种同步模式都会为声明的条目写入内部托管标记，包括从控制台接管的同名条目。控制台编辑不会解除托管。未托管条目保留，因此该模式不是整个数据库的完整镜像。
省略 mcpServers 或 groups 时不清理该类条目；显式设置 mcpServers: {} 或 groups: [] 才会清空对应的全部托管条目。重命名会创建新条目并删除旧条目，包括旧服务器的运行凭据。
旧版本同步过的服务器通过已有声明指纹识别。旧分组没有托管标记，需先用任一同步模式重新声明一次，再从文件移除。已经从文件移除的历史分组仍需手动删除。
删除服务器时一并清理其个人凭据绑定、服务器和工具向量，以及保留但未在本次声明的分组中的引用。如果本次声明的分组仍引用待删除服务器，启动失败，避免静默修改声明。用户、Bearer Key 权限范围、MCPHub OAuth 客户端和令牌、系统配置不在清理范围内。
创建、更新、删除、引用修正和凭据及向量清理共用一个事务。声明无效或数据库操作失败会回滚事务并使启动失败；可选的向量表不存在时跳过向量清理。同步仍仅在启动时运行，且不回写配置文件。

启用 prune 前请核对完整配置：删除不可恢复，重新添加服务器也不会恢复其凭据。

数据库架构

MCPHub 创建以下表：

users - 用户账户和认证
servers - MCP 服务器配置
groups - 服务器分组
system_config - 系统级设置
user_configs - 用户特定设置
vector_embeddings - 向量搜索数据（用于智能路由）

备份和恢复

备份

# PostgreSQL 备份
pg_dump -U mcphub mcphub > mcphub_backup.sql

# 或使用 Docker
docker exec postgres pg_dump -U mcphub mcphub > mcphub_backup.sql

恢复

# PostgreSQL 恢复
psql -U mcphub mcphub < mcphub_backup.sql

# 或使用 Docker
docker exec -i postgres psql -U mcphub mcphub < mcphub_backup.sql

切换回基于文件的配置

如果您需要切换回基于文件的配置：

设置 USE_DB=false 或删除 DB_URL 和 USE_DB 环境变量
重启 MCPHub
MCPHub 将再次使用 mcp_settings.json

注意：在数据库模式下所做的更改不会反映到文件中，除非您手动导出。

故障排除

连接被拒绝

Error: connect ECONNREFUSED 127.0.0.1:5432

解决方案： 检查 PostgreSQL 是否正在运行并可访问：

# 检查 PostgreSQL 状态
sudo systemctl status postgresql

# 或对于 Docker
docker ps | grep postgres

认证失败

Error: password authentication failed for user "mcphub"

解决方案： 验证 DB_URL 环境变量中的数据库凭据。

迁移失败

❌ Migration failed: ...

解决方案：

检查 mcp_settings.json 是否存在且为有效的 JSON
验证数据库连接
检查日志获取具体错误信息
确保数据库用户具有 CREATE TABLE 权限

表已存在

如果数据库表不存在，会自动创建。如果遇到关于已存在表的错误，请检查：

之前的迁移是否部分完成
手动创建表的冲突
如果需要，在数据库配置中使用 synchronize: false 运行

环境变量参考

变量	必需	默认值	描述
`DB_URL`	是*	-	完整的 PostgreSQL 连接 URL。设置此变量会自动启用数据库模式
`USE_DB`	否	自动	显式启用/禁用数据库模式。如果未设置，根据 `DB_URL` 是否存在自动检测
`MCPHUB_SETTING_PATH`	否	-	mcp_settings.json 的路径（用于迁移）

*数据库模式必需。只需设置 DB_URL 即可自动启用数据库模式

安全注意事项

数据库凭据： 安全存储数据库凭据，使用环境变量或密钥管理
网络访问： 仅限 MCPHub 实例访问数据库

加密： 在生产环境中使用 SSL/TLS 进行数据库连接：

DB_URL=postgresql://user:password@host:5432/mcphub?sslmode=require

备份： 定期备份您的数据库
访问控制： 使用强密码并限制用户权限

性能

数据库模式在以下场景提供更好的性能：

多个并发用户
频繁的配置更改
大量服务器/分组

文件模式可能更快的场景：

单用户设置
读取密集型工作负载且更改不频繁
开发/测试环境

开始使用

核心功能

配置指南

数据库配置

MCPHub 数据库配置

概述

为什么使用数据库配置？

环境变量

数据库模式必需变量

设置说明

1. 使用 Docker

方案 A：使用外部数据库

方案 B：将 PostgreSQL 作为独立服务

2. 手动设置

步骤 1：设置 PostgreSQL 数据库

步骤 2：安装 MCPHub

步骤 3：设置环境变量

步骤 4：运行迁移（可选）

步骤 5：启动 MCPHub

从基于文件迁移到数据库

自动迁移

个人凭据绑定

手动迁移

迁移后的配置

声明式服务器与分组（GitOps）

服务器 ID 与工具策略

清理托管条目

数据库架构

备份和恢复

备份

恢复

切换回基于文件的配置

故障排除

连接被拒绝

认证失败

迁移失败

表已存在

环境变量参考

安全注意事项

性能

​MCPHub 数据库配置

​概述

​为什么使用数据库配置？

​环境变量

​数据库模式必需变量

​设置说明

​1. 使用 Docker

​方案 A：使用外部数据库

​方案 B：将 PostgreSQL 作为独立服务

​2. 手动设置

​步骤 1：设置 PostgreSQL 数据库

​步骤 2：安装 MCPHub

​步骤 3：设置环境变量

​步骤 4：运行迁移（可选）

​步骤 5：启动 MCPHub

​从基于文件迁移到数据库

​自动迁移

​个人凭据绑定

​手动迁移

​迁移后的配置

​声明式服务器与分组（GitOps）

​服务器 ID 与工具策略

​清理托管条目

​数据库架构

​备份和恢复

​备份

​恢复

​切换回基于文件的配置

​故障排除

​连接被拒绝

​认证失败

​迁移失败

​表已存在

​环境变量参考

​安全注意事项

​性能

MCPHub 数据库配置

概述

为什么使用数据库配置？

环境变量

数据库模式必需变量

设置说明

1. 使用 Docker

方案 A：使用外部数据库

方案 B：将 PostgreSQL 作为独立服务

2. 手动设置

步骤 1：设置 PostgreSQL 数据库

步骤 2：安装 MCPHub

步骤 3：设置环境变量

步骤 4：运行迁移（可选）

步骤 5：启动 MCPHub

从基于文件迁移到数据库

自动迁移

个人凭据绑定

手动迁移

迁移后的配置

声明式服务器与分组（GitOps）

服务器 ID 与工具策略

清理托管条目

数据库架构

备份和恢复

备份

恢复

切换回基于文件的配置

故障排除

连接被拒绝

认证失败

迁移失败

表已存在

环境变量参考

安全注意事项

性能