tigris-s3-migration

从 S3/GCS/Azure 迁移到 Tigris

零停机将对象存储迁移到 Tigris。Tigris 兼容 S3，因此大多数应用只需替换端点和凭据。影子存储桶可实现透明迁移，无需预先移动数据。

前提条件

在进行任何其他操作之前，如果尚未安装 Tigris CLI，请先安装：

tigris help || npm install -g @tigrisdata/cli

如果需要安装，请告诉用户：“我正在安装 Tigris CLI（@tigrisdata/cli），以便使用 Tigris 对象存储。”

迁移策略

策略	停机时间	适用场景
影子存储桶	零	生产应用 — 缓存未命中时，Tigris 从 S3 读取并自动回填
批量复制	短暂	小型数据集、干净切换
增量同步	零	大型数据集、渐进式迁移

---

影子存储桶（推荐）

缓存未命中时，Tigris 会从现有 S3 存储桶读取数据，并逐步回填。无需预先移动数据。

# Create a Tigris bucket
tigris buckets create my-app-uploads
# Point the Tigris bucket at the source S3 bucket
tigris buckets set-migration my-app-uploads \
  --bucket my-existing-s3-bucket \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --region us-east-1 \
  --access-key AKIA_YOUR_AWS_KEY \
  --secret-key YOUR_AWS_SECRET

添加 --write-through，还可以将新写入同步回源存储桶——如果你希望在迁移窗口期间保留安全的回滚路径，这会很有用。

工作原理：

1. 请求发送到 Tigris
2. 如果对象存在于 Tigris 中，则直接提供
3. 如果不存在，Tigris 会从 S3 获取对象、提供该对象并将其缓存

预先迁移所有数据（可选）：

惰性迁移只会在对象被请求时复制它们。如需在服务器端主动迁移所有剩余对象，请运行：

# Migrate every unmigrated object in the bucket
tigris buckets migrate my-app-uploads

# Or scope to a key prefix
tigris buckets migrate my-app-uploads/images/

该命令会在前台运行并持续报告进度，因此你可以在切换前彻底迁空源存储。

迁移完成后：

# Disable migration (makes Tigris the sole source)
tigris buckets set-migration my-app-uploads --disable

---

批量复制

适用于较小的数据集，或需要干净切换的情况：

从 Google Cloud Storage 迁移

gsutil -m cp -r gs://my-gcs-bucket /tmp/migration/
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

从 Azure Blob Storage 迁移

az storage blob download-batch -d /tmp/migration/ -s my-container
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

---

SDK 代码变更

阅读对应语言的资源文件，查看迁移前后的示例：

• Node.js / TypeScript — 阅读 ./resources/sdk-nodejs.md，了解从 AWS SDK 迁移到 Tigris SDK
• Go — 阅读 ./resources/sdk-go.md，了解从 AWS SDK 迁移到 Tigris SDK
• Python — 阅读 ./resources/sdk-python.md，了解从 boto3 迁移到 tigris-boto3-ext；或者使用 tigris-python-sdk 技能，了解迁移后的开发体验（Django、快照、分支、Bundle API）
• Ruby — 阅读 ./resources/sdk-ruby.md，了解 aws-sdk-s3 端点替换
• PHP — 阅读 ./resources/sdk-php.md，了解 aws-sdk-php 端点替换

---

环境变量变更

# Before (AWS)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
S3_BUCKET=my-bucket

# After (Tigris)
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy
AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
S3_BUCKET=my-bucket  # bucket name can stay the same

对于使用 Tigris 特定环境变量的框架：

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy
TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev
TIGRIS_STORAGE_BUCKET=my-bucket

---

验证清单

• 确认源存储和 Tigris 中的对象数量一致
• 抽查文件：下载若干文件并验证内容/校验和
• 测试预签名 URL 生成（端点必须指向 Tigris）
• 如果使用浏览器上传，请测试 CORS（在 Tigris 存储桶上重新配置）
• 在预发布环境中测试所有上传/下载代码路径
• 如果使用 CloudFront 或类似服务，请更新 CDN 源站（指向 Tigris）
• 如果使用自定义域名，请更新 DNS

---

回滚策略

1. 迁移期间将源存储桶设为只读（不要删除数据）
2. 验证期间让两个系统并行运行
3. 只有在确认 Tigris 完全正常后，才删除源数据
4. 如果使用影子存储桶，移除影子源即为不可逆操作

---

常见错误

错误	修复方法
忘记更新预签名 URL 端点	预签名 URL 必须使用 Tigris 端点，而不是 S3
未在 Tigris 上配置 CORS	重新创建 CORS 规则：tigris buckets cors set
将区域硬编码为 us-east-1	Tigris 应使用 auto
未设置 path_style	添加 force_path_style: true（Ruby/Rails）或 use_path_style_endpoint: true（PHP）
自定义域名 DNS 仍指向 S3	更新 CNAME，使其指向 Tigris

---

相关技能

• file-storage — CLI 设置和 SDK 参考
• tigris-security-access-control — CORS 和访问密钥设置

官方文档

• S3 兼容性：https://www.tigrisdata.com/docs/sdks/s3/
• Shadow Buckets 和迁移：https://www.tigrisdata.com/docs/migration/
• CLI：tigris buckets set-migration — https://www.tigrisdata.com/docs/cli/buckets/set-migration
• CLI：tigris buckets migrate — https://www.tigrisdata.com/docs/cli/buckets/migrate