MCPHub开源项目极速部署指南：零门槛实现多服务器统一管理

MCPHub是一个开源的统一中心服务器（Unified Hub Server），能够将多个MCP（Model Context Protocol）服务器整合到单一的SSE（Server-Sent Events）端点，为开发者提供高效的服务器管理和资源整合解决方案。本文将通过Docker容器化技术，帮助你在10分钟内完成部署，即使是Linux新手也能轻松上手。

部署前环境检测指南

在开始部署前，请确保你的系统满足以下条件：

依赖项	最低版本	推荐版本	检测命令
Docker	20.10.0+	24.0.0+	docker --version
Docker Compose	2.0.0+	2.24.0+	docker-compose --version
可用内存	2GB	4GB+	free -h
磁盘空间	10GB	20GB+	df -h

⚠️ 注意：如果你的系统尚未安装Docker，可以参考官方文档的安装指南。对于Ubuntu系统，可通过sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin命令快速安装。

极速部署流程：从克隆到启动

1. 获取项目代码

首先，将MCPHub项目代码克隆到本地环境：

git clone https://gitcode.com/gh_mirrors/mc/mcphub
cd mcphub  # 进入项目目录

2. 配置环境变量

创建环境变量文件来自定义部署参数：

# 创建并编辑环境变量文件
cp examples/mcp_settings_with_env_vars.json .env
nano .env  # 可替换为你常用的文本编辑器

在文件中设置关键参数：

# 数据库配置
DB_PASSWORD=your_secure_password  # 建议使用至少12位包含大小写字母和特殊符号的密码
DB_USER=mcphub_admin
DB_NAME=mcphub_db

# 应用配置
MCPHUB_PORT=3000  # 默认端口，如冲突可修改为其他端口
LOG_LEVEL=info  # 日志级别：debug|info|warn|error

3. 启动服务集群

使用Docker Compose一键启动完整服务栈：

# 后台启动服务（包含PostgreSQL数据库和MCPHub应用）
docker-compose -f docker-compose.db.yml up -d

# 查看服务状态
docker-compose -f docker-compose.db.yml ps

正常输出应显示两个服务都处于"Up"状态：

• mcphub_postgres_1 (数据库服务)
• mcphub_app_1 (应用服务)

功能探索：MCPHub核心界面导览

部署完成后，通过浏览器访问http://localhost:3000进入MCPHub管理界面。首次登录使用默认管理员账户（用户名：admin，密码：admin123），系统会强制要求修改初始密码。

核心功能区域

1. 仪表盘：概览服务器状态，包括总服务器数、在线状态和工具数量统计
2. 服务器管理：添加、编辑和监控MCP服务器
3. 分组管理：按业务需求对服务器进行逻辑分组
4. 服务器市场：发现和安装官方及社区贡献的MCP服务器

自定义配置技巧：打造专属服务

1. 端口映射调整

如果3000端口已被占用，修改docker-compose.db.yml文件中的端口映射：

services:
  app:
    ports:
      - "3001:3000"  # 将主机3001端口映射到容器3000端口

2. 数据持久化配置

为确保数据安全，建议修改数据卷配置为绝对路径：

volumes:
  postgres_data:
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: '/path/to/your/local/directory'  # 替换为实际本地路径

3. 性能优化参数

编辑.env文件添加性能优化参数：

# 性能调优
NODE_ENV=production  # 生产环境模式
MAX_SERVER_CONCURRENCY=100  # 最大并发服务器连接数
CACHE_TTL=300  # 缓存过期时间(秒)

常见问题诊断与解决

服务启动失败

现象：执行docker-compose ps显示服务状态为"Exit"或"Restarting"
原因：通常是数据库初始化失败或端口冲突
解决方案：

1. 查看详细日志：docker-compose -f docker-compose.db.yml logs app
2. 检查端口占用：netstat -tulpn | grep 3000
3. 重置数据库：docker-compose -f docker-compose.db.yml down -v && docker-compose -f docker-compose.db.yml up -d

访问权限问题

现象：登录后无法添加服务器或修改配置
原因：默认管理员权限未正确配置
解决方案：

1. 进入容器：docker exec -it mcphub_app_1 sh
2. 运行权限修复命令：npm run fix-permissions
3. 重启应用：docker-compose -f docker-compose.db.yml restart app

数据库连接超时

现象：应用日志显示"Connection timeout"错误
原因：数据库服务未就绪或网络配置问题
解决方案：

1. 确认数据库服务状态：docker-compose -f docker-compose.db.yml logs postgres
2. 检查网络配置：确保容器间网络互通
3. 增加数据库连接超时时间：在.env中添加DB_CONNECTION_TIMEOUT=30000

进阶学习资源

• 官方配置指南：docs/configuration/docker-setup.mdx
• API开发文档：docs/api-reference/introduction.mdx
• 高级部署方案：examples/mcp_settings_with_env_vars.json

通过本文介绍的部署方法，你已经拥有了一个功能完整的MCPHub服务。接下来可以探索服务器市场中的各类应用，或通过API接口开发自定义集成方案，充分发挥多服务器统一管理的优势。