tigris-snapshots-recovery

Tigris 快照与时间点恢复

恢复任意时间点删除或更改的文件。启用了快照的 Tigris 存储桶会自动跟踪每次更改 — 无需事先创建快照即可恢复文件。

前置条件

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

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

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

关键信息

• 必须在创建存储桶时启用快照。 无法在现有存储桶上启用快照。你必须创建一个启用了快照的新存储桶。
• 每次更改都会自动跟踪。 即使没有显式创建快照，每次写入、删除和覆盖都会得到保留。你可以恢复任意时间点的任何对象。
• 显式快照是可选的书签。 创建命名快照只是标记一个时间点，方便查找。无论如何，数据都会得到保留。
• 快照存储桶必须使用 STANDARD 存储层级。 启用了快照的存储桶不支持生命周期转换和 TTL。

---

创建启用了快照的存储桶

# New bucket with snapshots enabled
tigris buckets create my-bucket --snapshot

# ⚠ This will NOT work — cannot enable snapshots on existing bucket
# tigris buckets update my-bucket --snapshot  ← NOT SUPPORTED

import { createBucket } from "@tigrisdata/storage";

const result = await createBucket("my-bucket", {
  enableSnapshot: true,
});

迁移现有存储桶

如果需要在现有存储桶上使用快照，请创建一个新存储桶并复制数据：

tigris buckets create my-bucket-v2 --snapshot
tigris cp t3://my-bucket/ t3://my-bucket-v2/ -r
# Update your app to use the new bucket name
tigris buckets delete my-bucket  # when ready

---

自动跟踪的工作原理

启用快照后，Tigris 会保留每个对象的所有版本：

Timeline:
  T1: put("config.json", v1)        → v1 stored
  T2: put("config.json", v2)        → v2 stored, v1 still accessible
  T3: remove("config.json")         → deleted, but v1 and v2 still accessible
  T4: put("config.json", v3)        → v3 stored, v1, v2, and deletion all accessible

---

从快照恢复

典型的恢复工作流：列出快照，选择一个，然后从中恢复文件。

import { listBucketSnapshots, get, put } from "@tigrisdata/storage";

// 1. List snapshots
const result = await listBucketSnapshots("my-bucket");

// 2. Find the right one
const target = result.data?.find((s) => s.name === "before-deploy-v2.3");
const snapshotVersion = target!.version;

// 3. Read a file at that snapshot and write it back
const old = await get("config.json", "string", { snapshotVersion });
if (!old.error) {
  await put("config.json", old.data, { contentType: "application/json" });
}

如需完整工作流，包括完整存储桶恢复、前缀恢复、基于时间戳的恢复和快照比较，请阅读 ./resources/restore-workflows.md。

如需 Go SDK 示例，请阅读 ./resources/go-examples.md。

如需 Python（tigris-boto3-ext）示例，请阅读 ./resources/python-examples.md。如需完整的 Python 支持（boto3 设置、Django、Bundle API），请使用 tigris-python-sdk 技能。

---

创建显式快照（可选书签）

虽然每次更改都会自动跟踪，但命名快照可以方便地查找特定时间点：

tigris snapshots take my-bucket --name "before-deploy-v2.3"
tigris snapshots list my-bucket

import { createBucketSnapshot } from "@tigrisdata/storage";
await createBucketSnapshot("my-bucket", { name: "before-deploy-v2.3" });

适合创建显式快照的情况： 部署、迁移、批量数据操作或任何有风险的操作之前。

不需要显式快照的情况： 恢复单个文件时 — 只需使用时间戳。自动跟踪会涵盖日常更改。

---

重要规则

务必：

• 创建存储桶时启用快照 — 之后无法添加
• 为启用了快照的存储桶使用 STANDARD 存储层级
• 先在非生产存储桶上测试恢复
• 记住，任何纳秒级时间戳都可以作为快照版本

切勿：

• 认为可以在现有存储桶上启用快照（必须创建新存储桶）
• 仅依赖显式快照 — 由于自动跟踪，你可以从任意时间戳恢复
• 在启用了快照的存储桶上使用生命周期规则或 TTL（不受支持）
• 恢复多个文件时忘记分页

---

已知问题

问题	解决方法
出现“Snapshots not enabled”错误	创建存储桶时未使用 --snapshot / enableSnapshot: true。请创建新存储桶并复制数据。
找不到正确的时间戳	在有风险的操作之前创建显式命名快照，以便于查找
恢复多个文件时速度很慢	使用并发限制分批恢复；如需恢复整个存储桶，可考虑改用分叉
快照存储桶无法转换存储层级	快照存储桶必须使用 STANDARD 层级 — 不支持生命周期转换

---

相关技能

• tigris-snapshots-forking — 为开发沙箱和测试分叉存储桶
• file-storage — get、put、list 的 SDK 参考
• tigris-backup-export — 使用数据库转储的补充备份策略

官方文档

• 快照：https://www.tigrisdata.com/docs/buckets/snapshots-and-forks/