s3sync

概述

S3sync 是一个可靠、非常快速且强大的 S3 同步工具。
它可以用来同步本地目录与 S3 存储桶，也可以用来同步 S3 与 S3 存储桶。支持分块上传、版本控制和元数据。

作为库

S3sync 可以作为库使用。

use s3sync::config::args::parse_from_args;
use s3sync::config::Config;
use s3sync::pipeline::Pipeline;
use s3sync::types::token::create_pipeline_cancellation_token;

#[tokio::main]
async fn main() {
    // You can use all the arguments for s3sync binary here.
    let args = vec!["program_name", "./src", "s3://test-bucket/src/"];

    // s3sync library converts the arguments to Config.
    let config = Config::try_from(parse_from_args(args).unwrap()).unwrap();

    // Create a cancellation token for the pipeline.
    // You can use this token to cancel the pipeline.
    let cancellation_token = create_pipeline_cancellation_token();
    let mut pipeline = Pipeline::new(config.clone(), cancellation_token).await;

    // You can close statistics sender to stop statistics collection, if needed.
    // Statistics collection consumes some Memory, so it is recommended to close it if you don't need it.
    pipeline.close_stats_sender();

    // Run the pipeline. In this simple example, we run the pipeline synchronously.
    pipeline.run().await;

    assert!(!pipeline.has_error());
}

特性

• 可靠：深度端到端对象完整性检查
  S3sync 对每个对象计算 ETag (MD5 或等效) 并将其与目标中的 ETag 进行比较。
  存在于本地磁盘上的对象将从磁盘读取并与源或目标中的校验和进行比较。
  即使源对象是使用分块上传上传的，S3sync 也可以计算并比较每个部分和整个对象的 ETag。(使用 --auto-chunksize)
  可选地，S3sync 还可以计算和比较每个对象的附加校验和 (SHA256/SHA1/CRC32/CRC32C)。
  注意：Amazon S3 Express One Zone 存储类不支持 ETag 作为验证。但可以使用额外的校验和算法。

• 非常快速
  S3sync 使用 Rust 实现，使用 AWS SDK for Rust，该 SDK 使用多线程异步 I/O。
  在我的环境中（c6a.large，有 256 个工作者），本地到 S3，大约 4,000 个对象/秒（小对象 1-20 kb）。
  S3sync 优化用于同步大量（超过数百万）对象。未针对传输少量（小于工作器大小：默认 16）大对象进行优化。（当然，也可以用于此目的。）

  本地到 S3，c6a.large(2vCPU, 4GB) 100,000 个对象（1-20 kb 对象），1.00 GiB，40.76 MiB/秒，25 秒，所有对象均进行端到端完整性验证（MD5、SHA256）。

  [ec2-user@ip-foo ~]$ time ./s3sync --worker-size 256 --additional-checksum-algorithm SHA256 ~/testdata s3://5786c9fb-e2a7-407c-814a-84ed9590e35c/testdata/
  1.00 GiB | 40.76 MiB/sec,  transferred 100000 objects | 3,980 objects/sec,  etag verified 100000 objects,  checksum verified 100000 objects,  deleted 0 objects,  skipped 0 objects,  error 0 objects, warning 0 objects,  duration 25 seconds
  
  real    0m25.142s
  user    0m28.928s
  sys     0m19.969s
  

  S3 到本地，c6a.large(2vCPU, 4GB) 100,000 个对象（1-20 kb 对象），1.00 GiB，24.70 MiB/秒，41 秒，所有对象均进行端到端完整性验证（MD5、SHA256）。

  [ec2-user@ip-foo ~]$ time ./s3sync --worker-size 256 --enable-additional-checksum  s3://5786c9fb-e2a7-407c-814a-84ed9590e35c/ .
  1.00 GiB | 24.70 MiB/sec,  transferred 100000 objects | 2,412 objects/sec,  etag verified 100000 objects,  checksum verified 100000 objects,  deleted 0 objects,  skipped 0 objects,  error 0 objects, warning 0 objects,  duration 41 seconds
  
  real    0m41.471s
  user    0m47.906s
  sys     0m25.662s
  

  本地到S3，c6a.large(2vCPU, 4GB) 16个对象（6GiB对象），96.00 GiB，208.92 MiB/sec，8分钟，所有对象都经过端到端完整性验证（MD5，SHA256）。

  [ec2-user@ip-foo ~]$ time ./s3sync --additional-checksum-algorithm SHA256 ~/testdata s3://b2f99466-6665-4b8e-8327-a7bdabff8a10/testdata/
  96.00 GiB | 208.92 MiB/sec,  transferred  16 objects | 0 objects/sec,  etag verified 16 objects,  checksum verified 16 objects,  deleted 0 objects,  skipped 0 objects,  error 0 objects, warning 0 objects,  duration 8 minutes
    
  real    7m50.571s
  user    10m40.117s
  sys     4m28.771s
  

  S3到本地，c6a.large(2vCPU, 4GB) 16个对象（6GiB对象），96.00 GiB，41.67 MiB/sec，39分钟，所有对象都经过端到端完整性验证（MD5，SHA256）。
  在S3到本地的场景中，ETag/附加校验和验证成本较高。因为s3sync需要从本地磁盘读取整个下载对象来计算ETag/校验和。
  您可以使用--disable-etag-verify来禁用它。

  [ec2-user@ip-foo ~]$ time ./s3sync --enable-additional-checksum s3://b2f99466-6665-4b8e-8327-a7bdabff8a10 .
  96.00 GiB | 41.67 MiB/sec,  transferred  16 objects | 0 objects/sec,  etag verified 16 objects,  checksum verified 16 objects,  deleted 0 objects,  skipped 0 objects,  error 0 objects, warning 0 objects,  duration 39 minutes
    
  real    39m19.267s
  user    11m3.478s
  sys     8m35.242s
  

  S3到本地，c6a.large(2vCPU, 4GB) 16个对象（6GiB对象），96.00 GiB，125.67 MiB/sec，13分钟，不进行端到端完整性验证。
  当您需要快速传输大量数据时，这可能会很有用。

  [ec2-user@ip-foo ~]$ time ./s3sync --disable-etag-verify s3://b2f99466-6665-4b8e-8327-a7bdabff8a10 .
  96.00 GiB | 125.67 MiB/sec,  transferred  16 objects | 0 objects/sec,  etag verified 0 objects,  checksum verified 0 objects,  deleted 0 objects,  skipped 0 objects,  error 0 objects, warning 0 objects,  duration 13 minutes
  
  real    13m2.278s
  user    3m54.569s
  sys     9m40.960s  
  

• 多种方式

  • 本地到S3
  • S3到本地
  • S3到S3

• 支持任何对象大小
  s3sync可以处理任何大小的对象。从0字节到5TiB。

• 内存使用量低
  内存使用量低，不依赖于对象大小或对象数量。它主要取决于工作进程数量和多部分块大小。
  默认设置使用大约500MB的最大内存，无论对象大小或对象数量。

• 增量传输（正常传输）
  只传输已修改的对象。如果对象的修改时间晚于目标对象，则传输该对象。增量传输可以从最后一个检查点恢复。检查修改对象非常快。

• 基于ETag（MD5或等效）的增量传输
  如果您想使用基于ETag的增量传输，可以使用--check-etag选项。
  它比较源对象的ETag与目标对象的ETag，并只传输已修改的对象。
  ETag不总是MD5。如果对象使用多部分上传上传，ETag不是MD5散列，而是这些连接值的MD5散列。默认设置使用multipart-threshold（默认：8MiB）和multipart-chunksize（默认：8MiB），并根据这些值计算每个部分的ETag。
  使用--auto-chunksize，s3sync可以根据正确的块大小计算和比较每个部分和整个对象的ETag。如果您不知道正确的块大小，这很有用。但需要更多的API调用和时间。请参阅--auto-chunksize选项。
  使用--dry-run，您可以在不传输对象的情况下检查同步状态。
  使用--json-tracing，您可以以JSON格式输出跟踪信息。

s3sync -vv --dry-run --check-etag --auto-chunksize testdata/ s3://XXXX/testdata/
2024-06-15T01:23:50.632072Z DEBUG object filtered. ETags are same. name="HeadObjectChecker" source_e_tag="da6a0d097e307ac52ed9b4ad551801fc" target_e_tag="da6a0d097e307ac52ed9b4ad551801fc" source_last_modified="2024-06-15T01:01:48.687+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=6291456 target_size=6291456 key="dir1/data2.dat"
2024-06-15T01:23:50.675831Z DEBUG object filtered. ETags are same. name="HeadObjectChecker" source_e_tag="d126ef08817d0490e207e456cb0ae080-2" target_e_tag="d126ef08817d0490e207e456cb0ae080-2" source_last_modified="2024-06-15T01:01:48.685+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=9437184 target_size=9437184 key="dir1/data1.dat"
2024-06-15T01:23:50.683417Z DEBUG object filtered. ETags are same. name="HeadObjectChecker" source_e_tag="ebe97f2a4738800fe71edbe389c000a6-2" target_e_tag="ebe97f2a4738800fe71edbe389c000a6-2" source_last_modified="2024-06-15T01:01:48.690+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=12582912 target_size=12582912 key="dir1/data3.dat"
0 B | 0 B/sec,  transferred   0 objects | 0 objects/sec,  etag verified 0 objects,  checksum verified 0 objects,  deleted 0 objects,  skipped 3 objects,  error 0 objects, warning 0 objects,  duration 0 seconds

• 基于附加校验和（SHA256/SHA1/CRC32/CRC32C）的增量传输
  如果您使用带有附加校验和的Amazon S3，可以使用-check-additional-checksum选项。
  此选项比较源对象和目标对象的校验和，并只传输已修改的对象。它每个对象都需要额外的API调用。
  使用--dry-run，您可以在不传输对象的情况下检查同步状态。
  使用--json-tracing，您可以以JSON格式输出跟踪信息。

s3sync -vv --dry-run --check-additional-checksum SHA256 --additional-checksum-algorithm SHA256 testdata/ s3://XXXX/testdata/
2024-06-15T01:06:30.035362Z DEBUG object filtered. Checksums are same. name="HeadObjectChecker" checksum_algorithm="SHA256" source_checksum="tp2uVqFNGoMU7UBmTEAz6gpVDuomc+BN9CpmrGufryw=" target_checksum="tp2uVqFNGoMU7UBmTEAz6gpVDuomc+BN9CpmrGufryw=" source_last_modified="2024-06-15T01:01:48.687+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=6291456 target_size=6291456 key="dir1/data2.dat"
2024-06-15T01:06:30.041354Z DEBUG object filtered. Checksums are same. name="HeadObjectChecker" checksum_algorithm="SHA256" source_checksum="zWifJvli3SaQ9LZtHxzpOjkUE9x4ovgJZ+34As/NMwc=-2" target_checksum="zWifJvli3SaQ9LZtHxzpOjkUE9x4ovgJZ+34As/NMwc=-2" source_last_modified="2024-06-15T01:01:48.685+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=9437184 target_size=9437184 key="dir1/data1.dat"
2024-06-15T01:06:30.086455Z DEBUG object filtered. Checksums are same. name="HeadObjectChecker" checksum_algorithm="SHA256" source_checksum="MyTyVYvNthXQp4fOwy/IzuKgFGIzIHpP1DiTfjZoV0Q=-2" target_checksum="MyTyVYvNthXQp4fOwy/IzuKgFGIzIHpP1DiTfjZoV0Q=-2" source_last_modified="2024-06-15T01:01:48.690+00:00" target_last_modified="2024-06-15T01:02:27+00:00" source_size=12582912 target_size=12582912 key="dir1/data3.dat"
0 B | 0 B/sec,  transferred   0 objects | 0 objects/sec,  etag verified 0 objects,  checksum verified 0 objects,  deleted 0 objects,  skipped 3 objects,  error 0 objects, warning 0 objects,  duration 0 seconds

• 版本支持
  可以同步对象的所有版本。（除中间删除标记外）

• 标签支持
  可以同步对象的所有标签。

• 元数据支持
  可以同步对象的所有元数据。例如，Content-Type，Content-Encoding，Cache-Control，用户定义的元数据等。

• 灵活过滤
  正则表达式，ContentLength，LastModified。

• 按对象进行速率限制，带宽
  例如，您可以限制每秒传输的对象数量为1,000个，带宽为100MB/sec。

• --delete 支持
  在同步过程中，如果目标中存在而源中不存在的对象将被删除。
  由于这可能会导致数据丢失，请在使用 --dry-run 选项进行测试后再进行。

• S3 兼容存储支持
  s3sync 使用 Rust 的 AWS SDK。s3sync 可以与任何 S3 兼容存储一起使用。
  最初，它是为了 S3 兼容而开发的。

• 多平台支持
  所有功能均支持在受支持的平台上。

要求

• 64位 Linux (内核 3.2 或更高版本，glibc 2.17 或更高版本)
• 64位 Windows 10 或更高版本
• MacOS 11.0 或更高版本

许可证

本项目采用 Apache-2.0 许可证。

安装

从 发布 下载最新二进制文件
二进制文件在上述平台上运行，无需任何依赖项。

您也可以按照以下说明从源代码构建。

安装 Rust

请参阅 https://rust-lang.net.cn/tools/install

构建

s3sync 需要 Rust 1.76 或更高版本。

cargo install s3sync --path .

用法

使用 s3sync 需要AWS凭证。支持 IAM 角色、AWC CLI 配置文件、环境变量等。
默认情况下，s3sync 从许多位置获取访问凭证（IAM 角色、环境变量等）。
有关更多信息，请参阅 指定您的凭证和默认区域

您也可以在命令行选项或环境变量中指定凭证。

区域是必需的。可以在配置文件、环境或命令行选项中指定。

前缀是可选的。如果未指定，则将同步整个桶。

如果指定了前缀，则 s3sync 不会自动添加尾随斜杠。
例如，如果您将 s3://bucket-name/prefix 作为目标，则 s3sync 将同步名为 foo 的源对象到 s3://bucket-name/prefixfoo。
如果您将 s3://bucket-name/prefix/ 作为目标，则 s3sync 将同步名为 foo 的源对象到 s3://bucket-name/prefix/foo。

s3sync /path/to/local s3://bucket-name/prefix

s3sync s3://bucket-name/prefix /path/to/local

s3sync s3://bucket-name1/prefix s3://bucket-name2/prefix

s3sync --source-access-key foo --source-secret-access-key bar s3://bucket-name/prefix /path/to/local

s3sync --source-profile foo --target-profile bar s3://bucket-name1/prefix s3://bucket-name2/prefix

s3sync --source-profile foo --source-region ap-northeast-1 s3://bucket-name1/prefix s3://bucket-name2/prefix

s3sync --enable-versioning s3://bucket-name1/prefix s3://bucket-name2/prefix

s3sync --target-endpoint-url https://foo --target-force-path-style /path/to/local s3://bucket-name/prefix 

s3sync --dry-run s3://bucket-name1/prefix s3://bucket-name2/prefix

s3sync --delete s3://bucket-name1/prefix s3://bucket-name2/prefix

"Action": [
    "s3:GetBucketVersioning",
    "s3:GetObject",
    "s3:GetObjectAttributes",
    "s3:GetObjectTagging",
    "s3:GetObjectVersion",
    "s3:GetObjectVersionAttributes",
    "s3:GetObjectVersionTagging",
    "s3:ListBucket",
    "s3:ListBucketVersions",
    "s3express:CreateSession",
]

"Action": [
    "s3:AbortMultipartUpload",
    "s3:DeleteObject",
    "s3:DeleteObjectTagging",
    "s3:GetBucketVersioning",
    "s3:GetObject",
    "s3:GetObjectTagging",
    "s3:GetObjectVersion",
    "s3:ListBucket",
    "s3:ListBucketVersions",
    "s3:PutObject",
    "s3:PutObjectTagging",
    "s3express:CreateSession"
]

s3sync --auto-complete-shell bash