From b510d6667a478eb515ac9991639d57bcb677f597 Mon Sep 17 00:00:00 2001
From: abearxiong <xiongxiao@xiongxiao.me>
Date: Fri, 6 Feb 2026 19:48:34 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20S3=20=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E8=BF=81=E7=A7=BB=E5=B7=A5=E5=85=B7=E7=9A=84=20README=20?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E5=8C=85=E5=90=AB=E5=8A=9F=E8=83=BD?=
 =?UTF-8?q?=E7=89=B9=E6=80=A7=E3=80=81=E6=94=AF=E6=8C=81=E7=9A=84=E5=AD=98?=
 =?UTF-8?q?=E5=82=A8=E6=9C=8D=E5=8A=A1=E3=80=81=E7=8E=AF=E5=A2=83=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE=E3=80=81=E5=AE=89=E8=A3=85=E5=92=8C=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E6=96=B9=E6=B3=95=E7=AD=89=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2e369e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# S3 数据迁移工具
+
+一个简单高效的 S3 对象存储迁移工具，支持在不同 S3 兼容存储服务之间迁移数据。
+
+## 功能特性
+
+- **智能对比**：通过 ETag 对比文件差异，避免重复传输
+- **断点续传**：支持中断后继续迁移，已存在的文件会自动跳过
+- **增量同步**：只迁移变化或新增的文件
+- **详细日志**：清晰的进度显示和结果统计
+
+## 支持的存储服务
+
+- Amazon S3
+- MinIO
+- 阿里云 OSS
+- 腾讯云 COS
+- 火山引擎 TOS
+- 其他 S3 兼容的存储服务
+
+## 环境配置
+
+创建 `.env` 文件，配置源存储和目标存储信息：
+
+```bash
+# 源存储配置（旧 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`。默认配置已包含此设置，无需修改。
+
+```typescript
+const oldS3Client = new S3Client({
+  // ...
+  forcePathStyle: true,  // MinIO 必需
+});
+```
+
+## 安装
+
+```bash
+# 安装依赖
+pnpm install
+```
+
+## 使用方法
+
+```bash
+# 运行迁移
+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