s3-migrate/README.md

S3 数据迁移工具

一个简单高效的 S3 对象存储迁移工具，支持在不同 S3 兼容存储服务之间迁移数据。

功能特性

• 智能对比：通过 ETag 对比文件差异，避免重复传输
• 断点续传：支持中断后继续迁移，已存在的文件会自动跳过
• 增量同步：只迁移变化或新增的文件
• 详细日志：清晰的进度显示和结果统计

支持的存储服务

• Amazon S3
• MinIO
• 阿里云 OSS
• 腾讯云 COS
• 火山引擎 TOS
• 其他 S3 兼容的存储服务

环境配置

创建 .env 文件，配置源存储和目标存储信息：

# 源存储配置（旧 S3）
O_S3_ACCESS_KEY_ID=your_access_key
O_S3_SECRET_ACCESS_KEY=your_secret_key
O_S3_REGION=us-east-1
O_S3_BUCKET_NAME=source-bucket
O_S3_ENDPOINT=http://localhost:9000

# 目标存储配置（新 S3）
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_REGION=cn-shanghai
S3_BUCKET_NAME=destination-bucket
S3_ENDPOINT=https://tos-s3-cn-shanghai.volces.com

参考 .env.example 文件获取完整配置示例。

注意事项

MinIO 用户：如果使用 MinIO 作为源存储，需要在代码中设置 forcePathStyle: true。默认配置已包含此设置，无需修改。

const oldS3Client = new S3Client({
  // ...
  forcePathStyle: true,  // MinIO 必需
});

安装

# 安装依赖
pnpm install

使用方法

# 运行迁移
pnpm migrate

运行逻辑

对于每个文件，迁移脚本会执行以下操作：

状态	操作
目标不存在	复制文件（新增）
目标存在，ETag 不同	更新文件
目标存在，ETag 相同	跳过

输出示例

Starting S3 migration...
Source: http://kevisual.cn:9000/resources
Destination: https://tos-s3-cn-shanghai.volces.com/envision

Found 10 objects in source bucket
Copying: images/photo1.jpg
✓ Copied: images/photo1.jpg
- Skip (same ETag): images/photo2.jpg
Updating (ETag changed): documents/report.pdf
  Source ETag: abc123def456
  Dest ETag:   789xyz012abc
✓ Copied: documents/report.pdf

Migration complete!
Total objects: 10
Copied (new): 2
Updated (ETag changed): 1
Skipped (same): 7
Errors: 0

技术栈

• TypeScript - 类型安全
• AWS SDK v3 - S3 客户端
• dotenv - 环境变量管理

License

ISC