MBE Monorepo - 生产环境部署指南

本文档详细说明如何在生产环境中部署 MBE (Mises Behavior Engine) Monorepo。

📋 目录

前置要求
服务器配置
环境准备
部署步骤
配置说明
服务管理
监控和维护
故障排查

🔧 前置要求

硬件要求

最低配置：

CPU: 4 核
内存: 8GB RAM
磁盘: 50GB 可用空间
网络: 100Mbps

推荐配置：

CPU: 8 核或更多
内存: 16GB RAM 或更多
磁盘: 100GB+ SSD
网络: 1Gbps

软件要求

操作系统: Ubuntu 22.04 LTS 或更高版本（推荐）
Docker: >= 20.10
Docker Compose: >= 2.0
Git: >= 2.30

安装 Docker 和 Docker Compose

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker compose version

🖥️ 服务器配置

防火墙配置

# 允许 SSH（22）
sudo ufw allow 22/tcp

# 允许 HTTP/HTTPS（80/443）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 允许 API 端口（8000，如果直接暴露）
# sudo ufw allow 8000/tcp

# 启用防火墙
sudo ufw enable

系统优化

# 增加文件描述符限制
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# 优化内核参数（可选）
sudo sysctl -w vm.max_map_count=262144
sudo sysctl -w fs.file-max=2097152

📦 环境准备

1. 克隆仓库

# 创建应用目录
sudo mkdir -p /opt/mbe
sudo chown $USER:$USER /opt/mbe
cd /opt/mbe

# 克隆仓库（需要 SSH 密钥或访问权限）
git clone git@github.com:zenglx1978/mbe-monorepo.git .
# 或使用 HTTPS（需要访问令牌）
# git clone https://github.com/zenglx1978/mbe-monorepo.git .

2. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量（使用你喜欢的编辑器）
nano .env
# 或
vim .env

重要配置项：

# ===== 数据库配置 =====
POSTGRES_DB=mbe_prod
POSTGRES_USER=mbe_admin
POSTGRES_PASSWORD=<生成强密码>  # 必须修改！

# ===== Redis 配置 =====
REDIS_PASSWORD=<生成强密码>  # 必须修改！

# ===== API 配置 =====
MBE_ENV=production
MBE_DEBUG=0  # 生产环境关闭调试
MBE_SECRET_KEY=<生成随机字符串>  # 必须修改！

# ===== LLM API Keys =====
OPENAI_API_KEY=<你的 OpenAI API Key>
ANTHROPIC_API_KEY=<你的 Anthropic API Key>

# ===== 支付配置（如需要）=====
WECHAT_PAY_APP_ID=<微信支付 App ID>
WECHAT_PAY_MCH_ID=<微信支付商户号>
ALIPAY_APP_ID=<支付宝 App ID>

# ===== 邮件配置（如需要）=====
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=<SMTP 用户名>
SMTP_PASS=<SMTP 密码>

生成强密码：

# 生成随机密码
openssl rand -base64 32

# 生成 Secret Key
openssl rand -hex 32

3. 创建必要的目录

# 创建日志目录（如果需要）
mkdir -p logs

# 创建备份目录
mkdir -p backups

🚀 部署步骤

1. 构建 Docker 镜像

# 构建所有镜像（首次部署或更新代码后）
docker compose build

# 或只构建 API 镜像
docker compose build mbe-api

注意: 首次构建可能需要 10-30 分钟（下载 PyTorch 等大型依赖）

2. 启动服务

# 启动所有服务（后台运行）
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

3. 验证部署

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

# 检查详细健康状态
curl http://localhost:8000/api/health/detailed

# 检查 API 文档
curl http://localhost:8000/docs

预期输出：

{
  "status": "healthy",
  "service": "mises-behavior-engine"
}

4. 数据库初始化（首次部署）

# 如果需要运行数据库迁移
docker compose exec mbe-api python -m alembic upgrade head

# 或手动执行 SQL 脚本（如果有）
docker compose exec postgres psql -U mbe_admin -d mbe_prod -f /path/to/init.sql

⚙️ 配置说明

Docker Compose 服务

服务	说明	端口	健康检查
mbe-api	主 API 服务	8000	`/api/health`
mbe-worker	Celery 异步任务	-	-
mbe-beat	Celery 定时任务	-	-
postgres	PostgreSQL 数据库	5432	`pg_isready`
redis	Redis 缓存	6379	`redis-cli ping`

环境变量说明

详细环境变量说明请参考 .env.example 文件。

关键环境变量：

DATABASE_URL: PostgreSQL 连接字符串
REDIS_URL: Redis 连接字符串
PYTHONPATH: Python 模块搜索路径
MBE_ENV: 环境模式（development/staging/production）
MBE_DEBUG: 调试模式（0/1）

🔄 服务管理

启动/停止服务

# 启动所有服务
docker compose up -d

# 停止所有服务
docker compose down

# 重启特定服务
docker compose restart mbe-api

# 停止并删除数据卷（谨慎使用！）
docker compose down -v

查看日志

# 查看所有服务日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f mbe-api
docker compose logs -f mbe-worker

# 查看最近 100 行日志
docker compose logs --tail 100 mbe-api

更新部署

# 1. 拉取最新代码
git pull origin main

# 2. 重新构建镜像（如果代码有变更）
docker compose build

# 3. 重启服务（零停机时间部署）
docker compose up -d --no-deps mbe-api

# 或完全重启
docker compose down
docker compose up -d

📊 监控和维护

健康检查

# 设置定时健康检查（添加到 crontab）
*/5 * * * * curl -f http://localhost:8000/api/health || echo "API unhealthy" | mail -s "MBE Alert" admin@example.com

数据库备份

# 手动备份数据库
docker compose exec postgres pg_dump -U mbe_admin mbe_prod > backups/mbe_prod_$(date +%Y%m%d_%H%M%S).sql

# 设置自动备份（添加到 crontab）
0 2 * * * docker compose exec -T postgres pg_dump -U mbe_admin mbe_prod > /opt/mbe/backups/mbe_prod_$(date +\%Y\%m\%d).sql

# 清理旧备份（保留 30 天）
find /opt/mbe/backups -name "*.sql" -mtime +30 -delete

Redis 持久化

Redis 数据默认持久化到 Docker volume mbe-monorepo_redis_data。

日志轮转

# 配置 Docker 日志轮转（在 docker-compose.yml 中添加）
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

资源监控

# 查看容器资源使用
docker stats

# 查看磁盘使用
docker system df

# 清理未使用的资源
docker system prune -a

🔒 安全配置

1. 使用反向代理（Nginx）

安装 Nginx：

sudo apt install nginx

配置 Nginx（/etc/nginx/sites-available/mbe）：

server {
    listen 80;
    server_name your-domain.com;

    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL 证书配置（使用 Let's Encrypt）
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 代理到 API
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/mbe /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

2. SSL 证书（Let's Encrypt）

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 自动续期（已自动配置）
sudo certbot renew --dry-run

3. 防火墙规则

# 只允许 Nginx 端口对外开放
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 禁止直接访问 API 端口（如果使用 Nginx）
sudo ufw delete allow 8000/tcp

4. 数据库安全

使用强密码
限制数据库端口访问（仅允许本地）
定期备份
启用 SSL 连接（生产环境）

🐛 故障排查

服务无法启动

# 检查服务状态
docker compose ps

# 查看错误日志
docker compose logs mbe-api

# 检查容器资源使用
docker stats

# 检查磁盘空间
df -h

数据库连接失败

# 检查数据库是否运行
docker compose ps postgres

# 测试数据库连接
docker compose exec postgres psql -U mbe_admin -d mbe_prod -c "SELECT 1;"

# 检查环境变量
docker compose exec mbe-api env | grep DATABASE_URL

Redis 连接失败

# 检查 Redis 是否运行
docker compose ps redis

# 测试 Redis 连接
docker compose exec redis redis-cli -a <REDIS_PASSWORD> ping

# 检查环境变量
docker compose exec mbe-api env | grep REDIS_URL

API 响应慢

# 查看 API 日志
docker compose logs mbe-api | grep -i error

# 检查数据库查询性能
docker compose exec postgres psql -U mbe_admin -d mbe_prod -c "SELECT * FROM pg_stat_activity;"

# 检查 Redis 性能
docker compose exec redis redis-cli -a <REDIS_PASSWORD> INFO stats

磁盘空间不足

# 清理未使用的 Docker 资源
docker system prune -a

# 清理旧日志
docker compose logs --no-log-prefix mbe-api | tail -n 0

# 检查大文件
du -sh /var/lib/docker/volumes/*

📞 支持

如遇到问题：

查看日志：docker compose logs -f
检查健康状态：curl http://localhost:8000/api/health/detailed
查看 GitHub Issues（仅限公开模块）
联系项目维护者

最后更新：2026-02-06