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 迁移
创建所有表并导入所有数据

手动迁移

运行迁移脚本：

# 使用 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 仪表板的工作方式完全相同，但现在将更改存储在数据库中而不是文件中。

数据库架构

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

从基于文件迁移到数据库

自动迁移

手动迁移

迁移后的配置

数据库架构

备份和恢复

备份

恢复

切换回基于文件的配置

故障排除

连接被拒绝

认证失败

迁移失败

表已存在

环境变量参考

安全注意事项

性能

​MCPHub 数据库配置

​概述

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

​环境变量

​数据库模式必需变量

​设置说明

​1. 使用 Docker

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

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

​2. 手动设置

​步骤 1：设置 PostgreSQL 数据库

​步骤 2：安装 MCPHub

​步骤 3：设置环境变量

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

​步骤 5：启动 MCPHub

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

​自动迁移

​手动迁移

​迁移后的配置

​数据库架构

​备份和恢复

​备份

​恢复

​切换回基于文件的配置

​故障排除

​连接被拒绝

​认证失败

​迁移失败

​表已存在

​环境变量参考

​安全注意事项

​性能

MCPHub 数据库配置

概述

为什么使用数据库配置？

环境变量

数据库模式必需变量

设置说明

1. 使用 Docker

方案 A：使用外部数据库

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

2. 手动设置

步骤 1：设置 PostgreSQL 数据库

步骤 2：安装 MCPHub

步骤 3：设置环境变量

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

步骤 5：启动 MCPHub

从基于文件迁移到数据库

自动迁移

手动迁移

迁移后的配置

数据库架构

备份和恢复

备份

恢复

切换回基于文件的配置

故障排除

连接被拒绝

认证失败

迁移失败

表已存在

环境变量参考

安全注意事项

性能