012-kaopeilian/docs/规划/关于部署/本地开发.md

考培练系统本地开发环境配置指南

🎯 概述

本文档为开发者提供本地开发环境的配置说明，确保开发者能够在本地连接远程数据库进行开发，而不与生产环境配置产生冲突。

📋 环境要求

系统要求

• Node.js 18+
• Python 3.11+
• Git
• 网络访问远程MySQL服务器

开发工具推荐

• VS Code / WebStorm
• Postman / Insomnia（API测试）
• MySQL Workbench（数据库管理）

🚀 快速开始

1. 克隆项目

git clone https://github.com/nongjun/ai-development-workspace.git
cd ai-development-workspace

2. 后端配置

2.1 创建环境配置

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 安装依赖

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

2.3 启动后端服务

# 方式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 安装依赖

cd kaopeilian-frontend

# 使用npm
npm install

# 或使用pnpm（推荐）
pnpm install

3.2 配置环境变量

# 检查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 启动前端服务

# 开发模式启动（支持HMR热重载）
npm run dev

# 或使用pnpm
pnpm dev

# 访问地址：http://localhost:3001

🔧 配置说明

数据库连接配置

远程MySQL连接信息

• 主机: 120.79.247.16 或 aiedu.ireborn.com.cn
• 端口: 3306
• 数据库: kaopeilian
• 用户: root
• 密码: Kaopeilian2025!@#

连接字符串格式

# 注意：密码中的特殊字符需要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）

调试配置

// 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. 启动后端服务：

   cd kaopeilian-backend
   python app/main.py  # 自动热重载
   

2. 启动前端服务：

   cd kaopeilian-frontend  
   npm run dev  # HMR热重载
   

3. 访问应用：

   • 前端：http://localhost:3001
   • 后端API：http://localhost:8000
   • API文档：http://localhost:8000/docs

代码提交流程

1. 本地测试：

   # 后端测试
   cd kaopeilian-backend
   pytest tests/
   
   # 前端测试
   cd kaopeilian-frontend
   npm run test
   npm run lint
   

2. 提交代码：

   git add .
   git commit -m "feat: 添加新功能"
   git push origin main
   

3. 自动部署：

   • 推送到main分支后，生产服务器会自动更新
   • 通过GitHub Webhook机制触发
   • 自动重新构建和部署

🔍 故障排查

常见问题

1. 数据库连接失败

# 检查网络连接
ping 120.79.247.16

# 测试MySQL连接
mysql -h 120.79.247.16 -P 3306 -u root -p

# 检查环境变量
cat .env | grep DATABASE_URL

2. 前端API请求失败

# 检查后端是否启动
curl http://localhost:8000/health

# 检查前端代理配置
cat vite.config.ts | grep proxy -A 10

# 检查浏览器Network面板
# 确认请求是否正确转发到 http://localhost:8000

3. 热重载不工作

# 后端：确认使用--reload参数
ps aux | grep uvicorn

# 前端：确认开发模式启动
ps aux | grep vite

调试技巧

1. 后端调试：

   # 查看详细日志
   python app/main.py --log-level debug
   
   # 使用调试器
   python -m pdb app/main.py
   

2. 前端调试：

   # 查看构建信息
   npm run dev -- --debug
   
   # 检查环境变量
   npm run dev -- --mode development
   

3. 数据库调试：

   # 连接数据库
   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接口文档
• 数据库架构
• 联调经验
• 服务器部署