docs/v1.0/server/changelogs/2026-01-27-migrate-script-fix.md

修复数据库迁移脚本

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

问题描述

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

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

解决方案

1. 修正容器名称

# ❌ 错误
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. 在容器内执行命令

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

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

3. 使用标准 Alembic 命令

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

# 升级
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 子命令：显式升级到最新版本
• 更清晰的帮助信息
• 容器状态检查

使用方式

基本用法

# 升级到最新版本（默认）
./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 容器已启动：

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

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

测试验证

测试 1：检查容器状态

./migrate_db.sh current

预期输出：

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

测试 2：升级数据库

./migrate_db.sh upgrade

预期输出：

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

测试 3：容器未运行

# 停止容器
docker-compose stop

# 尝试迁移
./migrate_db.sh

预期输出：

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

影响范围

受益功能

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

行为变更

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

兼容性

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

相关文档

• Alembic 迁移系统
• Alembic 迁移指南
• Docker 容器化规范

后续优化

1. 添加迁移验证

   • 迁移前检查数据库连接
   • 迁移后验证表结构

2. 支持更多 Alembic 命令

   • stamp - 标记版本
   • show - 显示迁移详情
   • branches - 显示分支

3. 集成到 CI/CD

   • 自动运行迁移测试
   • 生产环境迁移审批流程