5.3 KiB

Raw Blame History

首次部署自动执行数据库迁移

日期: 2026-01-27
类型: 部署优化
影响范围: Docker 启动脚本

概述

优化 Docker 启动脚本，在首次部署或清理模式下自动执行数据库迁移，简化部署流程。

背景

之前的部署流程需要手动执行两个步骤：

启动 Docker 容器：./start_docker.sh
手动执行迁移：./migrate_db.sh

这对于首次部署的用户不够友好，容易遗漏迁移步骤导致应用启动失败。

变更内容

1. 修改 `start_docker.sh` 脚本

添加了智能迁移逻辑：

# 检查是否是首次部署（通过检查标记文件）
MIGRATION_MARKER=".migration_initialized"

if [ "$CLEAN_MODE" = true ] || [ ! -f "$MIGRATION_MARKER" ]; then
    echo "🔄 检测到首次部署或清理模式，自动执行数据库迁移..."
    
    # 等待数据库完全就绪
    echo "⏳ 等待数据库就绪..."
    sleep 3
    
    # 执行数据库迁移
    echo "📊 执行数据库迁移..."
    docker exec jointo-server-app alembic upgrade head
    
    if [ $? -eq 0 ]; then
        echo "✅ 数据库迁移成功"
        # 创建标记文件
        touch "$MIGRATION_MARKER"
    else
        echo "❌ 数据库迁移失败，请检查日志"
        echo "💡 可以手动执行: docker exec jointo-server-app alembic upgrade head"
    fi
else
    echo "ℹ️  非首次部署，跳过自动迁移"
    echo "💡 如需手动迁移，请执行: ./migrate_db.sh"
fi

2. 添加标记文件机制

标记文件: server/.migration_initialized
作用: 标识数据库已完成初始化迁移
创建时机: 首次迁移成功后自动创建
清除时机: 使用 --clean 参数时自动清除

3. 更新 `.gitignore`

将标记文件添加到 .gitignore，避免提交到版本控制：

# 部署标记文件
.migration_initialized

使用方式

首次部署

# 启动容器（自动执行迁移）
./start_docker.sh

# 或者使用完整参数
./start_docker.sh --clean --build

输出示例：

🐳 启动 Docker 容器化开发环境...
📦 清理旧容器和卷...
🔨 强制重新构建镜像...
⏳ 等待服务启动...
🔄 检测到首次部署或清理模式，自动执行数据库迁移...
⏳ 等待数据库就绪...
📊 执行数据库迁移...
✅ 数据库迁移成功
✅ 检查服务状态...
🎉 服务启动完成！

后续部署

# 快速重启（不执行迁移）
./start_docker.sh

# 输出示例：
# ℹ️  非首次部署，跳过自动迁移
# 💡 如需手动迁移，请执行: ./migrate_db.sh

手动迁移

如果需要手动执行迁移（例如更新了模型）：

./migrate_db.sh
# 或
docker exec jointo-server-app alembic upgrade head

清理重建

使用 --clean 参数会清除数据并重新执行迁移：

./start_docker.sh --clean

工作流程

首次部署流程

启动脚本
  ↓
检查标记文件 (.migration_initialized)
  ↓
不存在 → 首次部署
  ↓
启动 Docker 容器
  ↓
等待服务就绪 (5秒 + 3秒)
  ↓
执行数据库迁移 (alembic upgrade head)
  ↓
迁移成功 → 创建标记文件
  ↓
完成

后续部署流程

启动脚本
  ↓
检查标记文件 (.migration_initialized)
  ↓
存在 → 非首次部署
  ↓
启动 Docker 容器
  ↓
跳过自动迁移
  ↓
提示手动迁移命令
  ↓
完成

清理模式流程

启动脚本 (--clean)
  ↓
清理容器和卷 (docker compose down -v)
  ↓
删除标记文件（隐式）
  ↓
启动 Docker 容器
  ↓
检测到清理模式 → 自动执行迁移
  ↓
创建标记文件
  ↓
完成

优势

1. 用户体验优化

✅ 首次部署一键完成，无需记忆额外命令
✅ 自动化程度高，减少人为错误
✅ 清晰的日志输出，便于排查问题

2. 开发效率提升

✅ 新成员快速上手，降低学习成本
✅ CI/CD 流程简化，减少部署步骤
✅ 清理重建更方便，开发调试更高效

3. 安全性保障

✅ 后续部署不会误执行迁移，避免数据风险
✅ 标记文件机制简单可靠
✅ 迁移失败有明确提示和补救方案

注意事项

1. 标记文件管理

不要手动删除 server/.migration_initialized 文件，除非你确实需要重新初始化数据库
清理模式 (--clean) 会清除所有数据，请谨慎使用

2. 生产环境部署

生产环境建议：

首次部署使用自动迁移
后续更新手动执行迁移，确保可控性
迁移前务必备份数据库

3. 迁移失败处理

如果自动迁移失败：

查看错误日志：docker compose logs app
检查数据库连接：docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\l"
手动执行迁移：docker exec jointo-server-app alembic upgrade head
如果问题持续，使用 --clean 参数清理重建

总结

通过智能检测机制，实现了首次部署自动迁移、后续部署手动控制的最佳实践，既保证了便利性，又确保了安全性。

5.3 KiB Raw Blame History