MBE 生产环境完整部署指南

本文档提供 MBE 系统在生产环境的完整部署流程，包括数据库迁移、备份恢复、高可用性配置等。

目录

• 数据库迁移
• 备份和恢复
• 高可用性配置
• 负载均衡
• 服务监控和自动重启
• 生产环境检查清单

数据库迁移

MBE 使用 Alembic 管理数据库 schema 变更。

安装 Alembic

pip install alembic

初始化（首次部署）

# 初始化 Alembic（已配置好）
# alembic init database/migrations

# 检查配置
cat alembic.ini

创建迁移脚本

# 自动检测模型变化并生成迁移
alembic revision --autogenerate -m "Initial schema"

# 手动创建空白迁移
alembic revision -m "Add custom index"

执行迁移

# 查看当前版本
alembic current

# 查看待执行的迁移
alembic history

# 升级到最新版本
alembic upgrade head

# 升级到特定版本
alembic upgrade <revision_id>

# 降级一个版本
alembic downgrade -1

# 回滚到特定版本
alembic downgrade <revision_id>

迁移最佳实践

1. 开发环境测试

   # 1. 在开发环境创建迁移
   alembic revision --autogenerate -m "Add user_profile table"
   
   # 2. 检查生成的迁移脚本
   cat database/migrations/versions/xxx_add_user_profile_table.py
   
   # 3. 执行迁移
   alembic upgrade head
   
   # 4. 测试回滚
   alembic downgrade -1
   alembic upgrade head
   

2. 生产环境部署

   # 1. 备份数据库
   python scripts/backup_database.py backup
   
   # 2. 执行迁移
   alembic upgrade head
   
   # 3. 验证
   alembic current
   
   # 4. 如果失败，回滚
   # alembic downgrade -1
   

3. 零停机迁移

   • 避免删除列（先标记为 nullable）
   • 避免修改列类型（使用多步迁移）
   • 使用索引并发创建（CONCURRENTLY）

备份和恢复

1. 数据库备份

自动备份（推荐）

使用 cron 任务自动备份：

# 安装 cron 任务
sudo cp deploy/cron/mbe-backup /etc/cron.d/
sudo chmod 644 /etc/cron.d/mbe-backup

# 查看 cron 日志
tail -f /var/log/mbe/backup.log

手动备份

# 创建备份
python scripts/backup_database.py backup

# 列出所有备份
python scripts/backup_database.py list

# 清理旧备份
python scripts/backup_database.py cleanup

恢复数据库

# 恢复最新备份
python scripts/backup_database.py restore

# 恢复指定备份
python scripts/backup_database.py restore --file /var/backups/mbe/database/mbe_backup_20260206_100000.sql.gz

2. Redis 备份

手动备份

# 创建备份
python scripts/backup_redis.py backup

# 列出所有备份
python scripts/backup_redis.py list

# 清理旧备份
python scripts/backup_redis.py cleanup

恢复 Redis

# 恢复最新备份
python scripts/backup_redis.py restore

# 恢复指定备份
python scripts/backup_redis.py restore --file /var/backups/mbe/redis/redis_backup_20260206_100000.rdb.gz

3. 备份配置

环境变量：

# 备份目录
BACKUP_DIR=/var/backups/mbe

# 数据库配置
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=mbe
POSTGRES_USER=mbe
POSTGRES_PASSWORD=your_password

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_password
REDIS_DATA_DIR=/var/lib/redis

# 保留天数
BACKUP_RETENTION_DAYS=30

4. 备份验证

定期验证备份可用性：

# 1. 在测试环境恢复备份
python scripts/backup_database.py restore --file /path/to/backup.sql.gz

# 2. 运行测试验证数据完整性
pytest tests/integration/test_database.py

# 3. 检查关键数据
psql -h localhost -U mbe -d mbe_test -c "SELECT COUNT(*) FROM users;"

高可用性配置

1. Redis 持久化

使用 RDB + AOF 混合持久化模式。

配置文件： deploy/redis/redis.conf

# 复制配置到 Redis 数据目录
sudo cp deploy/redis/redis.conf /etc/redis/redis.conf

# 重启 Redis
sudo systemctl restart redis

# 验证持久化
redis-cli CONFIG GET appendonly
redis-cli CONFIG GET save

2. PostgreSQL 主从复制（可选）

主节点配置

编辑 /etc/postgresql/16/main/postgresql.conf:

# 复制配置
wal_level = replica
max_wal_senders = 5
max_replication_slots = 5
hot_standby = on

# 归档配置
archive_mode = on
archive_command = 'cp %p /var/lib/postgresql/16/archive/%f'

编辑 /etc/postgresql/16/main/pg_hba.conf:

# 允许从节点连接
host replication replicator 192.168.1.0/24 md5

重启主节点：

sudo systemctl restart postgresql

从节点配置

在从节点创建复制：

# 停止从节点 PostgreSQL
sudo systemctl stop postgresql

# 清空数据目录
sudo rm -rf /var/lib/postgresql/16/main/*

# 基础备份（从主节点）
sudo -u postgres pg_basebackup -h <master_ip> -U replicator -D /var/lib/postgresql/16/main -P -Xs -R

# 启动从节点
sudo systemctl start postgresql

3. Redis 哨兵模式（可选）

配置哨兵

redis-sentinel.conf:

# 监控主节点
sentinel monitor mbe-master 192.168.1.100 6379 2

# 认证
sentinel auth-pass mbe-master your_redis_password

# 故障转移配置
sentinel down-after-milliseconds mbe-master 5000
sentinel parallel-syncs mbe-master 1
sentinel failover-timeout mbe-master 10000

启动哨兵

# 启动 3 个哨兵实例（至少3个）
redis-sentinel /etc/redis/sentinel-1.conf
redis-sentinel /etc/redis/sentinel-2.conf
redis-sentinel /etc/redis/sentinel-3.conf

负载均衡

使用 Nginx 实现负载均衡和反向代理。

1. 安装 Nginx

sudo apt update
sudo apt install nginx

2. 配置 Nginx

# 复制配置文件
sudo cp deploy/nginx/mbe.conf /etc/nginx/sites-available/

# 创建软链接
sudo ln -s /etc/nginx/sites-available/mbe.conf /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx

3. SSL 证书（Let's Encrypt）

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

# 获取证书
sudo certbot --nginx -d api.example.com

# 自动续期（添加到 cron）
sudo certbot renew --dry-run

# 设置自动续期
echo "0 0 * * * root certbot renew --quiet" | sudo tee -a /etc/cron.d/certbot

4. 负载均衡策略

Nginx 支持多种负载均衡策略：

upstream mbe_api_backend {
    # 轮询（默认）
    server mbe-api-1:8000;
    server mbe-api-2:8000;
    
    # 最少连接
    # least_conn;
    
    # IP Hash（同一客户端总是到同一服务器）
    # ip_hash;
    
    # 权重
    # server mbe-api-1:8000 weight=3;
    # server mbe-api-2:8000 weight=1;
}

服务监控和自动重启

1. Systemd 服务配置

安装服务

# 复制服务文件
sudo cp deploy/systemd/mbe-api.service /etc/systemd/system/
sudo cp deploy/systemd/mbe-worker.service /etc/systemd/system/

# 重载 systemd
sudo systemctl daemon-reload

# 启用服务（开机自启）
sudo systemctl enable mbe-api
sudo systemctl enable mbe-worker

# 启动服务
sudo systemctl start mbe-api
sudo systemctl start mbe-worker

# 查看状态
sudo systemctl status mbe-api
sudo systemctl status mbe-worker

服务管理

# 启动
sudo systemctl start mbe-api

# 停止
sudo systemctl stop mbe-api

# 重启
sudo systemctl restart mbe-api

# 重载配置（优雅重启）
sudo systemctl reload mbe-api

# 查看日志
sudo journalctl -u mbe-api -f

# 查看最近50行日志
sudo journalctl -u mbe-api -n 50

2. 健康检查和自动重启

Systemd 配置自动重启：

[Service]
Restart=always
RestartSec=10
StartLimitInterval=0

3. 监控脚本（可选）

创建监控脚本 scripts/monitor_services.sh:

#!/bin/bash
# 检查服务健康并自动重启

check_service() {
    SERVICE=$1
    
    if ! systemctl is-active --quiet $SERVICE; then
        echo "❌ $SERVICE 已停止，正在重启..."
        sudo systemctl restart $SERVICE
        
        # 发送告警（可选）
        curl -X POST https://your-webhook-url \
            -d "{'text': 'MBE Service $SERVICE was down and restarted'}"
    else
        echo "✅ $SERVICE 运行正常"
    fi
}

check_service "mbe-api"
check_service "mbe-worker"

# 检查 API 健康
if ! curl -f http://localhost:8000/api/health > /dev/null 2>&1; then
    echo "❌ API 健康检查失败，重启服务..."
    sudo systemctl restart mbe-api
fi

添加到 cron（每5分钟检查）：

*/5 * * * * /opt/mbe-monorepo/scripts/monitor_services.sh >> /var/log/mbe/monitor.log 2>&1

生产环境检查清单

部署前检查

• 环境变量配置完成（.env）
• 数据库密码已修改（强密码）
• Redis 密码已修改（强密码）
• SECRET_KEY 已修改（随机字符串）
• CORS 白名单已配置（具体域名）
• SSL 证书已安装
• Nginx 配置已测试
• 防火墙规则已配置
• 备份目录已创建
• 日志目录已创建

部署步骤

# 1. 克隆代码
cd /opt
sudo git clone https://github.com/zenglx1978/mbe-monorepo.git
cd mbe-monorepo

# 2. 配置环境变量
sudo cp .env.example .env
sudo nano .env  # 修改所有敏感配置

# 3. 创建必要目录
sudo mkdir -p /var/log/mbe
sudo mkdir -p /var/backups/mbe/database
sudo mkdir -p /var/backups/mbe/redis

# 4. 安装依赖
pip install -r shared/requirements.txt
pip install -r private/core/requirements.txt
pip install -r private/platform/requirements.txt
pip install alembic

# 5. 数据库迁移
alembic upgrade head

# 6. 配置 systemd 服务
sudo cp deploy/systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mbe-api mbe-worker

# 7. 配置 Nginx
sudo cp deploy/nginx/mbe.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/mbe.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 8. 配置 Redis 持久化
sudo cp deploy/redis/redis.conf /etc/redis/redis.conf
sudo systemctl restart redis

# 9. 配置自动备份
sudo cp deploy/cron/mbe-backup /etc/cron.d/
sudo chmod 644 /etc/cron.d/mbe-backup

# 10. 启动服务
sudo systemctl start mbe-api
sudo systemctl start mbe-worker

# 11. 验证服务
curl http://localhost:8000/api/health
curl https://api.example.com/api/health

部署后验证

• API 健康检查正常（/api/health）
• 数据库连接正常（/api/health/detailed）
• Redis 连接正常（/api/health/detailed）
• SSL 证书有效
• 监控指标可访问（/api/metrics）
• 日志正常记录（/var/log/mbe/）
• 备份任务已配置（crontab -l）

使用 Docker 部署（推荐）

单机部署

# 1. 克隆代码
git clone https://github.com/zenglx1978/mbe-monorepo.git
cd mbe-monorepo

# 2. 配置环境变量
cp .env.example .env
nano .env  # 修改配置

# 3. 构建镜像
docker compose build

# 4. 启动服务
docker compose up -d

# 5. 执行数据库迁移
docker compose exec mbe-api alembic upgrade head

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

# 7. 验证服务
curl http://localhost:8000/api/health

多实例部署（负载均衡）

使用 Docker Swarm 或 Kubernetes。

Docker Swarm 示例

# 1. 初始化 Swarm
docker swarm init

# 2. 部署 Stack
docker stack deploy -c docker-compose.yml mbe

# 3. 扩展 API 实例
docker service scale mbe_mbe-api=3

# 4. 查看服务
docker service ls
docker service ps mbe_mbe-api

高可用性架构

架构图

                         ┌─────────────┐
                         │   Nginx     │
                         │ (Load Bal.) │
                         └──────┬──────┘
                                │
                ┌───────────────┼───────────────┐
                │               │               │
           ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
           │ API-1   │     │ API-2   │     │ API-3   │
           └────┬────┘     └────┬────┘     └────┬────┘
                │               │               │
                └───────────────┼───────────────┘
                                │
                    ┌───────────┴───────────┐
                    │                       │
              ┌─────▼─────┐         ┌──────▼──────┐
              │PostgreSQL │         │   Redis     │
              │ (Master)  │         │ (Sentinel)  │
              └─────┬─────┘         └─────────────┘
                    │
              ┌─────▼─────┐
              │PostgreSQL │
              │ (Replica) │
              └───────────┘

关键组件

1. Nginx: 负载均衡 + SSL 终止
2. 多个 API 实例: 水平扩展
3. PostgreSQL 主从: 读写分离
4. Redis 哨兵: 自动故障转移

监控和告警

1. 部署监控栈

# 启动 Prometheus + Grafana + AlertManager
docker compose -f docker-compose.monitoring.yml up -d

# 访问 Grafana
# http://your-server:3000

2. 配置告警

编辑 monitoring/grafana/alertmanager.yml:

• 配置 Email/Slack/钉钉通知
• 重启 AlertManager

docker compose -f docker-compose.monitoring.yml restart alertmanager

3. 查看监控

• Grafana: http://your-server:3000
• Prometheus: http://your-server:9090
• AlertManager: http://your-server:9093

故障恢复流程

数据库故障

# 1. 检查数据库状态
sudo systemctl status postgresql

# 2. 查看日志
sudo journalctl -u postgresql -n 100

# 3. 如果需要恢复
python scripts/backup_database.py restore

# 4. 重启服务
sudo systemctl restart postgresql
sudo systemctl restart mbe-api

Redis 故障

# 1. 检查 Redis 状态
sudo systemctl status redis

# 2. 查看日志
sudo tail -f /var/log/redis/redis.log

# 3. 如果需要恢复
python scripts/backup_redis.py restore

# 4. 重启服务
sudo systemctl restart redis

应用故障

# 1. 查看服务状态
sudo systemctl status mbe-api
sudo systemctl status mbe-worker

# 2. 查看日志
sudo journalctl -u mbe-api -n 100

# 3. 重启服务
sudo systemctl restart mbe-api
sudo systemctl restart mbe-worker

# 4. 如果问题持续，回滚代码
git log -5
git checkout <previous_commit>
sudo systemctl restart mbe-api

性能调优

系统级别

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

# 2. 优化内核参数
sudo tee -a /etc/sysctl.conf <<EOF
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.ip_local_port_range = 10000 65000
net.ipv4.tcp_tw_reuse = 1
EOF

sudo sysctl -p

数据库调优

编辑 /etc/postgresql/16/main/postgresql.conf:

# 内存配置（根据服务器内存调整）
shared_buffers = 4GB
effective_cache_size = 12GB
maintenance_work_mem = 1GB
work_mem = 64MB

# 连接配置
max_connections = 200

# 查询优化
random_page_cost = 1.1
effective_io_concurrency = 200

总结

完整的生产环境准备包括：

✅ 数据库迁移 - Alembic schema 管理
✅ 自动备份 - 每日备份数据库和 Redis
✅ 备份恢复 - 快速恢复工具
✅ 高可用性 - PostgreSQL 主从 + Redis 哨兵
✅ 负载均衡 - Nginx 多实例
✅ 自动重启 - Systemd 监控
✅ 监控告警 - Prometheus + Grafana
✅ 故障恢复 - 完整恢复流程

系统已具备生产级别的稳定性和可靠性！🚀