gongxiangp2/scripts/migrate-product-package-README.md

任务-详情老素材迁移指南

概述

本脚本用于将"任务-详情"老素材（只有S3预览图）迁移到新逻辑（本地zip文件）。

安全措施

1. 保留老数据：不删除原有的资产记录，只新增记录
2. 分批迁移：每次处理5个素材，避免一次性迁移导致问题
3. 演练模式：可以先运行演练模式，不实际修改数据库
4. 完整日志：记录每个素材的迁移状态和错误信息
5. 错误处理：单个素材失败不影响其他素材

使用步骤

1. 数据库备份（必须！）

# 在生产服务器上备份数据库
ssh root@192.168.58.20
docker exec gongxiangpan-postgres-1 pg_dump -U gongxiangpan lobechat > /root/backup/lobechat_before_migration_$(date +%Y%m%d_%H%M%S).sql

2. 演练模式测试

# 修改脚本配置
# CONFIG.dryRun = true
# CONFIG.batchSize = 2

# 运行演练
npx tsx scripts/migrate-product-package-old-materials.ts

3. 小批量测试

# 修改脚本配置
# CONFIG.dryRun = false
# CONFIG.batchSize = 2

# 迁移2个素材
npx tsx scripts/migrate-product-package-old-materials.ts

4. 验证测试结果

• 检查首页预览图是否正常显示
• 测试下载功能是否正常
• 检查详情页是否正常
• 检查外部接口是否正常

5. 批量迁移

# 修改脚本配置
# CONFIG.batchSize = 10

# 多次运行，每次迁移10个
npx tsx scripts/migrate-product-package-old-materials.ts

配置说明

const CONFIG = {
  batchSize: 5,        // 每批处理的素材数量
  dryRun: false,       // 是否为演练模式（不实际修改数据库）
  skipDownload: false, // 是否跳过下载（用于测试打包逻辑）
};

迁移流程

1. 查询需要迁移的素材（zipFilePath为空或zipFileSize=0）
2. 从S3下载预览图到临时目录
3. 将预览图打包成分类zip（main.zip、sku.zip、detail.zip）
4. 打包总zip（all.zip，包含三个分类zip）
5. 新增资产记录：
   • main-preview/sku-preview/detail-preview（指向S3预览图）
   • main/sku/detail（指向本地zip文件）
   • all（指向总zip文件）
6. 更新素材记录（zipFilePath、zipFileName、zipFileSize）
7. 清理临时文件

数据变化

迁移前

materials 表:
- zipFilePath: NULL 或 ''
- zipFileSize: 0

material_assets 表:
- assetType: 'main' (S3预览图)
- assetType: 'sku' (S3预览图)
- assetType: 'detail' (S3预览图)
- assetType: 'psd' (本地文件)

迁移后

materials 表:
- zipFilePath: 'uploads/materials/xxx_all_xxx.zip'
- zipFileSize: 12345678

material_assets 表（新增，老记录保留）:
- assetType: 'main-preview' (S3预览图，新增)
- assetType: 'sku-preview' (S3预览图，新增)
- assetType: 'detail-preview' (S3预览图，新增)
- assetType: 'main' (本地zip，新增)
- assetType: 'sku' (本地zip，新增)
- assetType: 'detail' (本地zip，新增)
- assetType: 'all' (本地zip，新增)
- assetType: 'psd' (本地文件，保留)

回滚方案

如果迁移后发现问题，可以执行回滚：

-- 1. 删除新增的资产记录
DELETE FROM material_assets
WHERE material_id IN (
  SELECT id FROM materials
  WHERE "materialType" = '任务-详情'
  AND "zipFilePath" IS NOT NULL
  AND "zipFilePath" != ''
)
AND asset_type IN ('main-preview', 'sku-preview', 'detail-preview', 'all')
AND created_at > '2026-01-20 14:00:00'; -- 迁移开始时间

-- 2. 恢复素材记录
UPDATE materials
SET
  "zipFilePath" = '',
  "zipFileName" = '',
  "zipFileSize" = 0
WHERE "materialType" = '任务-详情'
AND "zipFilePath" IS NOT NULL
AND "zipFilePath" != ''
AND updated_at > '2026-01-20 14:00:00'; -- 迁移开始时间

注意事项

1. 必须先备份数据库
2. 先小批量测试，验证无误后再批量迁移
3. 迁移过程中不要停止脚本
4. 保留迁移日志文件
5. 迁移完成后验证功能

监控指标

• 迁移成功率
• 下载失败的文件数
• 打包失败的素材数
• 数据库更新失败的素材数
• 平均迁移时间

常见问题

Q: 迁移失败怎么办？

A: 单个素材失败不影响其他素材，可以查看日志文件了解失败原因，修复后重新运行脚本。

Q: 迁移过程中可以停止吗？

A: 可以，但建议等当前素材处理完成后再停止。已迁移的素材不会重复迁移。

Q: 如何验证迁移是否成功？

A:

1. 检查日志文件中的成功/失败统计
2. 在首页查看素材预览图是否正常
3. 测试下载功能
4. 检查数据库中的记录是否正确

Q: 迁移后老数据会被删除吗？

A: 不会，老数据会被保留，只是新增了新的记录。

联系方式

如有问题，请联系开发团队。