MBE 文档中心

🚀 MBE 自动部署指南

📋 概述

MBE Monorepo 提供了两种自动部署工作流：

  1. 完整版部署 (deploy.yml) - 使用 Docker Registry，适合生产环境
  2. 简化版部署 (deploy-simple.yml) - 直接构建部署，适合快速迭代

🔧 前置配置

1. GitHub Secrets 配置

在 GitHub 仓库设置中添加以下 Secrets：

生产环境部署所需 Secrets：

# SSH 连接配置
DEPLOY_SSH_KEY:        # SSH 私钥（用于连接服务器）
DEPLOY_HOST:           # 服务器地址（如：mbe.hi-maker.com 或 IP）
DEPLOY_USER:           # SSH 用户名（如：ubuntu）
DEPLOY_PATH:           # 部署目录（如：/opt/mbe）

# Staging 环境（可选）
STAGING_SSH_KEY:       # Staging 环境 SSH 私钥
STAGING_HOST:          # Staging 服务器地址
STAGING_USER:          # Staging SSH 用户名
STAGING_PATH:          # Staging 部署目录

# 通知配置（可选）
SLACK_WEBHOOK:         # Slack Webhook URL
DISCORD_WEBHOOK:       # Discord Webhook URL

2. 生成 SSH 密钥对

# 在本地生成 SSH 密钥对
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key

# 将公钥添加到服务器
ssh-copy-id -i ~/.ssh/deploy_key.pub user@your-server.com

# 将私钥内容复制到 GitHub Secrets (DEPLOY_SSH_KEY)
cat ~/.ssh/deploy_key

3. 服务器准备

确保服务器已安装：

  • Docker >= 20.10
  • Docker Compose >= 2.0
  • Git
# 在服务器上创建部署目录
sudo mkdir -p /opt/mbe
sudo chown $USER:$USER /opt/mbe
cd /opt/mbe

# 初始化 Git 仓库（如果还没有）
git clone https://github.com/your-org/mbe-monorepo.git .
# 或
git init
git remote add origin https://github.com/your-org/mbe-monorepo.git

🔄 部署工作流说明

完整版部署 (deploy.yml)

触发条件：

  • CI Pipeline 成功完成后自动触发
  • 手动触发（可选择环境）

流程：

  1. ✅ 检查 CI 状态
  2. 🐳 构建 Docker 镜像
  3. 📦 推送到 GitHub Container Registry
  4. 🚀 SSH 部署到服务器
  5. 🏥 健康检查
  6. 📢 发送通知

优点：

  • 镜像可复用
  • 支持回滚
  • 适合生产环境

简化版部署 (deploy-simple.yml)

触发条件：

  • Push 到 master 分支
  • 手动触发

流程：

  1. 📥 SSH 连接到服务器
  2. 🔄 拉取最新代码
  3. 🔨 构建 Docker 镜像
  4. 🚀 重启服务
  5. 🏥 健康检查

优点：

  • 配置简单
  • 快速部署
  • 适合开发/测试环境

📝 使用方法

自动部署（推荐）

  1. 配置 Secrets（一次性）

    • 在 GitHub 仓库设置中添加所需 Secrets

  2. 推送代码

    git push origin master

  3. 等待部署

    • CI Pipeline 运行
    • 通过后自动触发部署
    • 查看 GitHub Actions 日志

手动部署

  1. 在 GitHub Actions 页面
    • 选择 "Deploy to Production" 工作流
    • 点击 "Run workflow"
    • 选择环境（production/staging）
    • 点击 "Run workflow"

🔍 部署验证

检查部署状态

# SSH 连接到服务器
ssh user@your-server.com

# 检查容器状态
cd /opt/mbe
docker-compose ps

# 查看日志
docker-compose logs -f mbe-api

# 健康检查
curl http://localhost:8000/api/health

回滚部署

# 在服务器上
cd /opt/mbe

# 回滚到上一个版本
git checkout <previous-commit>
docker-compose down
docker-compose up -d

# 或使用备份的配置
cp docker-compose.yml.backup.* docker-compose.yml
docker-compose up -d

🛠️ 故障排查

常见问题

  1. SSH 连接失败

    • 检查 DEPLOY_SSH_KEY 是否正确
    • 确认服务器允许 SSH 连接
    • 检查防火墙设置

  2. 部署目录不存在

    • 确认 DEPLOY_PATH 配置正确
    • 在服务器上创建目录并设置权限

  3. Docker 构建失败

    • 检查 Dockerfile 语法
    • 确认依赖文件存在
    • 查看构建日志

  4. 健康检查失败

    • 检查服务日志：docker-compose logs
    • 确认端口未被占用
    • 检查环境变量配置

查看部署日志

在 GitHub Actions 页面：

  1. 进入 "Actions" 标签
  2. 选择对应的部署工作流
  3. 查看各步骤的详细日志

🔐 安全建议

  1. 使用 SSH 密钥认证

    • 不要使用密码认证
    • 定期轮换 SSH 密钥

  2. 限制服务器访问

    • 使用防火墙限制 SSH 端口
    • 仅允许特定 IP 访问

  3. 保护 Secrets

    • 不要在代码中硬编码密钥
    • 使用 GitHub Secrets 管理敏感信息

  4. 监控部署

    • 设置部署通知
    • 监控服务健康状态
    • 记录部署历史

📚 相关文档

✅ 检查清单

部署前确保：

  • GitHub Secrets 已配置
  • SSH 密钥已添加到服务器
  • 服务器 Docker 环境正常
  • 部署目录权限正确
  • CI Pipeline 通过
  • 环境变量已配置
  • 数据库迁移已完成（如需要）

注意: 首次部署建议使用手动触发，验证配置正确后再启用自动部署。