🚀 MBE 部署管理系统

📋 概述

本系统提供标准化的 Local → Dev → Prod 三环境部署流程，支持命令行和Web界面两种管理方式。

🏗️ 架构设计

环境划分

标准部署流程

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Local     │         │     Dev     │         │    Prod     │
│  本地开发    │  推广→  │  开发测试    │  推广→  │  生产环境    │
│             │         │             │         │             │
│ 代码修改     │         │ 功能验证     │         │ 正式发布     │
│ 单元测试     │         │ 集成测试     │         │ 监控告警     │
│ 本地调试     │         │ 团队协作     │         │ 性能优化     │
└─────────────┘         └─────────────┘         └─────────────┘

🛠️ 使用方法

方式一：命令行工具

1. 查看所有环境状态

python scripts/deploy_manager.py status

输出示例： ```

📊 MBE 环境状态

【本地开发环境】 域名: localhost:8000 镜像: mbe-api:local ✅ 镜像存在 (创建于: 2026-02-03 10:30:15) 🟢 容器运行中: Up 2 hours (healthy)

【开发测试环境】 域名: mbe-dev.hi-maker.com 镜像: mbe-api:dev ❌ 镜像不存在 🔴 容器未运行

#### 2. 本地开发：修改代码后重新部署

```bash
# 重新构建并部署
python scripts/deploy_manager.py deploy local --rebuild

# 或快速部署（不重新构建，适用于配置修改）
python scripts/deploy_manager.py deploy local

3. 推广到开发环境测试

# 将本地环境推广到开发环境
python scripts/deploy_manager.py promote local dev

系统会：

1. 自动将 mbe-api:local 镜像标记为 mbe-api:dev
2. 使用 docker-compose.dev.yml 部署到开发环境
3. 记录部署历史

4. 测试通过后推广到生产

# 将开发环境推广到生产环境（需要确认）
python scripts/deploy_manager.py promote dev prod

5. 查看部署历史

# 查看最近10次部署
python scripts/deploy_manager.py history

# 查看最近20次
python scripts/deploy_manager.py history --limit 20

方式二：Web 管理界面

启动 Web 界面

python src/deploy/deploy_web.py

访问：http://localhost:9000

界面功能

• 环境状态卡片：实时显示各环境状态（镜像、容器、最后部署时间）
• 一键部署按钮：快速部署或重新构建部署
• 环境推广流程：可视化的推广操作
• 部署历史日志：查看所有部署记录和Git信息

📝 典型工作流程

场景1：发现Bug并修复

# 1. 在本地修改代码
vim src/knowledge/expert_router.py

# 2. 本地测试
python scripts/deploy_manager.py deploy local --rebuild

# 3. 本地测试通过后，推广到开发环境
python scripts/deploy_manager.py promote local dev

# 4. 在开发环境测试（https://mbe-dev.hi-maker.com）
curl https://mbe-dev.hi-maker.com/api/health

# 5. 测试通过后，推广到生产
python scripts/deploy_manager.py promote dev prod

场景2：仅配置修改（无需重新构建）

# 1. 修改环境变量或配置文件
vim .env

# 2. 快速重启服务（不重新构建镜像）
python scripts/deploy_manager.py deploy local

# 3. 测试OK后推广
python scripts/deploy_manager.py promote local dev
python scripts/deploy_manager.py promote dev prod

场景3：紧急回滚

# 查看历史，找到上一个稳定版本的commit
python scripts/deploy_manager.py history

# 回退代码到稳定版本
git checkout <stable_commit>

# 重新构建并部署
python scripts/deploy_manager.py deploy prod --rebuild

🔧 配置说明

Docker Compose 文件

系统会根据环境自动选择对应的配置文件：

• docker-compose.yml → Local 环境
• docker-compose.dev.yml → Dev 环境
• docker-compose.prod.yml → Prod 环境

环境变量

在 .env 文件中配置环境特定的变量：

# 通用配置
LLM_PROVIDER=deepseek
LLM_API_KEY=sk-xxx

# 开发环境
DEV_DATABASE_URL=postgresql://...
DEV_REDIS_URL=redis://...

# 生产环境
PROD_DATABASE_URL=postgresql://...
PROD_REDIS_URL=redis://...

📊 部署日志

所有部署操作都会记录到 logs/deploy_history.json：

[
  {
    "timestamp": "2026-02-03T10:30:15",
    "environment": "prod",
    "action": "promote",
    "from": "dev",
    "git": {
      "branch": "main",
      "commit": "a7b3c2d",
      "timestamp": "2026-02-03T10:30:15"
    }
  }
]

🚨 注意事项

生产环境操作规范

1. 必须经过Dev环境测试：禁止直接从Local推广到Prod
2. 需要二次确认：推广到Prod时会要求输入 yes 确认
3. 做好备份：部署前确保数据库已备份
4. 错峰部署：避免在业务高峰期部署

数据库迁移

如果涉及数据库schema变更：

# 在部署前先运行迁移
alembic upgrade head

# 然后再部署应用
python scripts/deploy_manager.py deploy prod --rebuild

回滚策略

保留最近3个版本的镜像：

# 查看镜像历史
docker images mbe-api

# 回滚到上一个版本
docker tag mbe-api:prod-backup-20260203 mbe-api:prod
docker-compose -f docker-compose.prod.yml up -d

📞 故障排查

部署失败

# 查看容器日志
docker logs mbe-api --tail 100

# 检查容器状态
docker ps -a | grep mbe

# 查看镜像构建日志
docker build -t mbe-api:test . 2>&1 | tee build.log

环境不一致

# 强制重新构建所有环境
python scripts/deploy_manager.py build local
python scripts/deploy_manager.py build dev
python scripts/deploy_manager.py build prod

网络问题

# 检查tunnel状态
docker logs mbe-tunnel --tail 20
docker logs mbe-tunnel-dev --tail 20

# 重启tunnel
docker restart mbe-tunnel
docker restart mbe-tunnel-dev

🔐 权限管理

建议为不同环境配置不同的访问权限：

• Local: 开发者全权限
• Dev: 开发团队可部署
• Prod: 仅运维团队可部署

可以通过 CI/CD 系统（如 GitLab CI、GitHub Actions）集成权限控制。

🎯 未来扩展

• 集成 GitLab/GitHub CI/CD
• 自动化测试集成
• 蓝绿部署支持
• 金丝雀发布
• 自动回滚机制
• 性能监控集成
• 告警通知（钉钉/邮件/Slack）