MCPHub零门槛部署指南：从环境准备到功能验证的完整流程

MCPHub作为一款能够将多个MCP服务器整合到单一SSE端点的统一中心服务器，为服务器管理和资源整合提供了高效解决方案。本指南将通过环境自检、部署实施、功能验证和场景扩展四个核心模块，帮助新手用户快速完成部署并掌握核心功能。

三步环境自检清单

在开始部署前，请确保系统满足以下环境要求，这将有效避免90%的部署问题：

1. Docker环境检查
   执行以下命令验证Docker是否安装并正常运行：

   docker --version  # 检查Docker版本，需20.10.0以上
   docker-compose --version  # 检查Docker Compose版本，需v2.0+
   

   ✅ 预期结果：命令返回版本号且无错误提示。
   ⚠️ 风险提示：若提示"command not found"，需先参考Docker官方文档安装环境。

2. 端口可用性确认
   默认部署将使用3000端口（应用）和5432端口（数据库），执行以下命令检查端口占用情况：

   netstat -tuln | grep -E '3000|5432'  # 检查关键端口占用
   

   ✅ 预期结果：无输出表示端口可用。
   ⚠️ 风险提示：若端口已被占用，需在后续配置中修改端口映射。

3. 网络连接测试
   确保服务器能正常访问外部网络（用于拉取Docker镜像）：

   ping -c 3 registry.docker.com  # 测试Docker镜像仓库连接
   

   ✅ 预期结果：网络连通且无丢包。

Docker容器化部署全流程

完成环境检查后，通过以下步骤快速部署MCPHub完整服务栈：

1. 项目资源获取

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

2. 配置文件定制

创建.env文件自定义部署参数（避免直接修改配置文件）：

# 数据库配置
DB_PASSWORD=your_secure_password  # 建议至少8位包含大小写字母和数字
DB_PORT=5432  # 若5432端口被占用可修改为其他端口

# 应用配置
MCPHUB_PORT=3000  # 应用访问端口
LOG_LEVEL=info  # 日志级别：debug/info/warn/error

3. 服务启动与状态监控

docker-compose -f docker-compose.db.yml up -d  # 后台启动服务栈
docker-compose -f docker-compose.db.yml ps  # 检查服务状态

服务正常启动后，会看到两个运行中的容器：mcphub_postgres（数据库）和mcphub_app（应用服务）。

功能验证与界面导览

部署完成后，通过以下步骤确认系统功能正常并了解核心操作界面：

1. 基础访问测试

打开浏览器访问 http://服务器IP:3000，使用默认账号 admin 和密码 admin123 登录系统。首次登录将强制要求修改密码，建议设置包含特殊字符的强密码。

2. 仪表盘功能验证

成功登录后将进入MCPHub仪表盘，该界面提供服务器状态总览：

仪表盘关键指标说明：

• 服务器总数：当前管理的MCP服务器总量
• 在线服务器：绿色标识表示正常连接的服务器
• 最近服务器列表：显示各服务器工具数量和启用状态

3. 核心功能模块体验

MCPHub提供四大核心功能模块，通过左侧导航栏访问：

服务器管理

可添加、编辑和监控MCP服务器，支持查看实时连接状态和工具列表。

分组管理

支持将服务器按业务场景分组，便于批量管理和权限控制：

服务器市场

提供丰富的MCP服务器资源，可一键安装官方和社区贡献的服务器：

生产环境配置优化指南

基础部署完成后，针对生产环境建议进行以下优化配置：

1. 数据持久化增强

默认配置已使用本地卷存储数据，进一步优化可修改docker-compose.db.yml中的卷配置：

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

2. 安全加固措施

• 修改默认管理员密码后，建议创建不同权限的用户账号
• 通过Settings→Security配置IP访问限制和HTTPS证书
• 定期执行docker-compose -f docker-compose.db.yml pull更新镜像

3. 性能调优建议

根据服务器硬件配置调整资源限制：

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2'  # 根据CPU核心数调整
          memory: 2G  # 根据内存大小调整

常见问题诊断工具

部署或使用过程中遇到问题，可通过以下工具快速定位：

1. 服务日志查看

docker-compose -f docker-compose.db.yml logs -f app  # 实时查看应用日志
docker-compose -f docker-compose.db.yml logs -f postgres  # 查看数据库日志

2. 容器状态检查

docker inspect mcphub_app  # 查看应用容器详细配置
docker exec -it mcphub_app /bin/bash  # 进入容器内部调试

3. 数据库连接测试

docker exec -it mcphub_postgres psql -U postgres -d mcphub  # 直接连接数据库

通过本指南，你已掌握MCPHub从环境准备到生产部署的完整流程。更多高级功能配置可参考项目文档：docs/configuration/。