b6a98ddaba
- 新增 DEPLOY.md 详细部署指南 - 新增 README.md 项目说明 - 更新 .env.example 添加 JWT_SECRET 示例 - 优化 db.js 数据库连接配置（支持端口和超时设置）
213 lines
3.9 KiB
Markdown
213 lines
3.9 KiB
Markdown
# API Debug Tool 部署文档
|
||
|
||
## 项目简介
|
||
|
||
API Debug Tool 是一个用于调试钉钉 API 的 Web 工具，支持多租户管理、接口管理和调试历史记录。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**: React + Vite
|
||
- **后端**: Node.js + Express
|
||
- **数据库**: MySQL 8.0+
|
||
- **认证**: JWT
|
||
|
||
## 系统要求
|
||
|
||
- Node.js >= 16.x
|
||
- MySQL >= 8.0
|
||
- npm 或 yarn
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone https://gitea.zhouzishen.cn/jason/api-debug.git
|
||
cd api-debug
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
# 安装根目录依赖
|
||
npm install
|
||
|
||
# 安装服务端依赖
|
||
cd server
|
||
npm install
|
||
|
||
# 安装客户端依赖
|
||
cd ../client
|
||
npm install
|
||
```
|
||
|
||
### 3. 配置数据库
|
||
|
||
#### 3.1 创建数据库
|
||
|
||
```sql
|
||
CREATE DATABASE api_debug CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
CREATE USER 'api-debug'@'%' IDENTIFIED BY 'your_password';
|
||
GRANT ALL PRIVILEGES ON api_debug.* TO 'api-debug'@'%';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
|
||
#### 3.2 配置环境变量
|
||
|
||
复制示例配置文件：
|
||
|
||
```bash
|
||
cd server
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，填入你的数据库配置：
|
||
|
||
```env
|
||
PORT=5001
|
||
DB_HOST=your_database_host
|
||
DB_USER=your_database_user
|
||
DB_PASSWORD=your_database_password
|
||
DB_NAME=api_debug
|
||
JWT_SECRET=your_jwt_secret_key
|
||
```
|
||
|
||
#### 3.3 初始化数据库
|
||
|
||
```bash
|
||
# 方式1: 使用 init.sql（推荐）
|
||
mysql -h your_host -u your_user -p api_debug < init.sql
|
||
|
||
# 方式2: 使用 migrate.js
|
||
node migrate.js
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
#### 开发环境
|
||
|
||
```bash
|
||
# 启动后端（在 server 目录）
|
||
npm start
|
||
|
||
# 启动前端（在 client 目录，新终端）
|
||
npm run dev
|
||
```
|
||
|
||
#### 生产环境
|
||
|
||
```bash
|
||
# 构建前端
|
||
cd client
|
||
npm run build
|
||
|
||
# 使用 PM2 启动后端
|
||
cd ../server
|
||
pm2 start index.js --name api-debug-server
|
||
|
||
# 使用 Nginx 代理前端静态文件
|
||
# 配置示例见下方
|
||
```
|
||
|
||
### 5. Nginx 配置示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
# 前端静态文件
|
||
location / {
|
||
root /path/to/api-debug/client/dist;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# 后端 API 代理
|
||
location /api {
|
||
proxy_pass http://localhost:5001;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection 'upgrade';
|
||
proxy_set_header Host $host;
|
||
proxy_cache_bypass $http_upgrade;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 默认账号
|
||
|
||
初始化后会创建默认管理员账号：
|
||
|
||
- 用户名: `admin`
|
||
- 密码: `123456`
|
||
|
||
**⚠️ 请在首次登录后立即修改密码！**
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 用户认证与授权（JWT）
|
||
- ✅ 多租户管理（支持旗舰版PP/ATS、标品PP/ATS、国际版ATS）
|
||
- ✅ 接口管理（支持分类和模块）
|
||
- ✅ 接口调试（自动签名、参数注入）
|
||
- ✅ 调试历史记录
|
||
- ✅ 用户数据隔离
|
||
- ✅ 多标签页调试
|
||
|
||
## 数据库表结构
|
||
|
||
- `users` - 用户表
|
||
- `tenants` - 租户表
|
||
- `endpoints` - 接口表
|
||
- `debug_history` - 调试历史表
|
||
- `token_cache` - Token 缓存表
|
||
- `settings` - 系统设置表
|
||
|
||
## 常见问题
|
||
|
||
### 1. 数据库连接失败
|
||
|
||
检查 `.env` 配置是否正确，确保数据库服务正在运行，防火墙允许连接。
|
||
|
||
### 2. 前端无法访问后端 API
|
||
|
||
检查 CORS 配置，确保后端已启用 `cors` 中间件。
|
||
|
||
### 3. JWT Token 过期
|
||
|
||
默认 Token 有效期为 7 天，可在 `server/routes/auth.js` 中修改 `expiresIn` 参数。
|
||
|
||
### 4. 端口冲突
|
||
|
||
如果 5001 端口被占用，修改 `.env` 中的 `PORT` 配置。
|
||
|
||
## 安全建议
|
||
|
||
1. 修改默认管理员密码
|
||
2. 使用强密码策略
|
||
3. 定期备份数据库
|
||
4. 生产环境使用 HTTPS
|
||
5. 限制数据库访问 IP
|
||
6. 定期更新依赖包
|
||
|
||
## 维护与备份
|
||
|
||
### 数据库备份
|
||
|
||
```bash
|
||
mysqldump -h your_host -u your_user -p api_debug > backup_$(date +%Y%m%d).sql
|
||
```
|
||
|
||
### 数据库恢复
|
||
|
||
```bash
|
||
mysql -h your_host -u your_user -p api_debug < backup_20260312.sql
|
||
```
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请提交 Issue 到项目仓库。
|
||
|
||
## 许可证
|
||
|
||
MIT License
|