# 考培练系统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生产，历史清晰
- ✅ **回滚机制完善**：自动备份，快速回滚
- ✅ **团队协作友好**：开发者无需关心生产配置

这个分支管理策略是经过实践验证的企业级解决方案，确保了开发效率和生产稳定性的最佳平衡。