feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
315
docs/规划/关于部署/本地开发.md
Normal file
315
docs/规划/关于部署/本地开发.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 考培练系统本地开发环境配置指南
|
||||
|
||||
## 🎯 概述
|
||||
|
||||
本文档为开发者提供本地开发环境的配置说明，确保开发者能够在本地连接远程数据库进行开发，而不与生产环境配置产生冲突。
|
||||
|
||||
## 📋 环境要求
|
||||
|
||||
### 系统要求
|
||||
- Node.js 18+
|
||||
- Python 3.11+
|
||||
- Git
|
||||
- 网络访问远程MySQL服务器
|
||||
|
||||
### 开发工具推荐
|
||||
- VS Code / WebStorm
|
||||
- Postman / Insomnia（API测试）
|
||||
- MySQL Workbench（数据库管理）
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 克隆项目
|
||||
```bash
|
||||
git clone https://github.com/nongjun/ai-development-workspace.git
|
||||
cd ai-development-workspace
|
||||
```
|
||||
|
||||
### 2. 后端配置
|
||||
|
||||
#### 2.1 创建环境配置
|
||||
```bash
|
||||
cd kaopeilian-backend
|
||||
|
||||
# 复制环境配置模板
|
||||
cp .env.example .env
|
||||
|
||||
# 编辑配置文件（保持远程数据库配置）
|
||||
# .env 文件内容应该是：
|
||||
# DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4
|
||||
# REDIS_URL=redis://localhost:6379/0
|
||||
# DEBUG=true
|
||||
```
|
||||
|
||||
#### 2.2 安装依赖
|
||||
```bash
|
||||
# 创建虚拟环境（推荐）
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# 或
|
||||
venv\Scripts\activate # Windows
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### 2.3 启动后端服务
|
||||
```bash
|
||||
# 方式1：直接运行（推荐，支持热重载）
|
||||
python app/main.py
|
||||
|
||||
# 方式2：使用uvicorn
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
|
||||
# 验证启动
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
### 3. 前端配置
|
||||
|
||||
#### 3.1 安装依赖
|
||||
```bash
|
||||
cd kaopeilian-frontend
|
||||
|
||||
# 使用npm
|
||||
npm install
|
||||
|
||||
# 或使用pnpm（推荐）
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### 3.2 配置环境变量
|
||||
```bash
|
||||
# 检查env.example文件
|
||||
cat env.example
|
||||
|
||||
# 如果需要，可以创建.env.local文件覆盖配置
|
||||
echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local
|
||||
echo "VITE_USE_MOCK_DATA=false" >> .env.local
|
||||
```
|
||||
|
||||
#### 3.3 启动前端服务
|
||||
```bash
|
||||
# 开发模式启动（支持HMR热重载）
|
||||
npm run dev
|
||||
|
||||
# 或使用pnpm
|
||||
pnpm dev
|
||||
|
||||
# 访问地址：http://localhost:3001
|
||||
```
|
||||
|
||||
## 🔧 配置说明
|
||||
|
||||
### 数据库连接配置
|
||||
|
||||
#### 远程MySQL连接信息
|
||||
- **主机**: `120.79.247.16` 或 `aiedu.ireborn.com.cn`
|
||||
- **端口**: `3306`
|
||||
- **数据库**: `kaopeilian`
|
||||
- **用户**: `root`
|
||||
- **密码**: `Kaopeilian2025!@#`
|
||||
|
||||
#### 连接字符串格式
|
||||
```env
|
||||
# 注意：密码中的特殊字符需要URL编码
|
||||
DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4
|
||||
|
||||
# 特殊字符编码对照：
|
||||
# ! → %21
|
||||
# @ → %40
|
||||
# # → %23
|
||||
```
|
||||
|
||||
### 前端API配置
|
||||
|
||||
#### 开发环境
|
||||
- **API地址**: `http://localhost:8000`
|
||||
- **代理配置**: Vite自动代理`/api`请求到后端
|
||||
- **Mock数据**: 默认关闭（`VITE_USE_MOCK_DATA=false`）
|
||||
|
||||
#### 调试配置
|
||||
```typescript
|
||||
// src/config/env.ts
|
||||
public readonly API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000'
|
||||
public readonly USE_MOCK_DATA = import.meta.env.VITE_USE_MOCK_DATA === 'true'
|
||||
```
|
||||
|
||||
## 🛠️ 开发工作流
|
||||
|
||||
### 日常开发流程
|
||||
|
||||
1. **启动后端服务**：
|
||||
```bash
|
||||
cd kaopeilian-backend
|
||||
python app/main.py # 自动热重载
|
||||
```
|
||||
|
||||
2. **启动前端服务**：
|
||||
```bash
|
||||
cd kaopeilian-frontend
|
||||
npm run dev # HMR热重载
|
||||
```
|
||||
|
||||
3. **访问应用**：
|
||||
- 前端：http://localhost:3001
|
||||
- 后端API：http://localhost:8000
|
||||
- API文档：http://localhost:8000/docs
|
||||
|
||||
### 代码提交流程
|
||||
|
||||
1. **本地测试**：
|
||||
```bash
|
||||
# 后端测试
|
||||
cd kaopeilian-backend
|
||||
pytest tests/
|
||||
|
||||
# 前端测试
|
||||
cd kaopeilian-frontend
|
||||
npm run test
|
||||
npm run lint
|
||||
```
|
||||
|
||||
2. **提交代码**：
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: 添加新功能"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
3. **自动部署**：
|
||||
- 推送到main分支后，生产服务器会自动更新
|
||||
- 通过GitHub Webhook机制触发
|
||||
- 自动重新构建和部署
|
||||
|
||||
## 🔍 故障排查
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. 数据库连接失败
|
||||
```bash
|
||||
# 检查网络连接
|
||||
ping 120.79.247.16
|
||||
|
||||
# 测试MySQL连接
|
||||
mysql -h 120.79.247.16 -P 3306 -u root -p
|
||||
|
||||
# 检查环境变量
|
||||
cat .env | grep DATABASE_URL
|
||||
```
|
||||
|
||||
#### 2. 前端API请求失败
|
||||
```bash
|
||||
# 检查后端是否启动
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# 检查前端代理配置
|
||||
cat vite.config.ts | grep proxy -A 10
|
||||
|
||||
# 检查浏览器Network面板
|
||||
# 确认请求是否正确转发到 http://localhost:8000
|
||||
```
|
||||
|
||||
#### 3. 热重载不工作
|
||||
```bash
|
||||
# 后端：确认使用--reload参数
|
||||
ps aux | grep uvicorn
|
||||
|
||||
# 前端：确认开发模式启动
|
||||
ps aux | grep vite
|
||||
```
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **后端调试**：
|
||||
```bash
|
||||
# 查看详细日志
|
||||
python app/main.py --log-level debug
|
||||
|
||||
# 使用调试器
|
||||
python -m pdb app/main.py
|
||||
```
|
||||
|
||||
2. **前端调试**：
|
||||
```bash
|
||||
# 查看构建信息
|
||||
npm run dev -- --debug
|
||||
|
||||
# 检查环境变量
|
||||
npm run dev -- --mode development
|
||||
```
|
||||
|
||||
3. **数据库调试**：
|
||||
```bash
|
||||
# 连接数据库
|
||||
mysql -h 120.79.247.16 -P 3306 -u root -p kaopeilian
|
||||
|
||||
# 查看表结构
|
||||
DESCRIBE users;
|
||||
DESCRIBE courses;
|
||||
```
|
||||
|
||||
## 📚 开发规范
|
||||
|
||||
### 代码规范
|
||||
- **后端**：使用black格式化，flake8检查
|
||||
- **前端**：使用ESLint和Prettier
|
||||
- **提交信息**：使用约定式提交格式
|
||||
|
||||
### API开发规范
|
||||
- **路径**：`/api/v1/{module}/{action}`
|
||||
- **响应格式**：统一使用`{code, message, data}`
|
||||
- **错误处理**：统一异常处理和日志记录
|
||||
|
||||
### 数据库规范
|
||||
- **字符集**：utf8mb4
|
||||
- **命名**：下划线命名法
|
||||
- **迁移**：使用Alembic管理数据库版本
|
||||
|
||||
## 🔄 与生产环境的区别
|
||||
|
||||
| 配置项 | 本地开发 | 生产环境 |
|
||||
|--------|----------|----------|
|
||||
| 数据库 | 远程MySQL (120.79.247.16) | 本地MySQL容器 |
|
||||
| Redis | 本地Redis | Redis容器 |
|
||||
| 前端 | 开发服务器 (HMR) | 静态文件 (Nginx) |
|
||||
| 后端 | 直接运行 | Docker容器 |
|
||||
| HTTPS | 不需要 | SSL证书 |
|
||||
| 域名 | localhost | aiedu.ireborn.com.cn |
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
### 1. 环境隔离
|
||||
- 使用不同的配置文件
|
||||
- 不要在开发环境修改生产数据
|
||||
- 定期同步测试数据
|
||||
|
||||
### 2. 代码管理
|
||||
- 频繁提交小的更改
|
||||
- 使用有意义的提交信息
|
||||
- 提交前进行本地测试
|
||||
|
||||
### 3. 调试技巧
|
||||
- 使用浏览器开发者工具
|
||||
- 查看Network面板确认API调用
|
||||
- 使用Console查看前端日志
|
||||
- 查看后端日志文件
|
||||
|
||||
### 4. 性能优化
|
||||
- 使用代码分割
|
||||
- 启用缓存机制
|
||||
- 优化数据库查询
|
||||
- 监控API响应时间
|
||||
|
||||
## 🆘 获取帮助
|
||||
|
||||
### 联系方式
|
||||
- **技术支持**：查看项目README
|
||||
- **问题反馈**：GitHub Issues
|
||||
- **文档更新**：提交PR
|
||||
|
||||
### 相关文档
|
||||
- [API接口文档](../全链路联调/前后端接口约定.md)
|
||||
- [数据库架构](../../kaopeilian-backend/数据库架构-统一版.md)
|
||||
- [联调经验](../全链路联调/联调经验汇总.md)
|
||||
- [服务器部署](./服务器部署经验.md)
|
||||
Reference in New Issue
Block a user