gongxiangp2/docs/migration-execution-guide.md

数据库迁移执行指南

📋 迁移前检查清单

• ✅ 迁移文件已创建：prisma/migrations/20251206000000_add_soft_delete_and_favorites/migration.sql
• ✅ 迁移脚本已准备：scripts/apply-migration.sh 和 scripts/apply-migration.ps1
• ✅ 安全性已确认：所有操作都是添加操作，不会影响现有素材数据
• ⏳ 数据库备份（强烈推荐）
• ⏳ 在影子系统测试迁移
• ⏳ 在生产系统执行迁移
• ⏳ 重新生成 Prisma Client

🚀 执行步骤

步骤 1：备份数据库（强烈推荐）

在服务器上执行：

# SSH 到服务器
ssh root@192.168.58.20

# 备份数据库
pg_dump "postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat" \
  -Fc -f "/mnt/PoolOne/backups/lobechat_before_migration_$(date +%Y%m%d_%H%M%S).dump"

# 验证备份文件
ls -lh /mnt/PoolOne/backups/lobechat_before_migration_*.dump

步骤 2：在影子系统测试迁移

方式一：使用迁移脚本（推荐）

# SSH 到服务器
ssh root@192.168.58.20

# 进入影子系统目录
cd /mnt/PoolOne/apps/youyidian-3d-shadow

# 确保迁移脚本有执行权限
chmod +x scripts/apply-migration.sh

# 执行迁移（确保 DATABASE_URL 指向 stage 库 lobechat_stage）
./scripts/apply-migration.sh

方式二：直接执行 Prisma 迁移

# SSH 到服务器
ssh root@192.168.58.20

# 进入影子系统目录
cd /mnt/PoolOne/apps/youyidian-3d-shadow

# 执行迁移
docker compose exec app npx prisma migrate deploy

步骤 3：验证迁移结果

在影子系统中验证新字段和表是否存在：

# 在容器内执行验证 SQL
docker compose exec app npx prisma db execute --stdin <<EOF
-- 检查 deletedAt 字段是否存在
SELECT column_name, data_type, is_nullable 
FROM information_schema.columns 
WHERE table_name = 'materials' AND column_name = 'deletedAt';

-- 检查新表是否存在
SELECT table_name 
FROM information_schema.tables 
WHERE table_name IN ('material_favorites', 'material_logs', 'material_download_logs');
EOF

预期结果：

• deletedAt 字段应该存在，类型为 timestamp without time zone，is_nullable 为 YES
• 三个新表都应该存在

步骤 4：测试影子系统功能

1. 访问影子系统：http://192.168.58.20:5320
2. 验证素材列表正常显示
3. 测试收藏功能（如果已实现 UI）
4. 检查是否有错误日志

步骤 5：在生产系统执行迁移

确认测试通过后，在生产系统执行：

# SSH 到服务器
ssh root@192.168.58.20

# 进入生产系统目录
cd /mnt/PoolOne/apps/youyidian-3d

# 执行迁移（确保 DATABASE_URL 指向生产库 lobechat）
docker compose exec app npx prisma migrate deploy

步骤 6：重新生成 Prisma Client

迁移后必须重新生成 Prisma Client：

# 在生产系统容器内执行
docker compose exec app npx prisma generate

# 重启应用容器以确保使用新的 Prisma Client
docker compose restart app

步骤 7：验证生产系统

1. 访问生产系统：http://192.168.58.20:4320
2. 验证素材列表正常显示
3. 测试新功能（收藏、个人中心等）
4. 检查应用日志是否有错误

⚠️ 注意事项

1. 执行时机：建议在低峰时段执行，避免影响用户使用
2. 备份优先：执行前务必备份数据库
3. 先测试后生产：先在影子系统测试，确认无误后再在生产系统执行
4. 监控日志：执行过程中注意观察应用日志，如有错误及时处理

🔄 回滚方案（如果需要）

如果迁移后出现问题，可以回滚：

-- 删除新字段（可选，不影响数据）
ALTER TABLE "materials" DROP COLUMN IF EXISTS "deletedAt";

-- 删除新表（可选，不影响 materials 表）
DROP TABLE IF EXISTS "material_favorites";
DROP TABLE IF EXISTS "material_logs";
DROP TABLE IF EXISTS "material_download_logs";

或者使用数据库备份恢复：

# 恢复数据库备份
pg_restore -d "postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat" \
  /mnt/PoolOne/backups/lobechat_before_migration_YYYYMMDD_HHMMSS.dump

✅ 迁移完成检查清单

• 数据库备份已完成
• 影子系统迁移执行成功
• 影子系统功能测试通过
• 生产系统迁移执行成功
• Prisma Client 已重新生成
• 生产系统功能测试通过
• 应用日志无错误