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
47KB
572 行
ssstar
ssstar 是一个 Rust 库 crate,也是一个命令行工具,用于创建和提取包含存储在 S3 或兼容 S3 存储中的对象的 tar 兼容归档。它类似于 GNU tar,生成的归档与 tar 完全兼容,尽管它使用不同的命令行参数。
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 --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 应用程序中。只需将 ssstar
作为依赖项添加到您的 Cargo.toml
[dependencies]
ssstar = "0.7.3"
有关更多详细信息和一些示例,请参阅 docs.rs 上的 ssstar
文档。您还可以查看我们的 CLI 代码,该代码在 ssstar
库包中实现,请参阅 ssstar-cli/main.rs
。
许可
根据您的选择,许可为以下之一
- Apache License,版本 2.0(《LICENSE-APACHE》或 http://www.apache.org/licenses/LICENSE-2.0)
- MIT 许可(《LICENSE-MIT》或 http://opensource.org/licenses/MIT)
。
贡献
除非您明确声明,否则任何有意提交给您的工作以供包含在内的贡献,如 Apache-2.0 许可证所述,应如上所述双许可,不附加任何其他条款或条件。
请参阅 CONTRIBUTING.md。
依赖项
~35–50MB
~752K SLoC