mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
generate documents using mintlify (#153)
This commit is contained in:
samanhappy
362
docs/zh/quickstart.mdx
Normal file
362
docs/zh/quickstart.mdx
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
title: '快速开始'
|
||||
description: '5 分钟内部署 MCPHub 并连接您的第一个 MCP 服务器'
|
||||
---
|
||||
|
||||
## 欢迎使用 MCPHub！
|
||||
|
||||
本指南将帮助您在 5 分钟内完成 MCPHub 的部署和配置，并连接您的第一个 MCP 服务器。
|
||||
|
||||
## 前提条件
|
||||
|
||||
在开始之前，请确保您的系统满足以下要求：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion icon="desktop" title="系统要求">
|
||||
- **操作系统**: Linux、macOS 或 Windows
|
||||
- **内存**: 最少 2GB RAM（推荐 4GB+）
|
||||
- **存储**: 至少 1GB 可用空间
|
||||
- **网络**: 稳定的互联网连接
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="code" title="软件依赖">
|
||||
- **Node.js**: 18.0+ 版本
|
||||
- **Docker**: 最新版本（可选，用于容器化部署）
|
||||
- **Git**: 用于代码管理
|
||||
|
||||
检查版本：
|
||||
```bash
|
||||
node --version # 应该 >= 18.0.0
|
||||
npm --version # 应该 >= 8.0.0
|
||||
docker --version # 可选
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 安装 MCPHub
|
||||
|
||||
### 方式一：使用 npm（推荐）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion icon="download" title="安装 MCPHub CLI">
|
||||
首先安装 MCPHub 命令行工具：
|
||||
|
||||
```bash
|
||||
npm install -g @mcphub/cli
|
||||
```
|
||||
|
||||
验证安装：
|
||||
```bash
|
||||
mcphub --version
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="folder-plus" title="创建新项目">
|
||||
创建一个新的 MCPHub 项目：
|
||||
|
||||
```bash
|
||||
# 创建项目
|
||||
mcphub init my-mcphub-project
|
||||
cd my-mcphub-project
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="gear" title="配置环境">
|
||||
复制并编辑环境变量文件：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env` 文件，设置基本配置：
|
||||
```bash
|
||||
# 服务器配置
|
||||
PORT=3000
|
||||
NODE_ENV=development
|
||||
|
||||
# 数据库配置（使用内置 SQLite）
|
||||
DATABASE_URL=sqlite:./data/mcphub.db
|
||||
|
||||
# JWT 密钥（请更改为安全的随机字符串）
|
||||
JWT_SECRET=your-super-secret-jwt-key-change-me
|
||||
|
||||
# 管理员账户
|
||||
ADMIN_EMAIL=admin@example.com
|
||||
ADMIN_PASSWORD=admin123
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 方式二：使用 Docker
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion icon="docker" title="Docker 快速部署">
|
||||
使用 Docker Compose 一键部署：
|
||||
|
||||
```bash
|
||||
# 下载配置文件
|
||||
curl -O https://raw.githubusercontent.com/mcphub/mcphub/main/docker-compose.yml
|
||||
|
||||
# 启动服务
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
或者直接运行 Docker 容器：
|
||||
```bash
|
||||
docker run -d \
|
||||
--name mcphub \
|
||||
-p 3000:3000 \
|
||||
-e NODE_ENV=production \
|
||||
-e JWT_SECRET=your-secret-key \
|
||||
mcphub/server:latest
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 启动 MCPHub
|
||||
|
||||
### 开发模式启动
|
||||
|
||||
```bash
|
||||
# 初始化数据库
|
||||
npm run db:setup
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 生产模式启动
|
||||
|
||||
```bash
|
||||
# 构建应用
|
||||
npm run build
|
||||
|
||||
# 启动生产服务器
|
||||
npm start
|
||||
```
|
||||
|
||||
<Note>开发模式下，MCPHub 会在 `http://localhost:3000` 启动，并具有热重载功能。</Note>
|
||||
|
||||
## 首次访问和配置
|
||||
|
||||
### 1. 访问管理界面
|
||||
|
||||
打开浏览器，访问 `http://localhost:3000`，您将看到 MCPHub 的欢迎页面。
|
||||
|
||||
### 2. 登录管理员账户
|
||||
|
||||
使用您在 `.env` 文件中设置的管理员凭据登录：
|
||||
|
||||
- **邮箱**: `admin@example.com`
|
||||
- **密码**: `admin123`
|
||||
|
||||
<Warning>首次登录后，请立即更改默认密码以确保安全！</Warning>
|
||||
|
||||
### 3. 完成初始配置
|
||||
|
||||
登录后，系统会引导您完成初始配置：
|
||||
|
||||
1. **更改管理员密码**
|
||||
2. **设置组织信息**
|
||||
3. **配置基本设置**
|
||||
|
||||
## 添加您的第一个 MCP 服务器
|
||||
|
||||
### 1. 准备 MCP 服务器
|
||||
|
||||
如果您还没有 MCP 服务器，可以使用我们的示例服务器进行测试：
|
||||
|
||||
```bash
|
||||
# 克隆示例服务器
|
||||
git clone https://github.com/mcphub/example-mcp-server.git
|
||||
cd example-mcp-server
|
||||
|
||||
# 安装依赖并启动
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
示例服务器将在 `http://localhost:3001` 启动。
|
||||
|
||||
### 2. 在 MCPHub 中添加服务器
|
||||
|
||||
在 MCPHub 管理界面中：
|
||||
|
||||
1. 点击 **"添加服务器"** 按钮
|
||||
2. 填写服务器信息：
|
||||
```
|
||||
名称: Example MCP Server
|
||||
端点: http://localhost:3001
|
||||
描述: 示例 MCP 服务器用于测试
|
||||
```
|
||||
3. 选择功能类型（如：chat、completion、analysis）
|
||||
4. 点击 **"测试连接"** 验证服务器可达性
|
||||
5. 点击 **"保存"** 完成添加
|
||||
|
||||
### 3. 验证服务器状态
|
||||
|
||||
添加成功后，您应该能在服务器列表中看到新添加的服务器，状态显示为 **"活跃"**（绿色）。
|
||||
|
||||
## 测试路由功能
|
||||
|
||||
### 发送测试请求
|
||||
|
||||
使用 cURL 或其他 HTTP 客户端测试路由功能：
|
||||
|
||||
```bash
|
||||
# 发送聊天请求
|
||||
curl -X POST http://localhost:3000/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Hello, this is a test message!"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 查看请求日志
|
||||
|
||||
在 MCPHub 管理界面的 **"监控"** 页面中，您可以实时查看：
|
||||
|
||||
- 请求数量和响应时间
|
||||
- 服务器健康状态
|
||||
- 错误日志和统计
|
||||
|
||||
## 后续步骤
|
||||
|
||||
恭喜！您已经成功部署了 MCPHub 并添加了第一个 MCP 服务器。接下来您可以：
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="配置负载均衡" icon="balance-scale" href="/zh/features/smart-routing">
|
||||
学习如何配置智能路由和负载均衡策略
|
||||
</Card>
|
||||
<Card title="添加更多服务器" icon="plus" href="/zh/features/server-management">
|
||||
了解服务器管理的高级功能
|
||||
</Card>
|
||||
<Card title="设置监控告警" icon="bell" href="/zh/features/monitoring">
|
||||
配置性能监控和告警通知
|
||||
</Card>
|
||||
<Card title="API 集成" icon="code" href="/zh/api-reference/introduction">
|
||||
将 MCPHub 集成到您的应用程序中
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 常见问题
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion icon="question" title="无法连接到 MCP 服务器">
|
||||
**可能原因**：
|
||||
- 服务器地址错误或服务器未启动
|
||||
- 防火墙阻止连接
|
||||
- 网络配置问题
|
||||
|
||||
**解决方案**：
|
||||
1. 验证服务器是否正在运行：`curl http://localhost:3001/health`
|
||||
2. 检查防火墙设置
|
||||
3. 确认网络连接正常
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="question" title="服务器状态显示为离线">
|
||||
**可能原因**：
|
||||
- 健康检查失败
|
||||
- 服务器响应超时
|
||||
- 服务器崩溃或重启
|
||||
|
||||
**解决方案**：
|
||||
1. 检查服务器日志
|
||||
2. 调整健康检查间隔
|
||||
3. 重启服务器进程
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="question" title="忘记管理员密码">
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 重置管理员密码
|
||||
npm run reset-admin-password
|
||||
```
|
||||
或者删除数据库文件重新初始化：
|
||||
```bash
|
||||
rm data/mcphub.db
|
||||
npm run db:setup
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 获取帮助
|
||||
|
||||
如果您在设置过程中遇到问题：
|
||||
|
||||
- 📖 查看 [完整文档](/zh/development/getting-started)
|
||||
- 🐛 在 [GitHub](https://github.com/mcphub/mcphub/issues) 上报告问题
|
||||
- 💬 加入 [Discord 社区](https://discord.gg/mcphub) 获取实时帮助
|
||||
- 📧 发送邮件至 support@mcphub.io
|
||||
|
||||
---
|
||||
|
||||
<Tip>
|
||||
**小贴士**: 在生产环境部署前，请阅读我们的 [生产部署指南](/zh/configuration/docker-setup)
|
||||
了解安全和性能最佳实践。
|
||||
</Tip>
|
||||
mintlify dev ```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
### 故障排除
|
||||
|
||||
这里有一些常见问题的快速解决方案：
|
||||
|
||||
<AccordionGroup>
|
||||
|
||||
<Accordion title="Mintlify dev 无法运行">
|
||||
请检查您是否安装了最新版本的 Mintlify CLI，以及您的 Node 版本是否符合我们的[要求](/zh/development)。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="页面加载为 404">
|
||||
确保您在包含 `docs.json` 的文件夹中运行 `mintlify dev`。
|
||||
</Accordion>
|
||||
|
||||
</AccordionGroup>
|
||||
|
||||
</Accordion>
|
||||
|
||||
</AccordionGroup>
|
||||
|
||||
### 部署您的更改
|
||||
|
||||
<AccordionGroup>
|
||||
|
||||
<Accordion icon="message-bot" title="安装我们的 GitHub 应用">
|
||||
我们的 GitHub 应用会自动将您存储库中的更改传播到您的部署中。更改将在推送到默认分支后自动部署到生产环境。
|
||||
|
||||
在您的[仪表板](https://dashboard.mintlify.com)上找到安装链接。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion icon="rocket" title="推送到默认分支">
|
||||
将更改推送到与您的项目关联的默认分支（通常是 `main`）以自动部署到生产环境。
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```bash Terminal
|
||||
git add .
|
||||
git commit -m "更新文档"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Accordion>
|
||||
|
||||
</AccordionGroup>
|
||||
Reference in New Issue
Block a user