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. 启动基础服务（数据库）

   # 启动 MySQL 和 Redis
   docker-compose -f docker-compose.dev.yml up -d mysql-dev redis-dev
   

2. 启动后端服务

   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. 启动前端服务

   cd kaopeilian-frontend
   npm run dev
   

方案二：完全Docker化开发环境

1. 一键启动所有服务

   ./start-dev.sh
   

2. 启动服务 + 管理工具

   ./start-dev.sh --with-admin  # 包含 phpMyAdmin
   ./start-dev.sh --full        # 包含所有工具
   

3. 停止服务

   ./stop-dev.sh
   

🔧 开发环境配置

环境变量配置

后端环境变量

# 数据库配置
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

前端环境变量

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管理

# 查看容器状态
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

数据库管理

# 连接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

开发调试

# 查看后端日志
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. 端口占用

# 查看端口占用
lsof -i :3001  # 前端
lsof -i :8000  # 后端
lsof -i :3306  # MySQL

# 终止占用进程
kill -9 <PID>

2. Docker相关问题

# 清理Docker缓存
docker system prune -a

# 重建镜像
docker-compose -f docker-compose.dev.yml build --no-cache

# 删除数据卷（谨慎使用）
docker volume rm kaopeilian-mysql-dev-data

3. 前端依赖问题

cd kaopeilian-frontend
rm -rf node_modules package-lock.json
npm install

4. 后端依赖问题

cd kaopeilian-backend
pip install --upgrade pip
pip install -r requirements.txt

服务健康检查

检查服务状态

# 后端健康检查
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. 启动基础服务

   docker-compose -f docker-compose.dev.yml up -d mysql-dev redis-dev
   

2. 启动后端（支持热重载）

   cd kaopeilian-backend
   source venv/bin/activate
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

3. 启动前端（支持热重载）

   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文档
• Vue 3文档
• Docker文档
• MySQL文档
• Redis文档

---

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