sync命令用于同步本地文件和文件夹到OSS-对象存储-阿里云

sync命令用于将本地文件或文件夹同步到OSS。通过增量对比文件的最后修改时间或快照信息，sync命令可以高效识别并同步差异文件，保持源和目标内容的一致性。

工作机制

文件数量
通过sync命令执行同步任务时，如果没有携带--delete选项，则单次同步任务同步的文件个数无限制。如果携带了--delete选项，则单次同步任务最多可同步100万个文件。当同步的文件个数超出100万时，将报错over max sync numbers 1000000.。
sync命令与cp命令的区别
- sync命令强制以递归的方式遍历指定文件夹内所有文件或子文件夹。cp命令需增加-r选项才会进行递归操作。
- 通过sync命令将数据同步到OSS时，ossutil支持通过--delete选项将目的端存在而源端不存在的文件都删除，仅保留本次同步的文件。cp命令不支持--delete选项。
- sync不支持--version-id选项，无法在已开启版本控制的Bucket内同步历史版本文件。cp命令支持--version-id选项。
除以上区别外，sync命令与cp命令用法类似。有关cp命令的用法及示例，请参见cp（上传文件）。

注意事项

从ossutil 1.6.16版本开始，命令行中Binary名称支持直接使用ossutil，您无需根据系统刷新Binary名称。如果您的ossutil版本低于1.6.16，则需要根据系统刷新Binary名称。更多信息，请参见命令行工具ossutil命令参考。

权限说明

默认情况下，只有阿里云账号拥有所有API的操作权限。RAM用户或RAM角色需要被阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予相应的权限才能执行此命令。

API Action	说明
oss:ListObjects	列出目标Bucket内的文件，用于与本地文件进行对比。
oss:PutObject	上传文件到OSS。
oss:DeleteObject	[可选] 当使用--delete选项时，需要此权限删除目标Bucket中多余的文件。
oss:PutObjectTagging	[可选] 当使用--tagging选项为Object添加标签时，需要此权限。

命令格式

ossutil sync file_url cloud_url [options]

参数及选项说明如下：

参数	说明
file_url	待同步的本地文件夹路径。例如Linux系统文件路径`/localfolder/`，Windows系统文件路径`D:\localfolder\`。
cloud_url	OSS文件夹路径。格式为`oss://bucketname/path/`。例如`oss://examplebucket/exampledir/`。如果输入的`cloud_url`没有以正斜线（/）结尾，ossutil会自动在结尾处添加一个正斜线（/）。
-f --force	强制操作，不进行询问提示。
-u，--update	只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ossutil才会执行同步操作。
--delete	删除目的端指定路径下的其他文件，仅保留本次同步的文件。警告建议您使用--delete选项前开启版本控制，防止数据误删除。
--enable-symlink-dir	同步链接子目录。
--disable-all-symlink	同步目录时，忽略所有的链接子文件以及链接子目录。
--disable-ignore-error	批量操作时不忽略错误。
--only-current-dir	仅同步当前目录下的文件，忽略子目录及子目录下的文件。
--output-dir	指定输出文件所在的目录。输出文件是指批量同步文件出错时产生的report文件，默认保存在当前目录下的ossutil_output目录。
-bigfile-threshold	设置断点续传文件的大小阈值，单位为字节。默认值：100 MB 取值范围：0~9223372036854775807
--part-size	设置分片大小，单位为字节。默认情况下ossutil会根据文件大小自行计算合适的分片大小值。取值范围：1~9223372036854775807
--checkpoint-dir	指定断点续传记录信息所在的目录。断点续传操作失败时，ossutil会自动创建名为`.ossutil_checkpoint`的目录，并在该目录下记录checkpoint信息，断点续传成功后会删除该目录。如果通过该选项指定了目录，请确保指定的目录可以被删除。
--encoding-type	文件名称的编码方式。取值为url。如果不指定该选项，则表示文件名称未经过编码。
--snapshot-path	指定保存同步文件时的快照信息所在的目录。在下一次同步文件时，ossutil会读取指定目录下的快照信息进行增量同步。
--include	包含符合指定条件的所有文件。更多信息，请参见include和exclude选项。
--exclude	不包含任何符合指定条件的文件。更多信息，请参见include和exclude选项。
--meta	设置文件的元数据，格式为`header:value#header:value`，示例为`Cache-Control:no-cache#Content-Encoding:gzip`。更多信息，请参见set-meta（管理文件元数据）。
--acl	文件的读写权限ACL。取值如下： default：继承Bucket的读写权限。 private（默认值）：只有该Bucket的拥有者可以对该Bucket内的文件进行读写操作，其他人无法访问该Bucket内的文件。 public-read：只有Bucket拥有者可以对该Bucket内的文件进行写操作，其他用户（包括匿名访问者）都可以对该Bucket中的文件进行读操作。这有可能造成您数据的外泄以及费用激增，若被人恶意写入违法信息还可能会侵害您的合法权益。除特殊场景外，不建议您配置此权限。 public-read-write：任何人（包括匿名访问者）都可以对该Bucket内文件进行读写操作。这有可能造成您数据的外泄以及费用激增，请谨慎操作。
--maxupspeed	最大上传速度，单位为KB/s。默认值为0，表示不限制上传速度。
--disable-crc64	关闭CRC64数据校验。
--payer	请求的支付方式。如果希望访问指定路径下的资源产生的流量、请求次数等费用由请求者支付，请将此选项的值设置为requester。
-j，--job	多文件操作时的并发任务数，默认值为3，取值范围为1~10000。
--parallel	单文件操作时的并发任务数，取值范围为1~10000。如果不设置此选项，默认由ossutil根据操作类型和文件大小自行决定。
--retry-times	发生错误后的重试次数。默认值为10，取值范围为1~500。
--tagging	文件的标签信息，格式为`TagkeyA=TagvalueA&TagkeyB=TagvalueB....`。

关于此命令的其他通用选项，请参见通用选项。

使用示例

以下示例均以 Linux 系统为例，请根据操作系统和实际环境修改参数。示例环境假定：

本地根目录下localfolder文件夹内有d.txt和e.png文件，OSS中名为examplebucket的Bucket下文件夹destfolder内有文件a.txt、b.txt和子文件夹C，其初始内容如下。

本地根目录                  examplebucket
    └── localfolder         └── destfolder/
            ├── d.txt               ├── a.txt
            └── e.png               ├── b.txt
                                    └── C/

将本地文件夹同步到OSS

将本地localfolder/下的所有文件同步到目标目录destfolder/。此操作仅上传新增文件，目标Bucket中已有的文件a.txt、b.txt和目录C/将被保留。

ossutil sync localfolder/ oss://examplebucket/destfolder/

同步成功后，返回结果中将包含同步的文件数量、文件大小以及完成同步操作所用时长：

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

同步后，destfolder/目录的结构如下：

destfolder/
├── a.txt
├── b.txt
├── d.txt 
├── e.png 
└── C/

同步时删除目标目录中的多余文件

在同步本地localfolder/的同时，使用--delete选项删除destfolder/目录中多余的文件和目录（即a.txt、b.txt和C/）。

ossutil sync localfolder/ oss://examplebucket/destfolder/ --delete

同步完成后，destfolder/的目录结构将与localfolder/完全一致：

destfolder/
├── d.txt
└── e.png

筛选并同步特定文件

通过--include和--exclude选项可以筛选需要同步的文件。

例如，以下命令仅同步.txt文件。

ossutil sync localfolder/  oss://examplebucket/destfolder/ --include "*.txt"

执行后，只有d.txt被上传，e.png被忽略。目标Bucket中原有的文件不受影响。

destfolder/
├── a.txt
├── b.txt
├── d.txt 
└── C/

以下命令仅同步非.txt文件。

ossutil sync localfolder/  oss://examplebucket/destfolder/ --exclude "*.txt"

执行后，只有e.png被上传，d.txt被忽略。目标Bucket中原有的文件不受影响。

destfolder/
├── a.txt
├── b.txt
├── e.png 
└── C/

强制覆盖目标目录的同名文件

当目标目录中存在与待上传文件同名的文件时，ossutil默认会提示确认是否覆盖。如果您确认目的端文件均可被覆写，使用-f或--force选项可以跳过交互式确认，直接强制覆盖。

ossutil sync localfolder/ oss://examplebucket/destfolder/ -f

命令执行成功后，返回结果中会包含同步的文件数量、总大小和平均速度等信息。输出示例如下：

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

跨账号同步

使用 -e,-i, -k 通用选项，将本地文件夹srcfolder的文件同步至另一个阿里云账号下位于“华东2（上海）”地域的存储空间examplebucket的testfolder目录下。

说明

需要根据Bucket所在地域填写对应的Endpoint。更多信息，请参见地域和Endpoint。

ossutil sync srcfolder/ oss://examplebucket/testfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret

安全提示：在命令行中直接使用AccessKey存在安全风险。对于自动化或长期任务，建议为源账号创建RAM角色并授权给目标账号使用，以实现更安全的跨账号访问。