#tar-archive #amazon-s3 #s3 #archive #tar #object-storage #helper

ssstar-testing

用于简化编写测试脚本的辅助库。不建议在 ssstar crate 之外使用。可能在不通知的情况下发生破坏性更改。

17 个不稳定版本 (6 个破坏性更改)

0.7.3 2024年3月12日
0.7.1 2023年11月20日
0.6.0 2023年7月19日
0.4.3 2023年3月3日
0.2.0 2022年9月2日

#1044文件系统

每月下载量 39
用于 ssstar

Apache-2.0 OR MIT

47KB
572

ssstar

ssstar 是一个 Rust 库 crate,也是一个命令行工具,用于创建和提取包含存储在 S3 或兼容 S3 存储中的对象的 tar 兼容归档。它类似于 GNU tar,生成的归档与 tar 完全兼容,尽管它使用不同的命令行参数。

Crates.io Docs.rs CI Coverage Status Crates.io

ssstar 提供了一个跨平台的 Rust 驱动的 CLI 以及一个 Rust 库 crate,允许您创建包含来自 S3 和兼容 S3 对象存储的对象的 tar 归档,无论大小如何。 ssstar 强烈应用并发性,并使用流式设计,这意味着即使多 TB 的对象也可以以最小的内存利用率进行处理。生成的 tar 归档可以上传到对象存储,写入本地文件,或写入 stdout 并管道到另一个命令行工具。

我们构建了 ssstar,以便我们的客户可以使用 elastio 云原生备份和恢复 CLI 将 S3 存储桶直接备份和恢复到 Elastio 保险库中,但我们使工具足够通用,可以在需要将一个或多个 S3 对象打包到 tar 包时单独使用。

安装

Cargo

在任何支持的平台上(意味着 Windows、macOS(英特尔和苹果硅)和 Linux),如果您已安装了最新的 Rust 编译器,您可以使用 cargo install 来获取 ssstar CLI

  • 确保您已安装至少 Rust 1.63.0,请按照 指南进行操作。
  • 运行 cargo install ssstar-cli --locked 从源代码编译 ssstar 并本地安装。

预编译的二进制文件

查看 Windows、mac 和 Linux 的预编译二进制文件的 GitHub 发布

用法(不带 Elastio)

要创建一个 tar 存档,您需要指定 S3 存储桶、对象、整个前缀或 glob,以及您希望 tar 存档写入的位置


# Archive an entire bucket and write the tar archive to another bucket
ssstar create \
  s3://my-source-bucket \
  --s3 s3://my-destination-bucket/backup.tar

# Archive all objects in the `foo/` prefix (non-recursive) and write the tar archive to a local file
ssstar create \
  s3://my-source-bucket/foo/ \
  --file ./backup.tar

# Archive some specific objects identified by name, and write the tar archive to stdout and pipe that to
# gzip
ssstar create \
  s3://my-source-bucket/object1 s3://my-source-bucket/object2 \
  --stdout | gzip > backup.tar.gz

# Archive all objects matching a glob, and write the tar archive to another bucket
ssstar create \
  "s3://my-source-bucket/foo/**" \
  --s3 s3://my-destination-bucket/backup.tar

您可以将多个输入传递给 ssstar create,使用整个存储桶、前缀、特定对象和 glob 的组合。只需确保当您使用 glob 时,将它们用引号括起来,否则您的 shell 可能会尝试评估它们。例如

# Archive a bunch of different inputs, writing the result to a file
ssstar create \
  s3://my-source-bucket/                  \ # <-- include all objects in `my-source-bucket`
  s3://my-other-bucket/foo/               \ # <-- include all objects in `foo/` (non-recursive)
  s3://my-other-bucket/bar/boo            \ # <-- include the object with key `bar/boo`
  "s3://yet-another-bucket/logs/2022*/**" \ # <-- recursively include all objects in any prefix `logs/2022*`
  --file ./backup.tar                     # <-- this is the path where the tar archive will be written

要提取 tar 存档并将内容直接写入 S3 对象,您需要指定 tar 存档的位置,可选的过滤器以过滤要提取的内容,以及要提取内容到的 S3 存储桶和前缀。

一个简单的示例

# Extract a local tar archive to the root of an S3 bucket `my-bucket`
ssstar extract --file ./backup.tar s3://my-bucket

tar 存档中的每个文件将被写入到存储桶 my-bucket,对象键等于存档中的文件路径。例如,如果存档包含一个文件 foo/bar/baz.txt,该文件将被写入到 s3://my-bucket/foo/bar/baz.txt

您可以提供目标存储桶,也可以提供前缀,例如

# Extract a local tar archive to the prefix `restored/` of an S3 bucket `my-bucket`
ssstar extract --file ./backup.tar s3://my-bucket/restored/

在这种情况下,如果 tar 存档包含一个文件 foo/bar/baz.txt,它将被写入到 s3://my-bucket/restored/foo/bar/baz.txt注意:在 S3 中,前缀不一定以 / 结尾;如果您没有将尾随的 / 字符提供给传递给 ssstar extract 的 S3 URL,则不会为您添加它!相反,您将得到类似于 s3://my-bucket/restoredfoo/bar/baz 的内容,这可能不是您真正想要的!

如果您不想提取存档的全部内容,可以指定一个或多个过滤器。这些可以是确切的文件路径、以 / 结尾的目录路径或 glob。例如

ssstar extract --file ./backup.tar \
  foo/bar/baz.txt          \ # <-- extract the file `foo/bar/baz.txt` if it's present in the archive
  boo/                     \ # <-- extract all files in the `boo` directory (recursive)
  "baz/**/*.txt"           \ # <-- extract any `.txt` file anywhere in `baz/`, recursively
  s3://my-bucket/restored/   # <-- write all matching files to the `restored/` prefix in `my-bucket`

用法(带 Elastio)

要使用 Elastio,请使用 --stdout 选项创建存档并将其传递给 elastio stream backup,并通过 ssstar extract--stdin 选项将 elastio stream restore 管道传递以恢复它们。例如

# Backup an entire S3 bucket `my-source-bucket` to the default Elastio vault:
ssstar create s3://my-source-bucket/ --stdout \
  | elastio stream backup --hostname-override my-source-bucket --stream-name my-backup
# Restore a recovery point with ID `$RP_ID` from Elastio to the `my-destination-bucket` bucket:
elastio stream restore --rp $RP_ID \
  | ssstar extract --stdin s3://my-destination-bucket

有关使用 Elastio CLI 的更多信息,请参阅 Elastio CLI 文档

高级 CLI 选项

运行 ssstar create --helpssstar extract --help 以获取创建和提取存档的完整 CLI 使用说明。有几个命令行选项可能特别有趣

使用自定义 S3 端点

ssstar 已开发和测试以兼容 AWS S3,但应该可以与任何提供 S3 兼容 API 的对象存储系统一起工作。特别是,我们 CI 系统运行的大多数自动化测试实际上使用的是 Minio 而不是真实的 S3 API。要使用与 S3 兼容的 API 的 ssstar,请使用 --s3-endpoint 选项。例如,如果您有一个运行在 127.0.7.1:30000 的 Minio 服务器,并使用默认的 minioadmin 凭据,则可以使用 ssstar 如下所示

ssstar --s3-endpoint http://127.0.0.1:30000 \
  --aws-access-key-id minioadmin --aws-secret-access-key minio-admin \
  ...

控制并发

--max-concurrent-requests 参数控制每个阶段(创建或提取存档过程)中将执行多少个并发的 S3 API 操作。默认值为 10,因为这是 AWS CLI 所使用的值。然而,如果您在具有连接到 S3 的多千兆位以太网连接的 EC2 实例上运行 ssstar,则 10 个并发请求可能不足以饱和网络连接。尝试更大的值以查看是否可以以更高的并发性体验到更快的传输时间。

使用(在 Rust 项目中)

库包 ssstarssstar CLI 的引擎。当我们编写 ssstar 时,我们故意将所有功能保留在一个库包中,并在其顶部有一个薄的 CLI 包装器,因为 ssstar 正在被内部用于 Elastio 以提供即将推出的 S3 备份功能。您也可以将 ssstar 功能集成到您的 Rust 应用程序中。只需将 ssstar 作为依赖项添加到您的 Cargo.toml

[dependencies]
ssstar = "0.7.3"

有关更多详细信息和一些示例,请参阅 docs.rs 上的 ssstar 文档。您还可以查看我们的 CLI 代码,该代码在 ssstar 库包中实现,请参阅 ssstar-cli/main.rs

许可

根据您的选择,许可为以下之一

贡献

除非您明确声明,否则任何有意提交给您的工作以供包含在内的贡献,如 Apache-2.0 许可证所述,应如上所述双许可,不附加任何其他条款或条件。

请参阅 CONTRIBUTING.md

依赖项

~35–50MB
~752K SLoC