MBE 文档中心

MBE 部署管理工具使用指南

📋 概述

MBE 提供了两个部署管理工具，用于管理本地、开发版和生产版三个环境：

  1. 命令行工具 (scripts/deploy_manager.py) - 适合脚本化和自动化
  2. Web 管理界面 (start_deploy_manager.py) - 可视化操作，更直观

🖥️ Web 管理界面（推荐）

启动方式

# 方式1：直接运行启动脚本
python start_deploy_manager.py

# 方式2：使用 uvicorn 启动
uvicorn src.deploy.smart_deploy_web:app --host 0.0.0.0 --port 9001

访问地址

本地访问: http://localhost:9001

功能特性

✅ 实时监控所有环境状态

  • 显示本地、开发版、生产版的状态
  • 显示容器运行状态
  • 显示镜像信息
  • 显示公网访问地址和状态

✅ 一键智能部署

  • 快速部署到指定环境
  • 支持重新构建镜像
  • 自动检测代码变更

✅ 环境推广自动化

  • Local → Dev → Prod 的标准化流程
  • 可视化推广操作
  • 自动记录部署历史

✅ 公网访问状态

  • 显示 Cloudflare Tunnel 状态
  • 显示公网访问地址
  • 测试公网连接

界面功能

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

💻 命令行工具

基本用法

# 查看所有环境状态
python scripts/deploy_manager.py status

# 构建镜像
python scripts/deploy_manager.py build local
python scripts/deploy_manager.py build dev
python scripts/deploy_manager.py build prod

# 部署到指定环境
python scripts/deploy_manager.py deploy local --rebuild
python scripts/deploy_manager.py deploy dev
python scripts/deploy_manager.py deploy prod

# 环境推广
python scripts/deploy_manager.py promote local dev
python scripts/deploy_manager.py promote dev prod

# 查看部署历史
python scripts/deploy_manager.py history
python scripts/deploy_manager.py history --limit 20

命令说明

1. status - 查看所有环境状态

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 ✅ 镜像存在 🟢 容器运行中: Up 1 day (healthy)

【生产环境】 域名: mbe.hi-maker.com 镜像: mbe-api:prod ✅ 镜像存在 🟢 容器运行中: Up 3 days (healthy)


#### 2. deploy - 部署到指定环境

```bash
# 重新构建并部署（适用于代码修改）
python scripts/deploy_manager.py deploy local --rebuild

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

3. promote - 环境推广

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

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

系统会：

  1. 自动将源环境的镜像标记为目标环境的镜像
  2. 使用对应的 docker-compose 文件部署
  3. 记录部署历史

4. history - 查看部署历史

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

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

🌍 环境配置

环境定义

环境 域名 镜像标签 Docker Compose 用途
Local localhost:8000 mbe-api:local docker-compose.yml 本地开发调试
Dev mbe-dev.hi-maker.com mbe-api:dev docker-compose.dev.yml 团队测试验证
Prod mbe.hi-maker.com mbe-api:prod docker-compose.prod.yml 生产对外服务

标准部署流程

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

📝 典型工作流程

场景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 docker-compose.dev.yml

# 2. 快速部署（不重新构建）
python scripts/deploy_manager.py deploy dev

场景3：使用 Web 界面

# 1. 启动 Web 管理界面
python start_deploy_manager.py

# 2. 浏览器访问 http://localhost:9001

# 3. 在界面上：
#    - 查看所有环境状态
#    - 点击"部署"按钮进行部署
#    - 使用"推广"功能进行环境推广
#    - 查看部署历史

🔍 相关文件

管理工具文件

  • start_deploy_manager.py - Web 管理界面启动脚本
  • src/deploy/smart_deploy_web.py - Web 管理界面主程序
  • scripts/deploy_manager.py - 命令行部署管理器

配置文件

  • docker-compose.yml - 本地环境配置
  • docker-compose.dev.yml - 开发环境配置
  • docker-compose.prod.yml - 生产环境配置

文档

  • docs/guides/DEPLOYMENT_GUIDE.md - 详细部署指南
  • docs/deployment/START_DEV_AND_PROD.md - 启动开发版和生产版指南

⚠️ 注意事项

  1. 生产环境操作需谨慎

    • 推广到生产环境前需要确认
    • 建议先在开发环境充分测试

  2. 镜像构建时间

    • 重新构建镜像需要较长时间（5-10分钟）
    • 仅配置修改时使用快速部署

  3. 数据库分离

    • 三个环境使用不同的数据库
    • 推广时不会迁移数据

  4. 公网访问

    • 开发版和生产版都配置了 Cloudflare Tunnel
    • 确保 Tunnel Token 正确配置

  5. Git 信息记录

    • 部署时会自动记录 Git 分支和 Commit 信息
    • 便于追踪部署历史

🚀 快速开始

方式1：使用 Web 界面（推荐）

# 启动 Web 管理界面
python start_deploy_manager.py

# 浏览器访问
# http://localhost:9001

方式2：使用命令行

# 查看所有环境状态
python scripts/deploy_manager.py status

# 部署到本地环境
python scripts/deploy_manager.py deploy local --rebuild

📞 帮助

如果遇到问题，可以：

  1. 查看部署历史：python scripts/deploy_manager.py history
  2. 检查环境状态：python scripts/deploy_manager.py status
  3. 查看日志：docker logs mbe-api 或 docker logs mbe-api-dev
  4. 参考文档：docs/guides/DEPLOYMENT_GUIDE.md