> ## 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.

# 数据库配置

> 使用 PostgreSQL 数据库配置 MCPHub 作为 mcp_settings.json 文件的替代方案。

# MCPHub 数据库配置

## 概述

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

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

**核心优势：**

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

## 环境变量

### 数据库模式必需变量

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

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

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

## 设置说明

### 1. 使用 Docker

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

如果您已有 PostgreSQL 数据库：

```bash theme={null}
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` 文件：

```yaml theme={null}
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:
```

运行：

```bash theme={null}
docker-compose up -d
```

### 2. 手动设置

#### 步骤 1：设置 PostgreSQL 数据库

```bash theme={null}
# 安装 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

```bash theme={null}
npm install -g @samanhappy/mcphub
```

#### 步骤 3：设置环境变量

创建 `.env` 文件：

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

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

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

```bash theme={null}
# 运行迁移脚本
npx tsx src/scripts/migrate-to-database.ts
```

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

#### 步骤 5：启动 MCPHub

```bash theme={null}
mcphub
```

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

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

### 自动迁移

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

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

### 手动迁移

运行迁移脚本：

```bash theme={null}
# 使用 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。

```bash theme={null}
USE_DB=true
MCPHUB_SETTINGS_SYNC=upsert
MCPHUB_SETTING_PATH=/etc/mcphub/mcp_settings.json
```

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

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

## 数据库架构

MCPHub 创建以下表：

* **users** - 用户账户和认证
* **servers** - MCP 服务器配置
* **groups** - 服务器分组
* **system\_config** - 系统级设置
* **user\_configs** - 用户特定设置
* **vector\_embeddings** - 向量搜索数据（用于智能路由）

## 备份和恢复

### 备份

```bash theme={null}
# PostgreSQL 备份
pg_dump -U mcphub mcphub > mcphub_backup.sql

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

### 恢复

```bash theme={null}
# PostgreSQL 恢复
psql -U mcphub mcphub < mcphub_backup.sql

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

## 切换回基于文件的配置

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

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

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

## 故障排除

### 连接被拒绝

```
Error: connect ECONNREFUSED 127.0.0.1:5432
```

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

```bash theme={null}
# 检查 PostgreSQL 状态
sudo systemctl status postgresql

# 或对于 Docker
docker ps | grep postgres
```

### 认证失败

```
Error: password authentication failed for user "mcphub"
```

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

### 迁移失败

```
❌ Migration failed: ...
```

**解决方案：**

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

### 表已存在

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

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

## 环境变量参考

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

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

## 安全注意事项

1. **数据库凭据：** 安全存储数据库凭据，使用环境变量或密钥管理
2. **网络访问：** 仅限 MCPHub 实例访问数据库
3. **加密：** 在生产环境中使用 SSL/TLS 进行数据库连接：
   ```bash theme={null}
   DB_URL=postgresql://user:password@host:5432/mcphub?sslmode=require
   ```
4. **备份：** 定期备份您的数据库
5. **访问控制：** 使用强密码并限制用户权限

## 性能

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

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

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

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


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