MBE 分布式开发管理实施指南
版本: v1.0 | 更新时间: 2026-02-02
目录
- 架构概览
- 环境配置
- Git 分支策略
- 开发工作流
- 代码审查流程
- CI/CD 自动化
- 团队协作规范
- 发布流程
- 快速参考
1. 架构概览
1.1 三环境隔离架构
┌─────────────────────────────────────────────────────────────────────────────┐
│ MBE 分布式开发架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ 生产环境 (Prod) │ ← 正式用户访问 │
│ │ mbe.hi-maker.com │ │
│ │ main 分支 │ │
│ │ API: 8000 │ │
│ └──────────┬──────────┘ │
│ │ hotfix only │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ 测试环境 (Test) │ ← 发布前验证（可选） │
│ │ test.hi-maker.com │ │
│ │ release/* 分支 │ │
│ │ API: 8002 │ │
│ └──────────┬──────────┘ │
│ │ release merge │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ 开发环境 (Dev) │ ← 团队协作开发 │
│ │ dev.hi-maker.com │ │
│ │ develop 分支 │ │
│ │ API: 8001 │ │
│ └──────────┬──────────┘ │
│ │ feature merge │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ 本地环境 (Local) │ ← 个人开发调试 │
│ │ localhost │ │
│ │ feature/* 分支 │ │
│ │ 直接运行 Python │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
1.2 端口分配
| 环境 |
API |
Admin |
Education |
AIGC |
Lawyer |
PostgreSQL |
Redis |
| 生产 |
8000 |
3000 |
3001 |
3002 |
3004 |
5432 |
6379 |
| 开发 |
8001 |
3010 |
3011 |
3012 |
3014 |
5433 |
6380 |
| 测试 |
8002 |
3020 |
3021 |
3022 |
3024 |
5434 |
6381 |
2. 环境配置
2.1 初始化 Git 仓库（首次设置）
# 1. 初始化 Git 仓库
cd D:\Mises\mises-behavior-engine
git init
# 2. 添加远程仓库
git remote add origin https://github.com/your-org/mises-behavior-engine.git
# 或使用私有 Gitea
git remote add origin http://localhost:3030/mbe/mises-behavior-engine.git
# 3. 创建主分支
git checkout -b main
git add .
git commit -m "Initial commit: MBE v2.0.0"
git push -u origin main
# 4. 创建开发分支
git checkout -b develop
git push -u origin develop
2.2 配置环境文件
# 确保有三套环境配置
.env.production # 生产环境
.env.development # 开发环境
.env.test # 测试环境（可选）
2.3 启动双环境
cd D:\Mises\mises-behavior-engine
# 同时启动生产和开发环境
.\scripts\deploy_dual_environment.ps1
# 或分别启动
.\scripts\deploy_dual_environment.ps1 -ProductionOnly
.\scripts\deploy_dual_environment.ps1 -DevelopmentOnly
3. Git 分支策略
3.1 分支模型 (Git Flow)
┌─────────────────────────────────────────────────────────────────────────────┐
│ Git Flow 分支模型 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ main ──────●─────────●─────────────────●─────────────●────────▶ │
│ │ │ │ │ │
│ │ │ v2.0.0 │ v2.1.0 │ v2.1.1 (hotfix) │
│ │ │ │ │ │
│ release ───┼─────────┼────────●───●────┼─────────────┼────────▶ │
│ │ │ │ │ │ │ │
│ │ │ release/v2.1 │ │ │
│ │ │ │ │ │ │ │
│ develop ───●─────●───●────●───●───●────●─────●───●───●────────▶ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ feature ───●─────● ●───────● ●───● │
│ feat/a feat/b feat/c feat/d feat/e feat/f │
│ │
│ hotfix ─────────────────────────────────────────────●───────▶ │
│ hotfix/v2.1.1 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3.2 分支命名规范
| 分支类型 |
命名格式 |
示例 |
说明 |
| 主分支 |
main |
main |
生产代码 |
| 开发分支 |
develop |
develop |
集成分支 |
| 功能分支 |
feature/功能名 |
feature/expert-marketplace |
新功能开发 |
| 修复分支 |
fix/问题描述 |
fix/login-error |
Bug 修复 |
| 发布分支 |
release/版本号 |
release/v2.1.0 |
发布准备 |
| 热修复 |
hotfix/版本号 |
hotfix/v2.0.1 |
紧急修复 |
3.3 Commit 规范 (Conventional Commits)
<type>(<scope>): <subject>
<body>
<footer>
Type 类型:
| Type |
说明 |
示例 |
| feat |
新功能 |
feat(expert): Add marketplace search |
| fix |
Bug 修复 |
fix(auth): Fix login validation |
| docs |
文档更新 |
docs: Update API documentation |
| style |
代码格式 |
style: Format with Black |
| refactor |
重构 |
refactor(db): Optimize query |
| test |
测试 |
test: Add expert unit tests |
| chore |
构建/工具 |
chore: Update dependencies |
| perf |
性能优化 |
perf(search): Improve speed |
4. 开发工作流
4.1 日常开发流程
# ============ 开发者 A 的工作流程 ============
# 1. 每天开始：同步最新代码
git checkout develop
git pull origin develop
# 2. 创建功能分支
git checkout -b feature/expert-search
# 3. 开发编码
# ... 编写代码 ...
# 4. 本地测试
pytest tests/ -v
python -m pytest tests/unit/ -v
# 5. 提交代码（小步提交）
git add .
git commit -m "feat(expert): Add search by category"
# 6. 继续开发和提交
# ... 更多代码 ...
git commit -m "feat(expert): Add search filters"
# 7. 推送到远程
git push -u origin feature/expert-search
# 8. 创建 Pull Request (PR)
# 在 GitHub/GitLab 上创建 PR: feature/expert-search → develop
# 9. 代码审查通过后合并
# 审查者点击 "Merge"
# 10. 清理本地分支
git checkout develop
git pull origin develop
git branch -d feature/expert-search
4.2 多人协作流程图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 多人协作开发流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 开发者 A develop 分支 开发者 B │
│ ════════ ════════════ ════════ │
│ │
│ │ │ │ │
│ │ pull │ pull │ │
│ ◀──────────────────────────│──────────────────────────────▶ │
│ │ │ │ │
│ │ │ │ │
│ feature/a │ feature/b │
│ │ │ │ │
│ │ commit │ commit │ │
│ │ commit │ commit │ │
│ │ commit │ commit │ │
│ │ │ │ │
│ │ push │ push │ │
│ │──────────────────────────│───────────────────────────▶ │ │
│ │ │ │ │
│ │ create PR │ create PR │ │
│ │──────────────────────────▶ │ │
│ │ ◀──────────────────────────────│ │
│ │ │ │ │
│ │ code review │ code review │ │
│ │ │ │ │
│ │ merge │ merge │ │
│ │ ●─────│─────● │ │
│ │ │ │ │
│ │ pull │ pull │ │
│ ◀──────────────────────────│──────────────────────────────▶ │
│ │ │ │ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
4.3 冲突解决
# 当合并出现冲突时
# 1. 更新本地 develop
git checkout develop
git pull origin develop
# 2. 回到功能分支并合并 develop
git checkout feature/my-feature
git merge develop
# 3. 解决冲突
# 编辑冲突文件，选择正确的代码
# 4. 标记冲突已解决
git add <conflicted-files>
git commit -m "resolve: Merge conflicts with develop"
# 5. 推送解决后的代码
git push origin feature/my-feature
5. 代码审查流程
5.1 审查流程
┌─────────────────────────────────────────────────────────────────────────────┐
│ 代码审查流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 开发者创建 PR │
│ ├── 填写 PR 描述（改动说明、测试方法） │
│ ├── 关联 Issue（如有） │
│ └── 指定审查者 │
│ │ │
│ ▼ │
│ 2. 自动检查 (CI) │
│ ├── 代码格式 (Black, isort) │
│ ├── 代码规范 (flake8) │
│ ├── 类型检查 (mypy) │
│ ├── 单元测试 (pytest) │
│ └── 覆盖率检查 (>70%) │
│ │ │
│ ▼ │
│ 3. 人工审查 │
│ ├── 功能正确性 │
│ ├── 代码质量 │
│ ├── 性能考虑 │
│ ├── 安全性 │
│ └── 可维护性 │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ │
│ [需要修改] [批准通过] │
│ │ │ │
│ │ ▼ │
│ 修改后重新 4. 合并到 develop │
│ 提交审查 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
5.2 审查要求
| 变更类型 |
最少审查人数 |
审查者要求 |
| 普通功能 |
1 人 |
团队成员 |
| 核心功能 |
2 人 |
含 Tech Lead |
| 安全相关 |
2 人 |
含安全负责人 |
| 架构变更 |
全员 |
团队讨论 |
5.3 PR 模板
## 变更说明
<!-- 简要描述这个 PR 做了什么 -->
## 变更类型
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 重构 (refactor)
- [ ] 测试 (test)
## 测试方法
<!-- 描述如何测试这些变更 -->
## 相关 Issue
<!-- 关联的 Issue 编号，如 #123 -->
## 检查清单
- [ ] 代码已自测
- [ ] 添加了必要的测试
- [ ] 更新了相关文档
- [ ] CI 检查通过
6. CI/CD 自动化
6.1 GitHub Actions 配置
位置: .github/workflows/test.yml
name: MBE CI/CD
on:
push:
branches: [main, develop, 'feature/*']
pull_request:
branches: [main, develop]
jobs:
# 代码检查
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: pip install black isort flake8 mypy
- name: Check formatting
run: |
black --check src/
isort --check-only src/
flake8 src/
# 单元测试
test:
runs-on: ubuntu-latest
services:
postgres:
image: pgvector/pgvector:pg16
env:
POSTGRES_PASSWORD: test
ports:
- 5432:5432
redis:
image: redis:alpine
ports:
- 6379:6379
steps:
- uses: actions/checkout@v4
- name: Run tests
run: |
pip install -r requirements.txt
pytest tests/ -v --cov=src --cov-report=xml
- name: Upload coverage
uses: codecov/codecov-action@v3
# 部署到开发环境（仅 develop 分支）
deploy-dev:
needs: [lint, test]
if: github.ref == 'refs/heads/develop'
runs-on: ubuntu-latest
steps:
- name: Deploy to development
run: |
# SSH 到服务器执行部署
ssh user@dev-server 'cd /app && ./scripts/deploy_dev.sh'
# 部署到生产环境（仅 main 分支）
deploy-prod:
needs: [lint, test]
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: |
ssh user@prod-server 'cd /app && ./scripts/deploy_prod.sh'
6.2 本地 CI 检查
# 提交前本地检查
cd D:\Mises\mises-behavior-engine
# 1. 代码格式化
black src/
isort src/
# 2. 代码规范检查
flake8 src/
# 3. 运行测试
pytest tests/unit/ -v
# 4. 覆盖率检查
pytest tests/ --cov=src --cov-report=html
7. 团队协作规范
7.1 角色分工
┌─────────────────────────────────────────────────────────────────────────────┐
│ 团队角色分工 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tech Lead (1人) │
│ ├── 技术决策 │
│ ├── 架构设计 │
│ ├── 代码审查（最终） │
│ └── 发布管理 │
│ │
│ 后端开发 (2-3人) │
│ ├── 开发者 A: 核心 API + 专家市场 │
│ ├── 开发者 B: 应用市场 + 用户系统 │
│ └── 开发者 C: 知识库 + AI 模型 │
│ │
│ 前端开发 (1-2人) │
│ ├── 开发者 D: Admin UI + 商城界面 │
│ └── 开发者 E: Education 等应用前端 │
│ │
│ 测试/运维 (1人) │
│ ├── 自动化测试 │
│ ├── CI/CD 维护 │
│ └── 部署运维 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
7.2 Sprint 节奏（2 周）
| 时间 |
活动 |
参与者 |
时长 |
| 周一 10:00 |
Sprint 规划 |
全员 |
2h |
| 每日 10:00 |
站会 |
全员 |
15min |
| 周三 14:00 |
技术分享（可选） |
全员 |
1h |
| 周五 15:00 |
Sprint 回顾 |
全员 |
1.5h |
7.3 沟通规范
即时沟通: 企业微信/Slack/钉钉
├── #general - 一般讨论
├── #dev - 开发相关
├── #alerts - 系统告警
└── #random - 闲聊
文档协作: Notion/飞书/语雀
├── 产品需求文档
├── 技术设计文档
├── 会议纪要
└── 知识库
代码协作: GitHub/GitLab/Gitea
├── 代码仓库
├── Issue 跟踪
├── PR 审查
└── CI/CD
8. 发布流程
8.1 发布流程图
┌─────────────────────────────────────────────────────────────────────────────┐
│ 版本发布流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: 创建发布分支 │
│ ════════════════════ │
│ git checkout develop │
│ git checkout -b release/v2.1.0 │
│ │
│ Step 2: 发布准备 │
│ ════════════════ │
│ - 更新版本号 │
│ - 更新 CHANGELOG.md │
│ - 完善文档 │
│ - 只允许 bugfix │
│ │
│ Step 3: 测试验证 │
│ ════════════════ │
│ - 部署到测试环境 │
│ - 执行测试用例 │
│ - 修复发现的问题 │
│ │
│ Step 4: 合并发布 │
│ ════════════════ │
│ git checkout main │
│ git merge release/v2.1.0 │
│ git tag -a v2.1.0 -m "Release v2.1.0" │
│ git push origin main --tags │
│ │
│ Step 5: 同步 develop │
│ ═══════════════════ │
│ git checkout develop │
│ git merge release/v2.1.0 │
│ git push origin develop │
│ │
│ Step 6: 部署生产 │
│ ════════════════ │
│ .\scripts\deploy_complete_production.ps1 │
│ │
│ Step 7: 清理分支 │
│ ════════════════ │
│ git branch -d release/v2.1.0 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
8.2 版本号规范 (语义化版本)
v主版本.次版本.修订版本
示例:
- v2.0.0 - 主版本（重大更新、不兼容变更）
- v2.1.0 - 次版本（新功能、向下兼容）
- v2.1.1 - 修订版（Bug 修复）
- v2.1.0-dev.1 - 开发版
- v2.1.0-rc.1 - 候选版
8.3 Hotfix 流程
# 紧急修复生产问题
# 1. 从 main 创建 hotfix 分支
git checkout main
git checkout -b hotfix/v2.0.1
# 2. 修复问题
# ... 修复代码 ...
git commit -m "fix: Critical security vulnerability"
# 3. 合并到 main
git checkout main
git merge hotfix/v2.0.1
git tag -a v2.0.1 -m "Hotfix v2.0.1"
git push origin main --tags
# 4. 同步到 develop
git checkout develop
git merge hotfix/v2.0.1
git push origin develop
# 5. 部署生产
.\scripts\deploy_complete_production.ps1
# 6. 清理分支
git branch -d hotfix/v2.0.1
9. 快速参考
9.1 常用命令速查
# ===== Git 基础 =====
git status # 查看状态
git log --oneline -10 # 查看最近10条提交
git diff # 查看改动
git stash # 暂存改动
git stash pop # 恢复暂存
# ===== 分支操作 =====
git branch -a # 查看所有分支
git checkout -b feature/xxx # 创建并切换分支
git branch -d feature/xxx # 删除分支
git push origin --delete feature/xxx # 删除远程分支
# ===== 同步操作 =====
git fetch origin # 获取远程更新
git pull origin develop # 拉取并合并
git push origin feature/xxx # 推送分支
# ===== 合并操作 =====
git merge develop # 合并 develop 到当前分支
git rebase develop # 变基到 develop
git cherry-pick <commit> # 挑选提交
# ===== 标签操作 =====
git tag # 列出标签
git tag -a v2.1.0 -m "Release" # 创建标签
git push origin --tags # 推送标签
9.2 部署命令速查
# ===== 双环境部署 =====
.\scripts\deploy_dual_environment.ps1 # 同时部署
.\scripts\deploy_dual_environment.ps1 -ProductionOnly # 仅生产
.\scripts\deploy_dual_environment.ps1 -DevelopmentOnly # 仅开发
# ===== 查看状态 =====
docker ps # 查看容器
docker logs -f mbe-api # 查看日志
docker stats # 查看资源
# ===== 停止服务 =====
docker compose -f docker-compose.complete.yml --env-file .env.production --profile production down
docker compose -f docker-compose.dev.complete.yml --env-file .env.development down
9.3 测试命令速查
# ===== 本地测试 =====
pytest tests/unit/ -v # 单元测试
pytest tests/integration/ -v # 集成测试
pytest tests/ --cov=src # 覆盖率测试
# ===== 代码检查 =====
black src/ # 格式化
isort src/ # 排序导入
flake8 src/ # 规范检查
相关文档