feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
588
docs/规划/关于部署/分支管理策略.md
Normal file
588
docs/规划/关于部署/分支管理策略.md
Normal file
@@ -0,0 +1,588 @@
|
||||
# 考培练系统Git分支管理策略
|
||||
|
||||
## 🎯 策略概述
|
||||
|
||||
为了解决开发环境和生产环境配置冲突问题，以及避免服务器自动更新与开发者提交产生冲突，我们采用双分支策略：
|
||||
|
||||
- **main分支**：开发者日常开发和协作
|
||||
- **production分支**：生产环境部署和自动更新
|
||||
|
||||
## 🌿 分支结构
|
||||
|
||||
```
|
||||
GitHub Repository: nongjun/ai-development-workspace
|
||||
├── main (开发分支)
|
||||
│ ├── 开发者日常提交
|
||||
│ ├── 功能开发和Bug修复
|
||||
│ ├── 代码审查和测试
|
||||
│ └── 连接远程数据库配置
|
||||
│
|
||||
└── production (生产分支)
|
||||
├── 稳定版本发布
|
||||
├── 生产环境部署配置
|
||||
├── 自动更新目标分支
|
||||
└── 连接本地MySQL容器
|
||||
```
|
||||
|
||||
## 🔄 完整工作流程
|
||||
|
||||
### 开发者工作流程
|
||||
|
||||
#### 1. 初始环境设置
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://github.com/nongjun/ai-development-workspace.git
|
||||
cd ai-development-workspace
|
||||
|
||||
# 设置开发环境后端配置
|
||||
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
|
||||
# DEBUG=true
|
||||
```
|
||||
|
||||
#### 2. 日常开发流程
|
||||
```bash
|
||||
# 确保在main分支开发
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 创建功能分支（推荐）
|
||||
git checkout -b feature/user-management
|
||||
|
||||
# 开发工作
|
||||
# ... 编写代码 ...
|
||||
|
||||
# 本地测试
|
||||
cd kaopeilian-backend
|
||||
python app/main.py # 启动后端（连接远程数据库）
|
||||
|
||||
cd ../kaopeilian-frontend
|
||||
npm run dev # 启动前端开发服务器
|
||||
|
||||
# 功能测试通过后提交
|
||||
git add .
|
||||
git commit -m "feat: 添加用户管理功能"
|
||||
git push origin feature/user-management
|
||||
|
||||
# 合并到main分支
|
||||
git checkout main
|
||||
git merge feature/user-management
|
||||
git push origin main
|
||||
```
|
||||
|
||||
#### 3. 开发环境特点
|
||||
- **数据库**：连接远程MySQL（120.79.247.16:3306）
|
||||
- **前端**：开发服务器（http://localhost:3001）
|
||||
- **后端**：本地运行（http://localhost:8000）
|
||||
- **热重载**：前后端都支持代码热重载
|
||||
|
||||
### 生产发布流程
|
||||
|
||||
#### 1. 标准发布流程
|
||||
```bash
|
||||
# 方式A：在本地执行发布
|
||||
git checkout production
|
||||
git pull origin production
|
||||
git merge origin/main
|
||||
git push origin production # 触发生产环境自动部署
|
||||
|
||||
# 方式B：在服务器执行发布
|
||||
cd /root/aiedu
|
||||
git checkout production
|
||||
git fetch origin main
|
||||
git merge origin/main
|
||||
git push origin production # 触发自动更新
|
||||
```
|
||||
|
||||
#### 2. 自动部署流程（服务器端）
|
||||
1. **GitHub接收推送** → production分支
|
||||
2. **发送Webhook通知** → `https://aiedu.ireborn.com.cn/webhook`
|
||||
3. **服务器自动执行**：
|
||||
```bash
|
||||
# /root/aiedu/scripts/auto_update.sh 自动执行：
|
||||
git fetch origin production
|
||||
git pull origin production
|
||||
docker compose down
|
||||
docker compose build --no-cache # 如果有Dockerfile变更
|
||||
docker compose up -d
|
||||
# 健康检查和验证
|
||||
```
|
||||
|
||||
#### 3. 生产环境特点
|
||||
- **数据库**：本地MySQL容器（mysql:3306）
|
||||
- **前端**：静态文件服务（Nginx）
|
||||
- **后端**：Docker容器运行
|
||||
- **域名**：https://aiedu.ireborn.com.cn
|
||||
|
||||
## ⚙️ 技术配置详解
|
||||
|
||||
### GitHub Webhook配置
|
||||
|
||||
#### 1. 仓库Webhook设置
|
||||
- **Repository**: `https://github.com/nongjun/ai-development-workspace`
|
||||
- **Settings** → **Webhooks** → **Add webhook**
|
||||
- **Payload URL**: `https://aiedu.ireborn.com.cn/webhook`
|
||||
- **Content type**: `application/json`
|
||||
- **Secret**: `kaopeilian-webhook-secret-2025`
|
||||
- **SSL verification**: Enable SSL verification
|
||||
- **Events**: Just the push event
|
||||
- **Active**: ✅
|
||||
|
||||
#### 2. 分支过滤配置
|
||||
```python
|
||||
# /root/aiedu/scripts/webhook_handler.py
|
||||
# 关键配置：仅监听production分支
|
||||
if ref != 'refs/heads/production':
|
||||
logging.info(f"Ignoring push to branch: {ref}")
|
||||
return jsonify({"message": "Branch ignored"}), 200
|
||||
```
|
||||
|
||||
### 环境配置分离
|
||||
|
||||
#### 1. 后端配置文件
|
||||
```bash
|
||||
kaopeilian-backend/
|
||||
├── .env.example # 开发环境模板（提交到Git）
|
||||
├── .env.production # 生产环境配置（不提交到Git）
|
||||
├── .env # 开发者本地配置（不提交到Git）
|
||||
└── app/
|
||||
```
|
||||
|
||||
#### 2. 配置内容对比
|
||||
```env
|
||||
# 开发环境配置（.env.example / .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
|
||||
SECRET_KEY=kaopeilian-secret-key-dev
|
||||
CORS_ORIGINS=["http://localhost:3001","http://localhost:3000"]
|
||||
|
||||
# 生产环境配置（.env.production）
|
||||
DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@mysql:3306/kaopeilian?charset=utf8mb4
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
DEBUG=false
|
||||
SECRET_KEY=kaopeilian-secret-key-2025-production
|
||||
CORS_ORIGINS=["https://aiedu.ireborn.com.cn","http://localhost:3001","http://frontend:80"]
|
||||
```
|
||||
|
||||
#### 3. Docker Compose环境加载
|
||||
```yaml
|
||||
# 生产环境使用专用配置文件
|
||||
backend:
|
||||
env_file:
|
||||
- ./kaopeilian-backend/.env.production
|
||||
environment:
|
||||
- PYTHONPATH=/app
|
||||
|
||||
# 前端构建时注入环境变量
|
||||
frontend:
|
||||
build:
|
||||
args:
|
||||
- NODE_ENV=production
|
||||
- VITE_API_BASE_URL=https://aiedu.ireborn.com.cn
|
||||
- VITE_WS_BASE_URL=wss://aiedu.ireborn.com.cn
|
||||
- VITE_USE_MOCK_DATA=false
|
||||
```
|
||||
|
||||
## 🛡️ 冲突预防和解决
|
||||
|
||||
### 1. 文件级别保护
|
||||
```gitignore
|
||||
# .gitignore 配置
|
||||
.env.local
|
||||
.env.production
|
||||
.env.prod
|
||||
.env.staging
|
||||
|
||||
# 服务器运行时文件（不提交）
|
||||
scripts/force_restart.sh
|
||||
scripts/diagnose.sh
|
||||
fix_frontend.sh
|
||||
setup_production_branch.sh
|
||||
/var/log/kaopeilian_*.log
|
||||
```
|
||||
|
||||
### 2. 服务器修改保护
|
||||
```bash
|
||||
# 自动更新脚本中的保护机制
|
||||
if git status --porcelain | grep -q .; then
|
||||
log "本地有未提交的修改，跳过自动更新"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# 或者强制覆盖本地修改
|
||||
git fetch origin production
|
||||
git reset --hard origin/production
|
||||
```
|
||||
|
||||
### 3. 分支同步策略
|
||||
```bash
|
||||
# 定期同步策略（可选）
|
||||
# 每天自动将main分支的更新合并到production
|
||||
# 0 2 * * * cd /root/aiedu && git checkout production && git merge origin/main && git push origin production
|
||||
```
|
||||
|
||||
## 📋 操作规范和最佳实践
|
||||
|
||||
### 开发者规范
|
||||
|
||||
#### 1. 环境设置规范
|
||||
```bash
|
||||
# ✅ 正确的设置方式
|
||||
cp .env.example .env
|
||||
# 保持.env文件中的远程数据库配置
|
||||
# 不要修改.env.example文件
|
||||
|
||||
# ❌ 错误的做法
|
||||
# 不要直接修改.env.example
|
||||
# 不要提交.env文件到Git
|
||||
# 不要在开发环境连接生产数据库
|
||||
```
|
||||
|
||||
#### 2. 代码提交规范
|
||||
```bash
|
||||
# ✅ 标准提交流程
|
||||
git checkout main
|
||||
git add .
|
||||
git commit -m "feat(user): 添加用户管理功能"
|
||||
git push origin main
|
||||
|
||||
# ❌ 禁止的操作
|
||||
# 不要直接推送到production分支
|
||||
# 不要在production分支进行开发
|
||||
# 不要提交环境配置文件
|
||||
```
|
||||
|
||||
#### 3. 测试验证规范
|
||||
```bash
|
||||
# 本地测试必须通过
|
||||
pytest tests/ # 后端单元测试
|
||||
npm run test # 前端单元测试
|
||||
npm run lint # 代码规范检查
|
||||
|
||||
# 功能测试
|
||||
curl http://localhost:8000/health # 后端健康检查
|
||||
# 浏览器访问 http://localhost:3001 # 前端功能测试
|
||||
```
|
||||
|
||||
### 运维人员规范
|
||||
|
||||
#### 1. 发布操作规范
|
||||
```bash
|
||||
# 标准发布流程
|
||||
cd /root/aiedu
|
||||
git checkout production
|
||||
git pull origin production
|
||||
git merge origin/main
|
||||
git push origin production # 触发自动部署
|
||||
|
||||
# 验证发布结果
|
||||
curl -I https://aiedu.ireborn.com.cn
|
||||
curl https://aiedu.ireborn.com.cn/health
|
||||
```
|
||||
|
||||
#### 2. 紧急修复流程
|
||||
```bash
|
||||
# 生产环境紧急修复
|
||||
git checkout production
|
||||
# ... 直接修复代码 ...
|
||||
git add .
|
||||
git commit -m "hotfix: 修复登录问题"
|
||||
git push origin production # 立即部署
|
||||
|
||||
# 修复后同步回开发分支
|
||||
git checkout main
|
||||
git merge production
|
||||
git push origin main
|
||||
```
|
||||
|
||||
#### 3. 版本回滚操作
|
||||
```bash
|
||||
# 代码回滚
|
||||
git checkout production
|
||||
git log --oneline -10 # 查看最近提交
|
||||
git reset --hard <previous_commit_hash>
|
||||
git push --force origin production
|
||||
|
||||
# 或使用自动备份恢复
|
||||
cd /root/aiedu/backups/updates
|
||||
ls -la backup_*_database.sql
|
||||
# 选择合适的备份进行恢复
|
||||
```
|
||||
|
||||
## 🔍 监控和故障排查
|
||||
|
||||
### 1. 分支状态监控
|
||||
```bash
|
||||
# 检查分支差异
|
||||
cd /root/aiedu
|
||||
git log production..main --oneline # 查看未发布的提交
|
||||
git log main..production --oneline # 查看生产独有的提交
|
||||
|
||||
# 检查当前分支状态
|
||||
git branch -v
|
||||
git status
|
||||
```
|
||||
|
||||
### 2. 自动更新监控
|
||||
```bash
|
||||
# 实时监控日志
|
||||
tail -f /var/log/kaopeilian_webhook.log # Webhook接收日志
|
||||
tail -f /var/log/kaopeilian_update.log # 自动更新日志
|
||||
journalctl -u kaopeilian-webhook.service -f # 系统服务日志
|
||||
|
||||
# 检查服务状态
|
||||
systemctl status kaopeilian-webhook.service
|
||||
curl https://aiedu.ireborn.com.cn/webhook/health
|
||||
```
|
||||
|
||||
### 3. 部署状态检查
|
||||
```bash
|
||||
# 容器健康状态
|
||||
docker compose ps
|
||||
docker stats --no-stream
|
||||
|
||||
# 网站可用性测试
|
||||
curl -I https://aiedu.ireborn.com.cn
|
||||
curl https://aiedu.ireborn.com.cn/health
|
||||
curl https://aiedu.ireborn.com.cn/webhook/health
|
||||
|
||||
# 数据库连接测试
|
||||
docker exec kaopeilian-mysql mysql -u root -p'Kaopeilian2025!@#' -e "SELECT VERSION()"
|
||||
```
|
||||
|
||||
## 🚨 常见问题和解决方案
|
||||
|
||||
### 1. 前端构建失败
|
||||
**问题**：`Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite'`
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 检查package.json和node_modules
|
||||
cd /root/aiedu/kaopeilian-frontend
|
||||
ls -la node_modules/.bin/vite
|
||||
|
||||
# 如果vite不存在，重新安装
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
|
||||
# 或者修改Dockerfile使用npm run build
|
||||
```
|
||||
|
||||
### 2. API地址配置错误
|
||||
**问题**：前端仍显示`localhost:8000`
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 检查Docker构建参数
|
||||
docker compose config | grep -A 10 "build:"
|
||||
|
||||
# 重新构建时确保环境变量正确传递
|
||||
docker compose build --no-cache frontend
|
||||
```
|
||||
|
||||
### 3. 数据库连接冲突
|
||||
**问题**：开发和生产连接同一数据库
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 确认开发环境配置
|
||||
cat kaopeilian-backend/.env | grep DATABASE_URL
|
||||
# 应该指向: 120.79.247.16:3306
|
||||
|
||||
# 确认生产环境配置
|
||||
cat kaopeilian-backend/.env.production | grep DATABASE_URL
|
||||
# 应该指向: mysql:3306
|
||||
```
|
||||
|
||||
### 4. Git提交冲突
|
||||
**问题**：服务器和开发者同时修改代码
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 方案A：使用分支策略（推荐）
|
||||
# 开发者只在main分支工作
|
||||
# 服务器只监听production分支
|
||||
|
||||
# 方案B：服务器配置保护
|
||||
# 在自动更新脚本中检查本地修改
|
||||
if git status --porcelain | grep -q .; then
|
||||
git stash push -m "Auto stash before update"
|
||||
fi
|
||||
```
|
||||
|
||||
## 🔧 自动化工具脚本
|
||||
|
||||
### 1. 快速发布脚本
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /root/aiedu/scripts/quick_deploy.sh
|
||||
|
||||
cd /root/aiedu
|
||||
echo "=== 快速发布到生产环境 ==="
|
||||
|
||||
# 检查当前分支
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
echo "当前分支: $CURRENT_BRANCH"
|
||||
|
||||
# 切换到production分支
|
||||
git checkout production
|
||||
git pull origin production
|
||||
|
||||
# 合并main分支的最新代码
|
||||
echo "合并main分支最新代码..."
|
||||
git fetch origin main
|
||||
git merge origin/main
|
||||
|
||||
# 推送触发自动部署
|
||||
echo "推送到production分支，触发自动部署..."
|
||||
git push origin production
|
||||
|
||||
echo "✅ 发布完成，请等待自动部署完成"
|
||||
echo "监控地址: https://aiedu.ireborn.com.cn"
|
||||
```
|
||||
|
||||
### 2. 分支状态检查脚本
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /root/aiedu/scripts/check_branch_status.sh
|
||||
|
||||
cd /root/aiedu
|
||||
echo "=== Git分支状态检查 ==="
|
||||
|
||||
echo "1. 当前分支信息:"
|
||||
git branch -v
|
||||
|
||||
echo ""
|
||||
echo "2. 远程分支信息:"
|
||||
git branch -r
|
||||
|
||||
echo ""
|
||||
echo "3. main分支未发布的提交:"
|
||||
git log production..origin/main --oneline | head -5
|
||||
|
||||
echo ""
|
||||
echo "4. production分支独有的提交:"
|
||||
git log origin/main..production --oneline | head -5
|
||||
|
||||
echo ""
|
||||
echo "5. 工作区状态:"
|
||||
git status --porcelain
|
||||
|
||||
echo ""
|
||||
echo "6. 最近的提交:"
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
### 3. 环境配置检查脚本
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /root/aiedu/scripts/check_env_config.sh
|
||||
|
||||
echo "=== 环境配置检查 ==="
|
||||
|
||||
echo "1. 开发环境模板:"
|
||||
if [ -f "/root/aiedu/kaopeilian-backend/.env.example" ]; then
|
||||
echo "✅ .env.example 存在"
|
||||
grep "DATABASE_URL" /root/aiedu/kaopeilian-backend/.env.example
|
||||
else
|
||||
echo "❌ .env.example 不存在"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "2. 生产环境配置:"
|
||||
if [ -f "/root/aiedu/kaopeilian-backend/.env.production" ]; then
|
||||
echo "✅ .env.production 存在"
|
||||
grep "DATABASE_URL" /root/aiedu/kaopeilian-backend/.env.production
|
||||
else
|
||||
echo "❌ .env.production 不存在"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "3. Docker Compose配置:"
|
||||
grep -A 5 "env_file:" /root/aiedu/docker-compose.yml
|
||||
|
||||
echo ""
|
||||
echo "4. Git忽略配置:"
|
||||
grep -A 10 ".env" /root/aiedu/.gitignore
|
||||
```
|
||||
|
||||
## 📊 版本管理和发布策略
|
||||
|
||||
### 1. 版本标记策略
|
||||
```bash
|
||||
# 重要版本发布时打标签
|
||||
git tag -a v1.0.0 -m "正式版本发布 - 完整功能"
|
||||
git push origin v1.0.0
|
||||
|
||||
# 查看版本历史
|
||||
git tag -l
|
||||
git show v1.0.0
|
||||
```
|
||||
|
||||
### 2. 发布频率建议
|
||||
- **main分支**：随时提交，频繁更新
|
||||
- **production分支**：每周发布，稳定版本
|
||||
- **hotfix**：紧急修复，立即发布
|
||||
|
||||
### 3. 代码审查流程
|
||||
```bash
|
||||
# 重要功能使用Pull Request
|
||||
git checkout -b feature/important-feature
|
||||
# ... 开发完成 ...
|
||||
git push origin feature/important-feature
|
||||
# 在GitHub创建PR: feature/important-feature → main
|
||||
```
|
||||
|
||||
## 🎯 成功指标和监控
|
||||
|
||||
### 1. 部署成功率指标
|
||||
- **自动部署成功率**: > 95%
|
||||
- **平均部署时间**: < 5分钟
|
||||
- **回滚时间**: < 2分钟
|
||||
- **服务可用性**: > 99.9%
|
||||
|
||||
### 2. 开发效率指标
|
||||
- **环境搭建时间**: < 10分钟
|
||||
- **代码提交到部署**: < 5分钟
|
||||
- **问题修复时间**: < 30分钟
|
||||
|
||||
### 3. 监控告警配置
|
||||
```bash
|
||||
# 服务健康监控
|
||||
curl -f https://aiedu.ireborn.com.cn/health || echo "服务异常"
|
||||
|
||||
# 自动更新监控
|
||||
if [ ! -f "/var/log/kaopeilian_update.log" ]; then
|
||||
echo "更新日志丢失"
|
||||
fi
|
||||
|
||||
# 分支同步检查
|
||||
COMMITS_BEHIND=$(git rev-list --count production..origin/main)
|
||||
if [ $COMMITS_BEHIND -gt 10 ]; then
|
||||
echo "production分支落后main分支 $COMMITS_BEHIND 个提交"
|
||||
fi
|
||||
```
|
||||
|
||||
## 📚 相关文档链接
|
||||
|
||||
- [本地开发指南](./本地开发.md) - 开发者环境配置
|
||||
- [服务器部署经验](./服务器部署经验.md) - 生产环境部署
|
||||
- [联调经验汇总](../全链路联调/联调经验汇总.md) - 前后端联调
|
||||
- [数据库架构](../../kaopeilian-backend/数据库架构-统一版.md) - 数据库设计
|
||||
|
||||
## 🎉 策略优势总结
|
||||
|
||||
通过双分支策略，我们实现了：
|
||||
|
||||
- ✅ **开发环境完全隔离**：开发者连接远程数据库，不影响生产
|
||||
- ✅ **生产环境独立稳定**：使用本地数据库容器，配置独立
|
||||
- ✅ **自动化部署流程**：推送production分支自动触发部署
|
||||
- ✅ **配置冲突完全避免**：不同环境使用不同配置文件
|
||||
- ✅ **版本控制清晰**：main开发，production生产，历史清晰
|
||||
- ✅ **回滚机制完善**：自动备份，快速回滚
|
||||
- ✅ **团队协作友好**：开发者无需关心生产配置
|
||||
|
||||
这个分支管理策略是经过实践验证的企业级解决方案，确保了开发效率和生产稳定性的最佳平衡。
|
||||
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