tigris-bucket-management

Tigris 存储桶管理

前置条件

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

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

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

概述

存储桶是对象的容器。本技能涵盖存储桶的生命周期：创建、列出、检查和删除。

快速参考

操作	函数	关键参数
创建	createBucket(name, options)	name、access、region、enableSnapshot
列出	listBuckets(options)	limit、paginationToken
检查	getBucketInfo(name)	bucketName
删除	removeBucket(name, options)	bucketName、force

创建存储桶

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

// Simple private bucket
const result = await createBucket("my-new-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Created:", result.data);
}

// Public bucket (objects readable by anyone)
const result = await createBucket("public-assets", {
  access: "public",
});

// Snapshot-enabled bucket (for version control)
const result = await createBucket("my-snapshot-bucket", {
  enableSnapshot: true,
});

// Regional bucket
const result = await createBucket("eu-data", {
  region: "eu",
});

// Fork from existing bucket snapshot
const result = await createBucket("my-forked-bucket", {
  sourceBucketName: "parent-bucket",
  sourceBucketSnapshot: "1751631910169675092",
});

创建存储桶选项

选项	值	默认值	用途
access	public/private	private	对象可读性
consistency	default/strict	default	读取一致性级别
defaultTier	STANDARD/STANDARD_IA/GLACIER/GLACIER_IR	STANDARD	默认存储层级
enableSnapshot	boolean	false	启用快照/分叉
region	string	global	存储桶区域
sourceBucketName	string	-	从此存储桶分叉
sourceBucketSnapshot	string	-	从此快照分叉

**注意：**启用快照的存储桶必须使用 STANDARD 层级。

列出存储桶

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

// List all buckets
const result = await listBuckets();
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Buckets:", result.data?.buckets);
  console.log("Owner:", result.data?.owner);
}

// Paginated list
const allBuckets = [];
let currentPage = await listBuckets({ limit: 10 });
allBuckets.push(...currentPage.data?.buckets);

while (currentPage.data?.paginationToken) {
  currentPage = await listBuckets({
    limit: 10,
    paginationToken: currentPage.data?.paginationToken,
  });
  allBuckets.push(...currentPage.data?.buckets);
}

获取存储桶信息

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

const result = await getBucketInfo("my-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Info:", result.data);
  // {
  //   isSnapshotEnabled: true,
  //   hasForks: false,
  //   sourceBucketName: undefined,
  //   sourceBucketSnapshot: undefined
  // }
}

删除存储桶

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

// Delete empty bucket
const result = await removeBucket("my-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Deleted successfully");
}

// Force delete (even if not empty)
const result = await removeBucket("my-bucket", {
  force: true,
});

**警告：**强制删除不可撤销。所有对象都会丢失。

存储桶访问级别

级别	行为	使用场景
private	对象需要身份验证	默认设置，敏感数据
public	对象可公开读取	静态资源，公开内容

一致性级别

级别	行为	权衡
default	低延迟，最终一致性	大多数工作负载
strict	强一致性，延迟较高	关键数据

存储层级

层级	使用场景	成本
STANDARD	通用用途	标准
STANDARD_IA	不常访问	成本较低
GLACIER	长期归档	成本最低
GLACIER_IR	极少访问，快速检索	归档并支持偶尔访问

区域

指定区域以满足数据本地化或合规要求：

await createBucket("data-eu", { region: "eu" });
await createBucket("data-asia", { region: "asia-south-1" });

留空则使用全局存储桶（推荐用于大多数场景）。

常见错误

错误	修正
启用快照时使用了非 STANDARD 层级	快照要求使用 STANDARD 层级
删除前未检查存储桶是否存在	先使用 getBucketInfo
未强制删除非空存储桶	使用 force: true，或先清空存储桶
名称冲突	存储桶名称必须全局唯一

Forking and Snapshots

For version control (snapshots/forking), see the tigris-snapshots-forking skill.