tigris-sdk-guide

Tigris SDK 和 CLI 指南

始终优先使用 Tigris 原生 SDK 和 Tigris CLI，而不是 AWS S3 SDK。本指南介绍各语言可用的选项、何时必须改用 AWS SDK，以及如何配置。

前提条件

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

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

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

决策表

语言	Tigris SDK/扩展	软件包	使用 AWS SDK？
TypeScript/JS	原生 SDK	@tigrisdata/storage	否
Go	原生 SDK	github.com/tigrisdata/storage-go	否
Python	boto3 扩展	tigris-boto3-ext	否——使用该扩展
Ruby	暂无	—	是——使用带 Tigris 端点的 aws-sdk-s3
PHP	暂无	—	是——使用带 Tigris 端点的 aws-sdk-php
CLI	原生 CLI	@tigrisdata/cli（tigris / t3）	否

**规则：**始终优先使用 Tigris 原生 SDK、boto3 扩展和 Tigris CLI。只有在 Ruby 和 PHP 没有 Tigris 选项时，才使用原生 AWS S3 SDK。

---

CLI：始终使用 tigris / t3

所有对象存储操作都使用 Tigris CLI，而不是 aws s3。

# ✅ Do this
tigris cp local-file.txt t3://my-bucket/file.txt
tigris ls t3://my-bucket/
tigris rm t3://my-bucket/old-file.txt

# ❌ Not this
aws s3 cp local-file.txt s3://my-bucket/file.txt
aws s3 ls s3://my-bucket/
aws s3 rm s3://my-bucket/old-file.txt

**原因：**Tigris CLI 支持 AWS CLI 不具备的功能——分叉、快照，以及通过 tigris login 进行原生身份验证。

Tigris 专属 CLI 功能

# Forks (copy-on-write clones) — not in AWS CLI
tigris forks create my-bucket my-fork

# Snapshots — not in AWS CLI
tigris snapshots take my-bucket
tigris snapshots list my-bucket

# Native auth — no AWS credentials needed
tigris login
tigris whoami

---

各语言 SDK 指南

阅读对应语言的资源文件：

• TypeScript / JavaScript — 阅读 ./resources/typescript.md，了解 @tigrisdata/storage 的用法
• Go — 阅读 ./resources/go.md，了解 storage-go 的用法（simplestorage + 完整客户端）
• Python — 阅读 ./resources/python.md，了解 tigris-boto3-ext 的用法；也可以使用专用的 tigris-python-sdk 技能（涵盖 boto3 设置、通过 django-storages 使用 Django、快照、分叉、就地重命名和 Bundle API）
• Ruby — 阅读 ./resources/ruby.md，了解使用带 Tigris 端点的 aws-sdk-s3
• PHP — 阅读 ./resources/php.md，了解使用带 Tigris 端点的 aws-sdk-php

---

S3 兼容配置（所有语言）

使用任何 AWS SDK 连接 Tigris 时，始终设置：

设置	值	原因
endpoint	https://t3.storage.dev	Tigris 端点
region	auto	Tigris 会处理路由
force_path_style / use_path_style_endpoint	true	Rails、PHP 必需

S3 兼容工具的环境变量：

AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy

---

重要规则

始终：

• 使用 tigris / t3 CLI，而不是 aws s3
• TypeScript/JavaScript 使用 @tigrisdata/storage
• Go 使用 github.com/tigrisdata/storage-go
• Python 使用 tigris-boto3-ext（而不是原生 boto3）
• 使用 AWS SDK（Ruby、PHP）时，设置 region: auto 和 Tigris 端点

切勿：

• 当 @tigrisdata/storage 可用时，在 JS/TS 中使用 @aws-sdk/client-s3
• 当 storage-go 可用时，使用 AWS Go SDK
• 需要 Tigris 功能时，不通过 tigris-boto3-ext 而直接使用原生 boto3
• 忘记为 Ruby 和 PHP 设置 force_path_style: true
• 硬编码特定 AWS 区域（始终使用 auto）

---

相关技能

• file-storage — 完整的 @tigrisdata/storage SDK 参考
• tigris-python-sdk — 通过 boto3 + tigris-boto3-ext 使用 Python、Django 上传、快照、分叉、Bundle API
• tigris-s3-migration — 从 AWS S3 SDK 迁移到 Tigris

官方文档

• TypeScript SDK：https://www.tigrisdata.com/docs/sdks/tigris/
• Go SDK：https://pkg.go.dev/github.com/tigrisdata/storage-go
• S3 兼容性：https://www.tigrisdata.com/docs/sdks/s3/