- 迁移57个老素材到新逻辑(本地zip + S3预览图) - 优化文件命名:SPU_作者_店铺_类型.zip - PSD文件单独存储,不打包进all.zip - 修复下载接口,优先使用本地zip文件 - 修复预览图重复问题 - 添加迁移脚本和验证脚本 - 更新文档和迁移计划 迁移统计: - 总素材数:77个 - 成功迁移:57个 - 新逻辑上传:18个 - 空记录:2个
190 lines
4.7 KiB
Markdown
190 lines
4.7 KiB
Markdown
# 任务-详情老素材迁移指南
|
||
|
||
## 概述
|
||
|
||
本脚本用于将"任务-详情"老素材(只有S3预览图)迁移到新逻辑(本地zip文件)。
|
||
|
||
## 安全措施
|
||
|
||
1. **保留老数据**:不删除原有的资产记录,只新增记录
|
||
2. **分批迁移**:每次处理5个素材,避免一次性迁移导致问题
|
||
3. **演练模式**:可以先运行演练模式,不实际修改数据库
|
||
4. **完整日志**:记录每个素材的迁移状态和错误信息
|
||
5. **错误处理**:单个素材失败不影响其他素材
|
||
|
||
## 使用步骤
|
||
|
||
### 1. 数据库备份(必须!)
|
||
|
||
```bash
|
||
# 在生产服务器上备份数据库
|
||
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. 演练模式测试
|
||
|
||
```bash
|
||
# 修改脚本配置
|
||
# CONFIG.dryRun = true
|
||
# CONFIG.batchSize = 2
|
||
|
||
# 运行演练
|
||
npx tsx scripts/migrate-product-package-old-materials.ts
|
||
```
|
||
|
||
### 3. 小批量测试
|
||
|
||
```bash
|
||
# 修改脚本配置
|
||
# CONFIG.dryRun = false
|
||
# CONFIG.batchSize = 2
|
||
|
||
# 迁移2个素材
|
||
npx tsx scripts/migrate-product-package-old-materials.ts
|
||
```
|
||
|
||
### 4. 验证测试结果
|
||
|
||
- 检查首页预览图是否正常显示
|
||
- 测试下载功能是否正常
|
||
- 检查详情页是否正常
|
||
- 检查外部接口是否正常
|
||
|
||
### 5. 批量迁移
|
||
|
||
```bash
|
||
# 修改脚本配置
|
||
# CONFIG.batchSize = 10
|
||
|
||
# 多次运行,每次迁移10个
|
||
npx tsx scripts/migrate-product-package-old-materials.ts
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
```typescript
|
||
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' (本地文件,保留)
|
||
```
|
||
|
||
## 回滚方案
|
||
|
||
如果迁移后发现问题,可以执行回滚:
|
||
|
||
```sql
|
||
-- 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: 不会,老数据会被保留,只是新增了新的记录。
|
||
|
||
## 联系方式
|
||
|
||
如有问题,请联系开发团队。
|