Back to Details

tigris-s3-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate to Tigris from S3/GCS/Azure

从S3/GCS/Azure迁移至Tigris

Migrate your object storage to Tigris with zero downtime. Tigris is S3-compatible, so most apps need only an endpoint and credential swap. Shadow buckets enable transparent migration without moving data upfront.
您可以零停机将对象存储迁移至Tigris。Tigris兼容S3协议，因此大多数应用仅需切换端点和凭证即可完成迁移。影子存储桶功能支持无需预先迁移数据的透明迁移方式。

Prerequisites

前提条件

Before doing anything else, install the Tigris CLI if it's not already available:
bash
tigris help || npm install -g @tigrisdata/cli
If you need to install it, tell the user: "I'm installing the Tigris CLI (
@tigrisdata/cli
) so we can work with Tigris object storage."
在进行任何操作之前，如果尚未安装Tigris CLI，请先安装：
bash
tigris help || npm install -g @tigrisdata/cli
如果需要安装，请告知用户：“我正在安装Tigris CLI（
@tigrisdata/cli
），以便我们可以操作Tigris对象存储。”

Migration Strategies

迁移策略

StrategyDowntimeBest For
Shadow bucketZeroProduction apps — Tigris reads from S3 on miss, backfills automatically
Bulk copyBriefSmall datasets, clean cutover
Incremental syncZeroLarge datasets, gradual migration
策略停机时间适用场景
影子存储桶零生产环境应用——当Tigris中不存在请求的对象时，会从S3读取并自动回填数据
批量复制短暂小型数据集、需要完全切换的场景
增量同步零大型数据集、逐步迁移的场景

Shadow Bucket (Recommended)

影子存储桶（推荐）

Tigris reads from your existing S3 bucket on cache miss and gradually backfills data. No upfront data movement needed.
bash
undefined
当缓存未命中时，Tigris会从您现有的S3存储桶读取数据，并逐步回填至自身存储中，无需预先迁移数据。
bash
undefined

Create a Tigris bucket that shadows your S3 bucket

创建一个影子存储桶，关联您的S3存储桶

tigris buckets create my-app-uploads
--shadow-source s3://my-existing-s3-bucket
--shadow-region us-east-1
--shadow-access-key AKIA_YOUR_AWS_KEY
--shadow-secret-key YOUR_AWS_SECRET

**How it works:**

1. Requests go to Tigris
2. If the object exists in Tigris, it's served directly
3. If not, Tigris fetches it from S3, serves it, and caches it
4. Over time, all frequently accessed objects migrate automatically
5. Background backfill copies remaining objects

**After migration completes:**

```bash
tigris buckets create my-app-uploads
--shadow-source s3://my-existing-s3-bucket
--shadow-region us-east-1
--shadow-access-key AKIA_YOUR_AWS_KEY
--shadow-secret-key YOUR_AWS_SECRET

**工作原理：**

1. 请求发送至Tigris
2. 如果对象已存在于Tigris中，则直接返回
3. 如果不存在，Tigris会从S3获取该对象，返回给请求方并缓存至自身存储
4. 随着时间推移，所有频繁访问的对象会自动完成迁移
5. 后台回填任务会复制剩余的对象

**迁移完成后：**

```bash

Verify object counts match

验证对象数量是否匹配

tigris ls t3://my-app-uploads --recursive | wc -l aws s3 ls s3://my-existing-s3-bucket --recursive | wc -l
tigris ls t3://my-app-uploads --recursive | wc -l aws s3 ls s3://my-existing-s3-bucket --recursive | wc -l

Remove shadow source (makes Tigris the sole source)

移除影子源（使Tigris成为唯一数据源）

tigris buckets update my-app-uploads --remove-shadow

---
tigris buckets update my-app-uploads --remove-shadow

---

Bulk Copy

批量复制

For smaller datasets or when you want a clean cutover:
bash
undefined
适用于小型数据集或需要完全切换的场景：
bash
undefined

Copy all objects from S3 to Tigris

将所有对象从S3复制到Tigris

tigris cp s3://my-existing-bucket t3://my-app-uploads -r
tigris cp s3://my-existing-bucket t3://my-app-uploads -r

Or use AWS CLI pointed at Tigris

或者使用指向Tigris的AWS CLI

AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy
aws s3 sync s3://my-existing-bucket s3://my-app-uploads
undefined
AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy
aws s3 sync s3://my-existing-bucket s3://my-app-uploads
undefined

From Google Cloud Storage

从Google Cloud Storage迁移

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

From Azure Blob Storage

从Azure Blob Storage迁移

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

SDK Code Changes

SDK代码变更

Read the resource file for your language to see before/after migration examples:
  • Node.js / TypeScript — Read 
    ./resources/sdk-nodejs.md
    for AWS SDK → Tigris SDK migration
  • Go — Read 
    ./resources/sdk-go.md
    for AWS SDK → Tigris SDK migration
  • Python — Read 
    ./resources/sdk-python.md
    for boto3 → tigris-boto3-ext migration
  • Ruby — Read 
    ./resources/sdk-ruby.md
    for aws-sdk-s3 endpoint swap
  • PHP — Read 
    ./resources/sdk-php.md
    for aws-sdk-php endpoint swap
阅读对应语言的资源文件，查看迁移前后的示例：
  • 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的迁移方法
  • Ruby — 阅读
    ./resources/sdk-ruby.md
    了解aws-sdk-s3的端点切换方法
  • PHP — 阅读
    ./resources/sdk-php.md
    了解aws-sdk-php的端点切换方法

Environment Variable Changes

环境变量变更

bash
undefined
bash
undefined

Before (AWS)

迁移前（AWS）

AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-east-1 S3_BUCKET=my-bucket
AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-east-1 S3_BUCKET=my-bucket

After (Tigris)

迁移后（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

For frameworks with specific Tigris env vars:

```bash
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
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 # 存储桶名称可以保持不变

对于支持特定Tigris环境变量的框架：

```bash
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

Verification Checklist

验证清单

  • Object count matches between source and Tigris
  • Spot-check files: download a few and verify content/checksums
  • Test presigned URL generation (endpoint must point to Tigris)
  • Test CORS if using browser uploads (reconfigure on Tigris bucket)
  • Test all upload/download code paths in staging
  • Update CDN origin if using CloudFront/similar (point to Tigris)
  • Update DNS if using custom domains
  • 源存储与Tigris中的对象数量一致
  • 抽样检查文件：下载部分文件并验证内容/校验和
  • 测试预签名URL生成（端点必须指向Tigris）
  • 如果使用浏览器上传，测试CORS配置（需在Tigris存储桶上重新配置）
  • 在 staging 环境测试所有上传/下载代码路径
  • 如果使用CloudFront等CDN，更新CDN源（指向Tigris）
  • 如果使用自定义域名，更新DNS配置

Rollback Strategy

回滚策略

  1. Keep source bucket read-only during migration (don't delete data)
  2. Run both systems in parallel during verification
  3. Only delete source data after confirming Tigris works fully
  4. If using shadow bucket, removing the shadow source is the point of no return
  1. 迁移期间保持源存储桶为只读状态（不要删除数据）
  2. 验证阶段同时运行两个系统
  3. 仅在确认Tigris完全正常工作后，再删除源存储中的数据
  4. 如果使用影子存储桶，移除影子源后将无法回滚

Common Mistakes

常见错误

MistakeFix
Forgot to update presigned URL endpointPresigned URLs must use Tigris endpoint, not S3
CORS not configured on TigrisRe-create CORS rules: 
tigris buckets cors set
Region hardcoded to 
us-east-1
Use 
auto
for Tigris
path_style
not set		Add 
force_path_style: true
(Ruby/Rails) or 
use_path_style_endpoint: true
(PHP)
Custom domain DNS still points to S3Update CNAME to point to Tigris
错误修复方案
忘记更新预签名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

Related Skills

相关技能

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

Official Documentation

官方文档