WuYongJie/gongxiangp2

Fork 0

chenpei 2b7cd7f654 源码还原完成，清理项目结构，更新steering规范

2025-12-27 19:03:41 +08:00

8.4 KiB

Raw Blame History

S3素材无感迁移指南

📋 概述

本迁移方案用于将老素材的S3文件迁移到新位置（统一使用路径前缀），实现存储路径的统一管理。

核心原则：

✅ 所有素材、人员信息、元数据都不能动
✅ 无感迁移，用户无感知
✅ 支持断点续传和错误重试
✅ 迁移后验证所有功能正常

🔍 迁移范围

需要迁移的S3字段

字段	说明	示例
`previewUrl`	预览图URL	`https://s3.1080p.hk/jsxiangche/preview-xxx.webp`
`zipFileName`	音频/视频源文件URL	`https://s3.1080p.hk/jsxiangche/audio-xxx.mp3`
`displayImages`	详情图数组	`["https://s3.1080p.hk/jsxiangche/img1.jpg", ...]`
`videoSourceUrl`	视频源文件URL	`https://s3.1080p.hk/jsxiangche/video-xxx.mp4`
`videoPreview540Url`	540P预览视频URL	`https://s3.1080p.hk/jsxiangche/preview-540p.mp4`
`videoPreviewClipUrl`	视频片段URL	`https://s3.1080p.hk/jsxiangche/clip-xxx.mp4`
`videoCoverUrl`	视频封面URL	`https://s3.1080p.hk/jsxiangche/cover-xxx.jpg`

不需要迁移的内容

✅ 本地源文件（./uploads 目录）- 不需要迁移
- 压缩包文件：存储在 ./uploads 目录（zipFilePath 字段）
- 新老素材都使用同一目录，无需迁移
✅ 外网服务器源文件（103.118.245.6）- 不需要迁移
- 部分老素材的源文件存储在外网服务器（通过FRP穿透访问）
- zipFilePath 字段可能包含 103.118.245.6 或 http:// 开头的URL
- 这些文件保持原样，不进行迁移
✅ 数据库中的其他字段（人员信息、元数据等）- 保持不变
✅ 已使用新路径的素材 - 跳过

📌 重要说明：源文件存储位置

系统中的源文件（压缩包/视频）存储在不同位置：

存储位置	说明	字段	是否需要迁移
本地文件系统	`./uploads` 目录（Docker挂载）	`zipFilePath`	❌ 不需要
外网服务器	103.118.245.6（老素材，通过FRP访问）	`zipFilePath`	❌ 不需要
S3存储	音频/视频源文件（S3 URL）	`zipFileName`	✅ 需要迁移

注意：

zipFileName 字段可能是：
- 本地文件名（如 material-xxx.zip）- 不需要迁移
- S3 URL（如 https://s3.1080p.hk/jsxiangche/audio-xxx.mp3）- 需要迁移
迁移脚本会自动识别 zipFileName 是否为S3 URL，只迁移S3中的文件

🔗 FRP穿透说明

系统中存在多个FRP穿透，用于不同的服务：

穿透类型	用途	外网地址	FRP服务器	本地服务	说明
S3存储穿透1	MinIO S3服务（老）	`s3.1080p.hk` (156.233.232.106)	180.97.221.140	192.168.58.20:9000/9001	用于老S3预览图、视频转码文件等
S3存储穿透2	MinIO S3服务（新）	`s3.yydd.ai` (103.118.245.6)	未知（同源文件穿透）	未知	用于新S3预览图、视频转码文件等
源文件穿透	老素材源文件	`103.118.245.6`	未知	外网服务器目录	用于老素材的压缩包/视频文件下载

重要发现（2025-12-22测试）：

✅ s3.yydd.ai 也使用FRP穿透：DNS解析到 103.118.245.6，访问该IP返回 "The server is powered by frp"
✅ s3.yydd.ai 和源文件穿透使用同一个FRP服务器：都是 103.118.245.6
⚠️ 两个S3域名都有穿透问题：s3.1080p.hk 和 s3.yydd.ai 都通过FRP穿透，都会受到带宽限制

重要说明：

S3存储穿透：所有S3中的文件（预览图、视频转码文件、音频/视频源文件）都通过FRP穿透访问
源文件穿透：仅用于部分老素材的源文件下载，新素材源文件存储在本地，不需要穿透
性能影响：由于都使用FRP穿透，大文件加载会较慢（首字节时间可能>10秒）
迁移脚本只处理S3存储中的文件，不涉及源文件穿透

🎯 迁移目标

老素材URL格式：

https://s3.1080p.hk/jsxiangche/preview-xxx.webp

新素材URL格式（迁移后）：

https://s3.1080p.hk/jsxiangche/由壹点AI/preview-xxx.webp

📝 迁移前准备

1. 备份数据库

# 使用 pg_dump 备份
pg_dump -h localhost -U postgres -d lobechat > backup_$(date +%Y%m%d_%H%M%S).sql

2. 检查环境变量

确保 .env.local 文件包含以下变量：

S3_ENDPOINT=https://s3.yydd.ai
S3_BUCKET=gongxiangpan
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_PUBLIC_DOMAIN=https://s3.yydd.ai/gongxiangpan
S3_FILE_PATH=由壹点AI/
DATABASE_URL=postgresql://user:password@localhost:5432/lobechat

3. 安装依赖

npm install
npx prisma generate

🚀 执行迁移

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

# 干运行模式（只检查，不实际迁移）
.\scripts\run-migration.ps1 -DryRun

# 执行迁移
.\scripts\run-migration.ps1

方式二：直接运行TypeScript脚本

# 需要先安装 tsx
npm install -g tsx

# 执行迁移
npx tsx scripts/migrate-s3-materials.ts

📊 迁移过程

1. 查询需要迁移的素材

脚本会自动查询所有包含老S3 URL的素材：

只迁移未删除的素材（deletedAt IS NULL）
自动识别需要迁移的字段

2. 迁移文件

对于每个需要迁移的文件：

从老位置下载文件
上传到新位置（带路径前缀）
验证新文件可访问
更新数据库中的URL

3. 断点续传

如果新文件已存在，自动跳过（支持断点续传）
每10个素材保存一次日志（防止中断丢失）

4. 错误处理

自动重试（最多10次）
记录失败详情到日志文件
失败的文件不影响其他文件的迁移

📁 迁移日志

迁移日志保存在 logs/migration/ 目录，文件名格式：

migration-{timestamp}.json

日志格式：

[
  {
    "materialId": "uuid",
    "field": "previewUrl",
    "oldUrl": "https://s3.1080p.hk/jsxiangche/preview-xxx.webp",
    "newUrl": "https://s3.1080p.hk/jsxiangche/由壹点AI/preview-xxx.webp",
    "status": "success",
    "timestamp": "2025-01-20T10:00:00.000Z"
  }
]

✅ 迁移后验证

1. 检查迁移统计

迁移完成后会显示统计信息：

总计：需要迁移的文件数
成功：成功迁移的文件数
跳过：已存在的文件数
失败：迁移失败的文件数

2. 验证素材显示

随机抽查几个素材：

预览图是否正常显示
详情图是否正常显示
视频预览是否正常播放
音频文件是否正常播放

3. 验证下载功能

测试几个素材的下载功能：

压缩包下载是否正常
视频文件下载是否正常
音频文件下载是否正常

4. 检查数据库

-- 检查是否还有老URL
SELECT COUNT(*) FROM materials
WHERE deletedAt IS NULL
AND (
  previewUrl LIKE '%s3.1080p.hk/jsxiangche/%'
  AND previewUrl NOT LIKE '%由壹点AI/%'
);

🔄 回滚方案

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

1. 恢复数据库备份

psql -h localhost -U postgres -d lobechat < backup_20250120_100000.sql

2. 删除新位置的文件（可选）

如果需要清理新位置的文件，可以使用S3管理工具或API删除。

⚠️ 注意事项

迁移时间：建议在低峰期执行迁移，避免影响用户使用
网络稳定性：确保网络连接稳定，避免迁移中断
存储空间：确保S3有足够的存储空间（迁移会临时占用双倍空间）
监控：迁移过程中监控系统资源使用情况
验证：迁移后务必验证所有功能正常

🐛 常见问题

Q: 迁移失败怎么办？

A: 检查日志文件，找到失败的原因。常见原因：

网络连接问题
S3权限问题
文件不存在

Q: 可以分批迁移吗？

A: 可以。脚本支持断点续传，可以随时中断和恢复。

Q: 迁移会影响系统使用吗？

A: 不会。迁移过程中系统可正常使用（只读模式），迁移是后台进行的。

Q: 迁移后老文件会删除吗？

A: 不会。迁移脚本只复制文件到新位置，不删除老文件。如果需要清理，可以手动删除。

📞 技术支持

如有问题，请：

查看迁移日志文件
检查错误信息
联系技术支持

8.4 KiB Raw Blame History Unescape Escape