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生产，历史清晰
|
||||
- ✅ **回滚机制完善**：自动备份，快速回滚
|
||||
- ✅ **团队协作友好**：开发者无需关心生产配置
|
||||
|
||||
这个分支管理策略是经过实践验证的企业级解决方案，确保了开发效率和生产稳定性的最佳平衡。
|
||||
Reference in New Issue
Block a user