feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
317
知识库/开发环境使用指南.md
Normal file
317
知识库/开发环境使用指南.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# 考培练系统 - 开发环境使用指南
|
||||
|
||||
## 🎯 概述
|
||||
|
||||
本项目已经配置了完整的Docker化开发环境，支持前后端代码热重载，确保开发环境的一致性。
|
||||
|
||||
## 🏗️ 架构说明
|
||||
|
||||
### 当前实现的方案
|
||||
|
||||
我们采用了**混合架构**：
|
||||
- **数据库层**：MySQL + Redis 运行在 Docker 容器中
|
||||
- **应用层**：前后端服务可以选择 Docker 或本地运行
|
||||
- **优势**：既保证了数据环境的一致性，又提供了开发的灵活性
|
||||
|
||||
### 服务端口分配
|
||||
|
||||
| 服务 | 端口 | 访问地址 | 说明 |
|
||||
|-----|------|----------|------|
|
||||
| 前端开发服务器 | 3001 | http://localhost:3001 | Vite 热重载服务 |
|
||||
| 后端API服务 | 8000 | http://localhost:8000 | FastAPI 热重载服务 |
|
||||
| API文档 | 8000 | http://localhost:8000/docs | Swagger UI |
|
||||
| MySQL数据库 | 3306 | localhost:3306 | 开发数据库 |
|
||||
| Redis缓存 | 6379 | localhost:6379 | 缓存服务 |
|
||||
| phpMyAdmin | 8080 | http://localhost:8080 | 数据库管理界面（可选） |
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 方案一：推荐的混合开发环境
|
||||
|
||||
1. **启动基础服务（数据库）**
|
||||
```bash
|
||||
# 启动 MySQL 和 Redis
|
||||
docker-compose -f docker-compose.dev.yml up -d mysql-dev redis-dev
|
||||
```
|
||||
|
||||
2. **启动后端服务**
|
||||
```bash
|
||||
cd kaopeilian-backend
|
||||
source venv/bin/activate
|
||||
export DATABASE_URL="mysql://root:Kaopeilian2025!@#@localhost:3306/kaopeilian"
|
||||
export REDIS_URL="redis://localhost:6379/0"
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
3. **启动前端服务**
|
||||
```bash
|
||||
cd kaopeilian-frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 方案二：完全Docker化开发环境
|
||||
|
||||
1. **一键启动所有服务**
|
||||
```bash
|
||||
./start-dev.sh
|
||||
```
|
||||
|
||||
2. **启动服务 + 管理工具**
|
||||
```bash
|
||||
./start-dev.sh --with-admin # 包含 phpMyAdmin
|
||||
./start-dev.sh --full # 包含所有工具
|
||||
```
|
||||
|
||||
3. **停止服务**
|
||||
```bash
|
||||
./stop-dev.sh
|
||||
```
|
||||
|
||||
## 🔧 开发环境配置
|
||||
|
||||
### 环境变量配置
|
||||
|
||||
#### 后端环境变量
|
||||
```bash
|
||||
# 数据库配置
|
||||
DATABASE_URL=mysql://root:Kaopeilian2025!@#@localhost:3306/kaopeilian
|
||||
MYSQL_HOST=localhost
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_USER=root
|
||||
MYSQL_PASSWORD=Kaopeilian2025!@#
|
||||
MYSQL_DATABASE=kaopeilian
|
||||
|
||||
# Redis配置
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
REDIS_DB=0
|
||||
|
||||
# 开发模式
|
||||
DEBUG=true
|
||||
ENV=development
|
||||
```
|
||||
|
||||
#### 前端环境变量
|
||||
```bash
|
||||
NODE_ENV=development
|
||||
VITE_API_BASE_URL=http://localhost:8000
|
||||
VITE_WS_BASE_URL=ws://localhost:8000
|
||||
VITE_USE_MOCK_DATA=false
|
||||
VITE_ENABLE_DEVTOOLS=true
|
||||
VITE_ENABLE_REQUEST_LOG=true
|
||||
```
|
||||
|
||||
### 热重载配置
|
||||
|
||||
#### 前端热重载
|
||||
- **文件监听**：`src/` 目录下的所有文件
|
||||
- **自动刷新**：代码修改后自动刷新浏览器
|
||||
- **HMR支持**：Vue组件支持热模块替换
|
||||
|
||||
#### 后端热重载
|
||||
- **文件监听**：`app/` 目录下的所有 `.py` 文件
|
||||
- **自动重启**：代码修改后自动重启服务
|
||||
- **重载目录**：`--reload-dir /app/app`
|
||||
|
||||
## 📋 常用命令
|
||||
|
||||
### Docker管理
|
||||
```bash
|
||||
# 查看容器状态
|
||||
docker ps
|
||||
|
||||
# 查看服务日志
|
||||
docker-compose -f docker-compose.dev.yml logs -f [service_name]
|
||||
|
||||
# 重启特定服务
|
||||
docker-compose -f docker-compose.dev.yml restart [service_name]
|
||||
|
||||
# 进入容器
|
||||
docker exec -it kaopeilian-mysql-dev bash
|
||||
docker exec -it kaopeilian-redis-dev redis-cli
|
||||
```
|
||||
|
||||
### 数据库管理
|
||||
```bash
|
||||
# 连接MySQL
|
||||
mysql -h localhost -P 3306 -u root -p
|
||||
|
||||
# 导入SQL文件
|
||||
mysql -h localhost -P 3306 -u root -p kaopeilian < backup.sql
|
||||
|
||||
# Redis操作
|
||||
redis-cli -h localhost -p 6379
|
||||
```
|
||||
|
||||
### 开发调试
|
||||
```bash
|
||||
# 查看后端日志
|
||||
tail -f kaopeilian-backend/logs/app.log
|
||||
|
||||
# 查看前端构建日志
|
||||
cd kaopeilian-frontend && npm run dev
|
||||
|
||||
# 运行测试
|
||||
cd kaopeilian-backend && python -m pytest
|
||||
cd kaopeilian-frontend && npm test
|
||||
```
|
||||
|
||||
## 🔍 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. 端口占用
|
||||
```bash
|
||||
# 查看端口占用
|
||||
lsof -i :3001 # 前端
|
||||
lsof -i :8000 # 后端
|
||||
lsof -i :3306 # MySQL
|
||||
|
||||
# 终止占用进程
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
#### 2. Docker相关问题
|
||||
```bash
|
||||
# 清理Docker缓存
|
||||
docker system prune -a
|
||||
|
||||
# 重建镜像
|
||||
docker-compose -f docker-compose.dev.yml build --no-cache
|
||||
|
||||
# 删除数据卷（谨慎使用）
|
||||
docker volume rm kaopeilian-mysql-dev-data
|
||||
```
|
||||
|
||||
#### 3. 前端依赖问题
|
||||
```bash
|
||||
cd kaopeilian-frontend
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
#### 4. 后端依赖问题
|
||||
```bash
|
||||
cd kaopeilian-backend
|
||||
pip install --upgrade pip
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 服务健康检查
|
||||
|
||||
#### 检查服务状态
|
||||
```bash
|
||||
# 后端健康检查
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# 前端服务检查
|
||||
curl http://localhost:3001/
|
||||
|
||||
# 数据库连接检查
|
||||
mysqladmin ping -h localhost -P 3306 -u root -p
|
||||
|
||||
# Redis连接检查
|
||||
redis-cli -h localhost -p 6379 ping
|
||||
```
|
||||
|
||||
## 🎨 开发工作流
|
||||
|
||||
### 推荐的开发流程
|
||||
|
||||
1. **启动基础服务**
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml up -d mysql-dev redis-dev
|
||||
```
|
||||
|
||||
2. **启动后端（支持热重载）**
|
||||
```bash
|
||||
cd kaopeilian-backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
3. **启动前端（支持热重载）**
|
||||
```bash
|
||||
cd kaopeilian-frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. **开始开发**
|
||||
- 修改后端代码：`kaopeilian-backend/app/` 目录
|
||||
- 修改前端代码：`kaopeilian-frontend/src/` 目录
|
||||
- 代码修改会自动触发重载
|
||||
|
||||
5. **测试和调试**
|
||||
- 前端：http://localhost:3001
|
||||
- 后端API：http://localhost:8000/docs
|
||||
- 数据库管理：http://localhost:8080 (如果启用)
|
||||
|
||||
## 📚 项目结构
|
||||
|
||||
```
|
||||
考培练系统/
|
||||
├── docker-compose.dev.yml # 开发环境Docker配置
|
||||
├── start-dev.sh # 开发环境启动脚本
|
||||
├── stop-dev.sh # 开发环境停止脚本
|
||||
├── kaopeilian-backend/ # 后端项目
|
||||
│ ├── Dockerfile.dev # 后端开发环境Dockerfile
|
||||
│ ├── app/ # 应用代码
|
||||
│ ├── requirements.txt # Python依赖
|
||||
│ └── venv/ # 虚拟环境
|
||||
├── kaopeilian-frontend/ # 前端项目
|
||||
│ ├── Dockerfile.dev # 前端开发环境Dockerfile
|
||||
│ ├── src/ # 源代码
|
||||
│ ├── package.json # Node.js依赖
|
||||
│ └── node_modules/ # 依赖包
|
||||
└── 开发环境使用指南.md # 本文档
|
||||
```
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 开发建议
|
||||
|
||||
1. **使用混合架构**：数据库用Docker，应用用本地开发
|
||||
2. **保持热重载**：确保代码修改能立即生效
|
||||
3. **环境一致性**：使用相同的数据库和缓存配置
|
||||
4. **日志监控**：定期查看应用日志排查问题
|
||||
5. **定期清理**：清理Docker缓存和无用的镜像
|
||||
|
||||
### 代码规范
|
||||
|
||||
1. **后端开发**：
|
||||
- 遵循PEP 8代码规范
|
||||
- 使用类型提示
|
||||
- 编写单元测试
|
||||
|
||||
2. **前端开发**：
|
||||
- 使用TypeScript
|
||||
- 遵循Vue 3组合式API
|
||||
- 使用ESLint和Prettier
|
||||
|
||||
### 版本控制
|
||||
|
||||
1. **忽略文件**：
|
||||
- `node_modules/`
|
||||
- `venv/`
|
||||
- `*.log`
|
||||
- `.env.local`
|
||||
|
||||
2. **提交规范**：
|
||||
- feat: 新功能
|
||||
- fix: 修复问题
|
||||
- docs: 文档更新
|
||||
- style: 代码格式
|
||||
- refactor: 重构代码
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
- [FastAPI文档](https://fastapi.tiangolo.com/)
|
||||
- [Vue 3文档](https://vuejs.org/)
|
||||
- [Docker文档](https://docs.docker.com/)
|
||||
- [MySQL文档](https://dev.mysql.com/doc/)
|
||||
- [Redis文档](https://redis.io/documentation)
|
||||
|
||||
---
|
||||
|
||||
**注意**：本指南基于当前的开发环境配置，如有更新请及时同步文档。
|
||||
Reference in New Issue
Block a user