Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

15 KiB

Raw Permalink Blame History

考培练系统Git分支管理策略

🎯 策略概述

为了解决开发环境和生产环境配置冲突问题，以及避免服务器自动更新与开发者提交产生冲突，我们采用双分支策略：

main分支：开发者日常开发和协作
production分支：生产环境部署和自动更新

🌿 分支结构

GitHub Repository: nongjun/ai-development-workspace
├── main (开发分支)
│   ├── 开发者日常提交
│   ├── 功能开发和Bug修复
│   ├── 代码审查和测试
│   └── 连接远程数据库配置
│
└── production (生产分支)
    ├── 稳定版本发布
    ├── 生产环境部署配置
    ├── 自动更新目标分支
    └── 连接本地MySQL容器

🔄 完整工作流程

开发者工作流程

1. 初始环境设置

# 克隆项目
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. 日常开发流程

# 确保在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. 标准发布流程

# 方式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. 自动部署流程（服务器端）

GitHub接收推送 → production分支
发送Webhook通知 → https://aiedu.ireborn.com.cn/webhook

服务器自动执行：

# /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. 分支过滤配置

# /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. 后端配置文件

kaopeilian-backend/
├── .env.example        # 开发环境模板（提交到Git）
├── .env.production     # 生产环境配置（不提交到Git）  
├── .env               # 开发者本地配置（不提交到Git）
└── app/

2. 配置内容对比

# 开发环境配置（.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环境加载

# 生产环境使用专用配置文件
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 配置
.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. 服务器修改保护

# 自动更新脚本中的保护机制
if git status --porcelain | grep -q .; then
    log "本地有未提交的修改，跳过自动更新"
    exit 0
fi

# 或者强制覆盖本地修改
git fetch origin production
git reset --hard origin/production

3. 分支同步策略

# 定期同步策略（可选）
# 每天自动将main分支的更新合并到production
# 0 2 * * * cd /root/aiedu && git checkout production && git merge origin/main && git push origin production

📋 操作规范和最佳实践

开发者规范

1. 环境设置规范

# ✅ 正确的设置方式
cp .env.example .env
# 保持.env文件中的远程数据库配置
# 不要修改.env.example文件

# ❌ 错误的做法
# 不要直接修改.env.example
# 不要提交.env文件到Git
# 不要在开发环境连接生产数据库

2. 代码提交规范

# ✅ 标准提交流程
git checkout main
git add .
git commit -m "feat(user): 添加用户管理功能"
git push origin main

# ❌ 禁止的操作
# 不要直接推送到production分支
# 不要在production分支进行开发
# 不要提交环境配置文件

3. 测试验证规范

# 本地测试必须通过
pytest tests/                    # 后端单元测试
npm run test                    # 前端单元测试
npm run lint                    # 代码规范检查

# 功能测试
curl http://localhost:8000/health    # 后端健康检查
# 浏览器访问 http://localhost:3001   # 前端功能测试

运维人员规范

1. 发布操作规范

# 标准发布流程
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. 紧急修复流程

# 生产环境紧急修复
git checkout production
# ... 直接修复代码 ...
git add .
git commit -m "hotfix: 修复登录问题"
git push origin production  # 立即部署

# 修复后同步回开发分支
git checkout main
git merge production
git push origin main

3. 版本回滚操作

# 代码回滚
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. 分支状态监控

# 检查分支差异
cd /root/aiedu
git log production..main --oneline  # 查看未发布的提交
git log main..production --oneline  # 查看生产独有的提交

# 检查当前分支状态
git branch -v
git status

2. 自动更新监控

# 实时监控日志
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. 部署状态检查

# 容器健康状态
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'

解决方案：

# 检查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

解决方案：

# 检查Docker构建参数
docker compose config | grep -A 10 "build:"

# 重新构建时确保环境变量正确传递
docker compose build --no-cache frontend

3. 数据库连接冲突

问题：开发和生产连接同一数据库

解决方案：

# 确认开发环境配置
cat kaopeilian-backend/.env | grep DATABASE_URL
# 应该指向: 120.79.247.16:3306

# 确认生产环境配置  
cat kaopeilian-backend/.env.production | grep DATABASE_URL
# 应该指向: mysql:3306

4. Git提交冲突

问题：服务器和开发者同时修改代码

解决方案：

# 方案A：使用分支策略（推荐）
# 开发者只在main分支工作
# 服务器只监听production分支

# 方案B：服务器配置保护
# 在自动更新脚本中检查本地修改
if git status --porcelain | grep -q .; then
    git stash push -m "Auto stash before update"
fi

🔧 自动化工具脚本

1. 快速发布脚本

#!/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. 分支状态检查脚本

#!/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. 环境配置检查脚本

#!/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. 版本标记策略

# 重要版本发布时打标签
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. 代码审查流程

# 重要功能使用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. 监控告警配置

# 服务健康监控
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

📚 相关文档链接

本地开发指南 - 开发者环境配置
服务器部署经验 - 生产环境部署
联调经验汇总 - 前后端联调
数据库架构 - 数据库设计

🎉 策略优势总结

通过双分支策略，我们实现了：

✅ 开发环境完全隔离：开发者连接远程数据库，不影响生产
✅ 生产环境独立稳定：使用本地数据库容器，配置独立
✅ 自动化部署流程：推送production分支自动触发部署
✅ 配置冲突完全避免：不同环境使用不同配置文件
✅ 版本控制清晰：main开发，production生产，历史清晰
✅ 回滚机制完善：自动备份，快速回滚
✅ 团队协作友好：开发者无需关心生产配置

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

15 KiB Raw Permalink Blame History Unescape Escape

考培练系统Git分支管理策略

🎯 策略概述

🌿 分支结构

🔄 完整工作流程

开发者工作流程

1. 初始环境设置

2. 日常开发流程

3. 开发环境特点

生产发布流程

1. 标准发布流程

2. 自动部署流程（服务器端）

3. 生产环境特点

⚙️ 技术配置详解

GitHub Webhook配置

1. 仓库Webhook设置

2. 分支过滤配置

环境配置分离

1. 后端配置文件

2. 配置内容对比

3. Docker Compose环境加载

🛡️ 冲突预防和解决

1. 文件级别保护

2. 服务器修改保护

3. 分支同步策略

📋 操作规范和最佳实践

开发者规范

1. 环境设置规范

2. 代码提交规范

3. 测试验证规范

运维人员规范

1. 发布操作规范

2. 紧急修复流程

3. 版本回滚操作

🔍 监控和故障排查

1. 分支状态监控

2. 自动更新监控

3. 部署状态检查

🚨 常见问题和解决方案

1. 前端构建失败

2. API地址配置错误

3. 数据库连接冲突

4. Git提交冲突

🔧 自动化工具脚本

1. 快速发布脚本

2. 分支状态检查脚本

3. 环境配置检查脚本

📊 版本管理和发布策略

1. 版本标记策略

2. 发布频率建议

3. 代码审查流程

🎯 成功指标和监控

1. 部署成功率指标

2. 开发效率指标

3. 监控告警配置

📚 相关文档链接

🎉 策略优势总结

15 KiB

Raw Permalink Blame History