Lib.rs

ssstar

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

ssstar 提供了一个跨平台的 Rust 驱动的 CLI 以及一个 Rust 库包，让您能够创建包含 S3 和 S3 兼容对象存储中的对象的 tar 归档，无论大小如何。 ssstar 采用了积极的并发性，并使用流式设计，这意味着即使是多 TB 的对象也可以以最小的内存利用进行处理。生成的 tar 归档可以上传到对象存储，写入本地文件，或写入 stdout 并通过管道传输到另一个命令行工具。

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

安装

Cargo

在任何支持的平台上（这意味着 Windows、macOS（Intel 和 Apple Silicon）和 Linux），如果您安装了最新的 Rust 编译器，您可以使用 cargo install 来获取 ssstar CLI

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

预编译的二进制文件

请参阅GitHub发布以获取适用于Windows、mac和Linux的预编译二进制文件。

使用方法（不使用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，然后通过将elastio stream restore管道传输到具有--stdin选项的ssstar extract来恢复它们。例如

# 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 --help和ssstar 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 项目中）

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

[dependencies]
ssstar = "0.7.3"

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

许可证

以下两种许可证中的任何一种

• Apache License，版本 2.0 (LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确说明，否则根据 Apache-2.0 许可证定义，您有意提交的任何贡献，均应按上述方式双许可，而不附加任何额外条款或条件。

请参阅 CONTRIBUTING.md。