012-kaopeilian/知识库/开发环境使用指南.md

# 考培练系统 - 开发环境使用指南

## 🎯 概述

本项目已经配置了完整的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)

---

**注意**：本指南基于当前的开发环境配置，如有更新请及时同步文档。