# 修复数据库迁移脚本

**日期**: 2026-01-27  
**类型**: Bug 修复  
**影响范围**: 数据库迁移工具

## 问题描述

`migrate_db.sh` 脚本存在以下问题：

1. **容器名称错误**：使用 `jointo-server-postgres` 而非正确的 `jointo-server-db`
2. **未在容器内执行**：直接在宿主机执行 Python 脚本，违反容器化规范
3. **使用旧的迁移脚本**：调用 `scripts/db_migrate.py` 而非标准的 Alembic 命令

## 解决方案

### 1. 修正容器名称

```bash
# ❌ 错误
if ! docker ps | grep -q "jointo-server-postgres"; then

# ✅ 正确
APP_CONTAINER="jointo-server-app"
DB_CONTAINER="jointo-server-db"
if ! docker ps | grep -q "${DB_CONTAINER}"; then
```

### 2. 在容器内执行命令

```bash
# ❌ 错误（宿主机执行）
python scripts/db_migrate.py upgrade

# ✅ 正确（容器内执行）
docker exec ${APP_CONTAINER} alembic upgrade head
```

### 3. 使用标准 Alembic 命令

所有迁移操作都使用 Alembic 标准命令：

```bash
# 升级
docker exec jointo-server-app alembic upgrade head

# 创建迁移
docker exec jointo-server-app alembic revision --autogenerate -m "描述"

# 回滚
docker exec jointo-server-app alembic downgrade -1

# 查看历史
docker exec jointo-server-app alembic history

# 查看当前版本
docker exec jointo-server-app alembic current
```

## 修改内容

### 核心改进

1. **容器化执行**
   - 所有命令通过 `docker exec` 在容器内执行
   - 符合项目 Docker 容器化规范

2. **标准化命令**
   - 使用 Alembic 官方命令
   - 移除对旧 `scripts/db_migrate.py` 的依赖

3. **容器检查**
   - 检查应用容器和数据库容器是否运行
   - 使用正确的容器名称

4. **错误处理**
   - 容器未运行时给出明确提示
   - 提供启动命令建议

### 新增功能

- `upgrade` 子命令：显式升级到最新版本
- 更清晰的帮助信息
- 容器状态检查

## 使用方式

### 基本用法

```bash
# 升级到最新版本（默认）
./migrate_db.sh

# 或显式指定
./migrate_db.sh upgrade

# 创建新迁移
./migrate_db.sh create "添加用户表"

# 回滚一个版本
./migrate_db.sh downgrade

# 查看迁移历史
./migrate_db.sh history

# 查看当前版本
./migrate_db.sh current

# 显示帮助
./migrate_db.sh --help
```

### 前置条件

确保 Docker 容器已启动：

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

# 或单独启动所需服务
docker-compose up -d jointo-server-db jointo-server-app
```

## 测试验证

### 测试 1：检查容器状态

```bash
./migrate_db.sh current
```

**预期输出**：
```
📦 检查 Docker 容器状态...
✓ Docker 容器运行正常
📊 当前版本
dc0e4f0a740c (head)
🎉 操作完成！
```

### 测试 2：升级数据库

```bash
./migrate_db.sh upgrade
```

**预期输出**：
```
📦 检查 Docker 容器状态...
✓ Docker 容器运行正常
🚀 升级数据库到最新版本
INFO  [alembic.runtime.migration] Running upgrade -> dc0e4f0a740c
🎉 操作完成！
```

### 测试 3：容器未运行

```bash
# 停止容器
docker-compose stop

# 尝试迁移
./migrate_db.sh
```

**预期输出**：
```
📦 检查 Docker 容器状态...
❌ 数据库容器未运行: jointo-server-db
请先启动服务：docker-compose up -d
```

## 影响范围

### 受益功能

- ✅ 所有数据库迁移操作
- ✅ 开发环境数据库管理
- ✅ 生产环境部署流程

### 行为变更

- ✅ 命令在容器内执行（符合规范）
- ✅ 使用标准 Alembic 命令
- ✅ 更严格的容器状态检查

### 兼容性

- ✅ 向后兼容：保留所有原有子命令
- ✅ 新增 `upgrade` 子命令（可选）
- ✅ 默认行为不变（升级到最新版本）

## 相关文档

- [Alembic 迁移系统](./2026-01-27-alembic-migration-system.md)
- [Alembic 迁移指南](../guides/alembic-migration-guide.md)
- [Docker 容器化规范](../../.kiro/steering/docker-container.md)

## 后续优化

1. **添加迁移验证**
   - 迁移前检查数据库连接
   - 迁移后验证表结构

2. **支持更多 Alembic 命令**
   - `stamp` - 标记版本
   - `show` - 显示迁移详情
   - `branches` - 显示分支

3. **集成到 CI/CD**
   - 自动运行迁移测试
   - 生产环境迁移审批流程