mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
500 lines
9.9 KiB
Plaintext
500 lines
9.9 KiB
Plaintext
---
|
||
title: '开发指南'
|
||
description: 'MCPHub 本地开发环境搭建和开发工作流指南'
|
||
---
|
||
|
||
## 概述
|
||
|
||
本指南将帮助您搭建 MCPHub 的本地开发环境，了解项目结构，并掌握开发工作流。
|
||
|
||
<Info>**前提条件**：请确保已安装 Node.js 18+ 和 Git。</Info>
|
||
|
||
## 环境准备
|
||
|
||
### 系统要求
|
||
|
||
在开始开发之前，请确保您的系统满足以下要求：
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="软件依赖" icon="download">
|
||
- **Node.js**: 18.0+ 版本 - **npm**: 8.0+ 版本 - **Git**: 最新版本 - **Docker**:
|
||
可选，用于容器化开发
|
||
</Card>
|
||
<Card title="推荐工具" icon="toolbox">
|
||
- **VS Code**: 推荐的代码编辑器 - **Postman**: API 测试工具 - **TablePlus**: 数据库管理工具 -
|
||
**Docker Desktop**: 容器管理
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
### 验证环境
|
||
|
||
```bash
|
||
# 检查 Node.js 版本
|
||
node --version # 应该 >= 18.0.0
|
||
|
||
# 检查 npm 版本
|
||
npm --version # 应该 >= 8.0.0
|
||
|
||
# 检查 Git 版本
|
||
git --version
|
||
|
||
# 检查 Docker（可选）
|
||
docker --version
|
||
```
|
||
|
||
## 克隆项目
|
||
|
||
### 获取源代码
|
||
|
||
```bash
|
||
# 克隆主仓库
|
||
git clone https://github.com/mcphub/mcphub.git
|
||
cd mcphub
|
||
|
||
# 或者克隆您的 fork
|
||
git clone https://github.com/YOUR_USERNAME/mcphub.git
|
||
cd mcphub
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
mcphub/
|
||
├── src/ # 源代码目录
|
||
│ ├── controllers/ # 控制器层
|
||
│ ├── middleware/ # 中间件
|
||
│ ├── models/ # 数据模型
|
||
│ ├── routes/ # 路由定义
|
||
│ ├── services/ # 业务逻辑层
|
||
│ ├── utils/ # 工具函数
|
||
│ └── index.ts # 应用入口
|
||
├── tests/ # 测试文件
|
||
├── docs/ # 文档源码
|
||
├── docker/ # Docker 配置
|
||
├── scripts/ # 构建脚本
|
||
├── prisma/ # 数据库模式
|
||
├── package.json # 项目依赖
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── .env.example # 环境变量示例
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
### 安装项目依赖
|
||
|
||
```bash
|
||
# 安装生产和开发依赖
|
||
npm install
|
||
|
||
# 仅安装生产依赖
|
||
npm ci --only=production
|
||
```
|
||
|
||
### 全局工具安装
|
||
|
||
```bash
|
||
# 安装 TypeScript 编译器
|
||
npm install -g typescript
|
||
|
||
# 安装开发工具
|
||
npm install -g tsx nodemon prisma
|
||
|
||
# 安装 MCPHub CLI（可选）
|
||
npm install -g @mcphub/cli
|
||
```
|
||
|
||
## 配置开发环境
|
||
|
||
### 环境变量配置
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑环境变量
|
||
nano .env
|
||
```
|
||
|
||
开发环境的 `.env` 配置示例：
|
||
|
||
```bash title=".env"
|
||
# 应用配置
|
||
NODE_ENV=development
|
||
PORT=3000
|
||
HOST=localhost
|
||
|
||
# 数据库配置
|
||
DATABASE_URL=sqlite:./data/dev.db
|
||
|
||
# JWT 配置
|
||
JWT_SECRET=dev-jwt-secret-key
|
||
JWT_EXPIRES_IN=7d
|
||
|
||
# 日志配置
|
||
LOG_LEVEL=debug
|
||
LOG_FORMAT=dev
|
||
|
||
# CORS 配置
|
||
CORS_ORIGIN=http://localhost:3000,http://localhost:3001
|
||
|
||
# 管理员账户
|
||
ADMIN_EMAIL=dev@mcphub.io
|
||
ADMIN_PASSWORD=dev123
|
||
|
||
# 开发功能开关
|
||
ENABLE_DEBUG_ROUTES=true
|
||
ENABLE_SWAGGER=true
|
||
ENABLE_HOT_RELOAD=true
|
||
```
|
||
|
||
### 数据库初始化
|
||
|
||
```bash
|
||
# 生成 Prisma 客户端
|
||
npx prisma generate
|
||
|
||
# 运行数据库迁移
|
||
npx prisma migrate dev --name init
|
||
|
||
# 填充测试数据
|
||
npm run db:seed
|
||
```
|
||
|
||
## 启动开发服务器
|
||
|
||
### 开发模式启动
|
||
|
||
```bash
|
||
# 启动开发服务器（带热重载）
|
||
npm run dev
|
||
|
||
# 或者使用 tsx 直接运行
|
||
npx tsx watch src/index.ts
|
||
```
|
||
|
||
### 后台模式启动
|
||
|
||
```bash
|
||
# 使用 PM2 启动（需要先安装 PM2）
|
||
npm install -g pm2
|
||
npm run dev:pm2
|
||
|
||
# 查看进程状态
|
||
pm2 status
|
||
|
||
# 查看日志
|
||
pm2 logs mcphub-dev
|
||
```
|
||
|
||
### 验证启动
|
||
|
||
访问以下 URL 验证服务是否正常启动：
|
||
|
||
- **主页**: http://localhost:3000
|
||
- **健康检查**: http://localhost:3000/health
|
||
- **API 文档**: http://localhost:3000/api/docs
|
||
- **管理界面**: http://localhost:3000/admin
|
||
|
||
## 开发工作流
|
||
|
||
### 1. 功能开发流程
|
||
|
||
```bash
|
||
# 1. 创建功能分支
|
||
git checkout -b feature/your-feature-name
|
||
|
||
# 2. 进行开发...
|
||
|
||
# 3. 运行测试
|
||
npm test
|
||
|
||
# 4. 代码格式化
|
||
npm run lint:fix
|
||
|
||
# 5. 提交代码
|
||
git add .
|
||
git commit -m "feat: add your feature description"
|
||
|
||
# 6. 推送分支
|
||
git push origin feature/your-feature-name
|
||
|
||
# 7. 创建 Pull Request
|
||
```
|
||
|
||
### 2. 代码规范
|
||
|
||
MCPHub 项目使用以下代码规范工具：
|
||
|
||
```bash
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 自动修复
|
||
npm run lint:fix
|
||
|
||
# 格式化代码
|
||
npm run format
|
||
|
||
# 类型检查
|
||
npm run type-check
|
||
```
|
||
|
||
### 3. 测试开发
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
npm test
|
||
|
||
# 运行单元测试
|
||
npm run test:unit
|
||
|
||
# 运行集成测试
|
||
npm run test:integration
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
npm run test:coverage
|
||
|
||
# 监听模式运行测试
|
||
npm run test:watch
|
||
```
|
||
|
||
## 调试技巧
|
||
|
||
### 1. VS Code 调试配置
|
||
|
||
创建 `.vscode/launch.json` 文件：
|
||
|
||
```json title=".vscode/launch.json"
|
||
{
|
||
"version": "0.2.0",
|
||
"configurations": [
|
||
{
|
||
"name": "Debug MCPHub",
|
||
"type": "node",
|
||
"request": "launch",
|
||
"program": "${workspaceFolder}/src/index.ts",
|
||
"runtimeArgs": ["-r", "tsx/cjs"],
|
||
"env": {
|
||
"NODE_ENV": "development"
|
||
},
|
||
"console": "integratedTerminal",
|
||
"skipFiles": ["<node_internals>/**"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 日志调试
|
||
|
||
使用内置的日志系统进行调试：
|
||
|
||
```typescript
|
||
import { logger } from '@/utils/logger';
|
||
|
||
// 不同级别的日志
|
||
logger.debug('调试信息', { data });
|
||
logger.info('信息日志', { userId });
|
||
logger.warn('警告信息', { error });
|
||
logger.error('错误信息', { error, stack });
|
||
```
|
||
|
||
### 3. 数据库调试
|
||
|
||
```bash
|
||
# 查看数据库内容
|
||
npx prisma studio
|
||
|
||
# 重置数据库
|
||
npx prisma migrate reset
|
||
|
||
# 查看迁移状态
|
||
npx prisma migrate status
|
||
```
|
||
|
||
## 常用开发命令
|
||
|
||
### 项目管理
|
||
|
||
```bash
|
||
# 安装新依赖
|
||
npm install package-name
|
||
npm install -D package-name # 开发依赖
|
||
|
||
# 更新依赖
|
||
npm update
|
||
|
||
# 清理缓存
|
||
npm cache clean --force
|
||
|
||
# 重新安装依赖
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
```
|
||
|
||
### 构建和部署
|
||
|
||
```bash
|
||
# 构建项目
|
||
npm run build
|
||
|
||
# 预览构建结果
|
||
npm run preview
|
||
|
||
# 构建 Docker 镜像
|
||
npm run docker:build
|
||
|
||
# 运行 Docker 容器
|
||
npm run docker:run
|
||
```
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 创建新迁移
|
||
npx prisma migrate dev --name your-migration-name
|
||
|
||
# 重置数据库
|
||
npx prisma migrate reset
|
||
|
||
# 推送模式变更
|
||
npx prisma db push
|
||
|
||
# 生成客户端
|
||
npx prisma generate
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
<AccordionGroup>
|
||
<Accordion icon="question" title="端口被占用">
|
||
**错误信息**: `Error: listen EADDRINUSE :::3000`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 查找占用端口的进程
|
||
lsof -i :3000
|
||
|
||
# 杀死进程
|
||
kill -9 PID
|
||
|
||
# 或者使用不同端口
|
||
PORT=3001 npm run dev
|
||
```
|
||
</Accordion>
|
||
|
||
<Accordion icon="question" title="数据库连接失败">
|
||
**可能原因**: 数据库文件权限或路径问题 **解决方案**: ```bash # 检查数据库文件 ls -la data/ #
|
||
重新初始化数据库 rm data/dev.db npx prisma migrate dev ```
|
||
</Accordion>
|
||
|
||
<Accordion icon="question" title="TypeScript 编译错误">
|
||
**解决方案**:
|
||
```bash
|
||
# 清理构建缓存
|
||
npm run clean
|
||
|
||
# 重新安装类型定义
|
||
npm install @types/node @types/express
|
||
|
||
# 重新生成 Prisma 客户端
|
||
npx prisma generate
|
||
```
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## 进阶主题
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="架构设计" icon="building" href="/zh/development/architecture">
|
||
了解 MCPHub 的整体架构和设计模式
|
||
</Card>
|
||
<Card title="API 开发" icon="code" href="/zh/development/api-development">
|
||
学习如何开发和设计 RESTful API
|
||
</Card>
|
||
<Card title="性能优化" icon="rocket" href="/zh/development/performance">
|
||
掌握性能分析和优化技巧
|
||
</Card>
|
||
<Card title="部署指南" icon="cloud" href="/zh/deployment/production">
|
||
了解生产环境部署的最佳实践
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
---
|
||
|
||
<Tip>
|
||
**开发小贴士**: 建议使用 VS Code 扩展 "Prisma"、"TypeScript Importer" 和 "REST Client"
|
||
来提高开发效率。
|
||
</Tip>
|
||
|
||
```bash yarn
|
||
yarn global add mintlify
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
**步骤 2**：导航到文档目录（`docs.json` 文件所在的位置）并执行以下命令：
|
||
|
||
```bash
|
||
mintlify dev
|
||
```
|
||
|
||
您的文档的本地预览将在 `http://localhost:3000` 可用。
|
||
|
||
### 自定义端口
|
||
|
||
默认情况下，Mintlify 使用端口 3000。您可以使用 `--port` 标志自定义 Mintlify 运行的端口。例如，要在端口 3333 上运行 Mintlify，请使用此命令：
|
||
|
||
```bash
|
||
mintlify dev --port 3333
|
||
```
|
||
|
||
如果您尝试在已在使用的端口上运行 Mintlify，它将使用下一个可用端口：
|
||
|
||
```md
|
||
端口 3000 已在使用中。尝试使用 3001。
|
||
```
|
||
|
||
## Mintlify 版本
|
||
|
||
请注意，每个 CLI 版本都与特定版本的 Mintlify 相关联。如果您的本地网站与生产版本不一致，请更新 CLI：
|
||
|
||
<CodeGroup>
|
||
|
||
```bash npm
|
||
npm i -g mintlify@latest
|
||
```
|
||
|
||
```bash yarn
|
||
yarn global upgrade mintlify
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
## 验证链接
|
||
|
||
CLI 可以帮助验证文档中的引用链接。要识别任何损坏的链接，请使用以下命令：
|
||
|
||
```bash
|
||
mintlify broken-links
|
||
```
|
||
|
||
## 部署
|
||
|
||
<Tip>
|
||
Mintlify 通过我们的 GitHub 应用实现持续部署。安装后，推送到您的默认分支将自动更新您的文档。
|
||
</Tip>
|
||
|
||
### GitHub 集成
|
||
|
||
我们强烈建议部署使用我们的 [GitHub 集成](https://github.com/apps/mintlify)，该集成在有人将更改推送到您的存储库时自动部署更改。只需安装 GitHub 应用到您的存储库并推送到您的默认分支！安装链接可以在您的 [仪表板](https://dashboard.mintlify.com) 中找到。
|
||
|
||
#### 故障排除
|
||
|
||
- Mintlify dev 无法运行 - 运行 `mintlify install` 它将重新安装依赖项。
|
||
- 页面加载为 404 - 确保您在包含 `docs.json` 的文件夹中运行
|
||
|
||
## 代码格式化
|
||
|
||
我们已经内置了对自动代码格式化的支持！我们使用 [Prettier](https://prettier.io/) 来格式化文件。
|