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

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

## 概述

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

## 背景

之前的部署流程需要手动执行两个步骤：
1. 启动 Docker 容器：`./start_docker.sh`
2. 手动执行迁移：`./migrate_db.sh`

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

## 变更内容

### 1. 修改 `start_docker.sh` 脚本

添加了智能迁移逻辑：

```bash
# 检查是否是首次部署（通过检查标记文件）
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`，避免提交到版本控制：

```gitignore
# 部署标记文件
.migration_initialized
```

## 使用方式

### 首次部署

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

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

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

### 后续部署

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

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

### 手动迁移

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

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

### 清理重建

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

```bash
./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. 迁移失败处理

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

## 相关文档

- [初始化数据库迁移系统](./2026-01-27-initial-schema-migration.md)
- [Alembic 迁移指南](../guides/alembic-migration-guide.md)
- [Docker 部署指南](../DEPLOYMENT.md)

## 总结

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