阿里云oss命令详解

SYNOPSIS

上传，下载或拷贝Objects

SYNTAX

ossutil cp file_url cloud_url [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir]
ossutil cp cloud_url file_url [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir]
ossutil cp cloud_url cloud_url [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir]

DETAIL DESCRIPTION

该命令允许：从本地文件系统上传文件到oss，从oss下载object到本地文件系统，在oss
上进行object拷贝。分别对应下述三种操作：
ossutil cp file_url oss://bucket[/prefix] [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]
ossutil cp oss://bucket[/prefix] file_url [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]
ossutil cp oss://src_bucket[/src_prefix] oss://dest_bucket[/dest_prefix] [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]

其中file_url代表本地文件系统中的文件路径，支持相对路径或绝对路径，请遵循本地文
件系统的使用格式；
oss://bucket[/prefix]代表oss上的object，支持前缀匹配，不支持通配符。
ossutil通过oss://前缀区分本地文件系统的文件和oss文件。

注意：在oss间拷贝文件，目前只支持拷贝object，不支持拷贝未complete的Multipart。

--recursive选项

（1）上传文件到oss时，如果file_url为目录，则必须指定--recursive选项，否则无需指
定--recursive选项。

（2）从oss下载或在oss间拷贝文件时：
如果未指定--recursive选项，则认为拷贝单个object，此时请确保src_url精确指定待
拷贝的object，如果object不存在，则报错。

如果指定了--recursive选项，ossutil会对src_url进行prefix匹配查找，对这些objects
批量拷贝，如果拷贝失败，已经执行的拷贝不会回退。

在进行批量文件上传（或下载、拷贝）时，如果其中某个文件操作失败，ossutil不会退出，
而是继续进行其他文件的上传（或下载、拷贝）动作，并将出错文件的错误信息记录到report
文件中。成功上传（或下载、拷贝）的文件信息将不会被记录到report文件中。

注意：批量操作出错时不继续运行，而是终止运行的情况：
（1）如果未进入批量文件迭代过程，错误已经发生，则不会产生report文件，ossutil会终止
运行，不继续迭代过程。如，用户输入cp命令出错时，不会产生report文件，而是屏幕输出错
误并退出。
（2）如果批量操作过程某文件发生的错误为：Bucket不存在、accessKeyID/accessKeySecret
错误造成的权限验证非法等错误，ossutil会屏幕输出错误并退出。

report文件名为：ossutil_report_日期_时间.report。report文件是ossutil输出文件的一种，
被放置在ossutil的输出目录下，该目录的路径可以用配置文件中的outputDir选项或命令行
--output-dir选项指定，如果未指定，会使用默认的输出目录：当前目录下的ossutil_output目录。

注意：ossutil不做report文件的维护工作，请自行查看及清理用户的report文件，避免产生
过多的report文件。

增量上传：

--update选项（-u）

如果指定了该选项，ossutil只有当目标文件（或object）不存在，或源文件（或object）新于
目标文件（或object）时，才执行拷贝。当指定了该选项时，无论--force选项是否指定了，在
目标文件存在时，ossutil都不会提示，直接采取上述策略。
该选项可用于当批量拷贝失败时，重传时跳过已经成功的文件。实现增量上传。

--snapshot-path选项

该选项用于在某些场景下加速增量上传批量文件（目前，下载和拷贝不支持该选项）。此场景为：
文件数较多且两次上传期间没有其他用户更改了oss上的对应object。

在cp上传文件时使用该选项，ossutil在指定的目录下生成文件记录文件上传的快照信息，在下一
次指定该选项上传时，ossutil会读取指定路径下的快照信息进行增量上传。用户指定的snapshot-path
必须为本地文件系统上的可写目录，若该路径目录不存在，ossutil会创建该文件用于记录快照信息，
如果该路径文件已存在，ossutil会读取里面的快照信息，根据快照信息进行增量上传（只上传上次
未成功上传的文件和本地进行过修改的文件），并更新快照信息。

注意：
（1）因为该命令通过在本地记录成功上传的文件的本地lastModifiedTime，从而在下次上传时通过
比较lastModifiedTime来决定是否跳过相同文件的上传，所以在使用该选项时，请确保两次上传期
间没有其他用户更改了oss上的对应object。当不满足该场景时，如果想要增量上传批量文件，请使
用--update选项。
（2）ossutil不会主动删除snapshot-path下的快照信息，为了避免快照信息过多，当用户确定快照信
息无用时，请用户自行清理snapshot-path。
（3）由于读写snapshot信息需要额外开销，当要批量上传的文件数比较少或网络状况比较好或有其
他用户操作相同object时，并不建议使用该选项。可以使用--update选项来增量上传。

注意：--update选项和--snapshot-path选项可以同时使用，ossutil会优先根据snapshot-path信息判断
是否跳过上传，如果不满足跳过条件，再根据--update判断是否跳过上传。如果指定了这两种增量上
传策略之中的任何一种，ossutil将根据策略判断是否进行上传/下载/拷贝，当遇到目标端的文件已
存在，也不会询问用户是否进行替换操作，此时--force选项不再生效。

--force选项

如果dest_url指定的文件或objects在oss上已经存在，并且未指定--update或--snapshot-path选项，
ossutil会询问是否进行替换操作（输入非法时默认不替换），如果指定了--force选项，则不询问，
强制替换。该选项只有在未指定--update或--snapshot-path选项时有效，否则按指定的选项操作。

--output-dir选项

该选项指定ossutil输出文件存放的目录，默认为：当前目录下的ossutil_output目录。如果指定
的目录不存在，ossutil会自动创建该目录，如果用户指定的路径已存在并且不是目录，会报错。
输出文件表示ossutil在运行过程中产生的输出文件，目前包含：在cp命令中ossutil运行出错时
产生的report文件。

大文件断点续传：

如果源文件大小超过--bigfile-threshold选项指定的大小（默认为100M），ossutil会认为该文件
为大文件，并自动使用断点续传策略，策略如下：
（1）上传到oss时：ossutil会对大文件自动分片，进行multipart分片上传，如果上传失败，会
在本地的.ossutil_checkpoint目录记录失败信息，下次重传时会读取.ossutil_checkpoint目
录中的信息进行断点续传，当上传成功时会删除.ossutil_checkpoint目录。
（2）从oss下载时：ossutil会自动对大文件分片下载，组装成一个文件，如果下载失败，同样会
在.ossutil_checkpoint目录记录失败信息，重试成功后会删除.ossutil_checkpoint目录。
（3）在oss间拷贝：ossutil会自动对大文件分片，使用Upload Part Copy方式拷贝，同样会在
.ossutil_checkpoint目录记录失败信息，重试成功后会删除.ossutil_checkpoint目录。

注意：
1）小文件不会采用断点续传策略，失败后下次直接重传。
2）在操作（1）和（3）中，如果操作失败，oss上可能会产生未complete的uploadId，但是只要最
终操作成功，就不会存在未complete的uploadId（被组装成object）。
3）上传到oss时，如果.ossutil_checkpoint目录包含在file_url中，.ossutil_checkpoint目录不会
被上传到oss。该目录路径可以用--checkpoint-dir选项指定，如果指定了该选项，请确保指定的目录
可以被删除。
4）如果使用rm命令删除了未complete的Multipart Upload，可能会造成下次cp命令断点续传失败（报
错：NoSuchUpload），这种时候如果想要重新上传整个文件，请删除相应的checkpoint文件。

--jobs选项和--parallel选项

--jobs选项控制多个文件上传/下载/拷贝时，文件间启动的并发数，--parallel控制上传/下载/拷
贝大文件时，分片间的并发数，ossutil会默认根据文件大小来计算parallel个数（该选项对于小文
件不起作用，进行分片上传/下载/拷贝的大文件文件阈值可由--bigfile-threshold选项来控制），
当进行批量大文件的上传/下载/拷贝时，实际的并发数为jobs个数乘以parallel个数。该两个选项
可由用户调整，当ossutil自行设置的默认并发达不到用户的性能需求时，用户可以自行调整该两个
选项来升降性能。

批量文件迁移：

ossutil支持批量文件迁移，在这种场景下，通常的使用方式是：
（1）批量上传：
ossutil cp your_dir oss://your_bucket -r -f -u
（2）批量下载：
ossutil cp oss://your_bucket your_dir -r -f -u
（3）同region的Bucket间迁移：
ossutil cp oss://your_src_bucket oss://your_dest_bucket -r -f -u

具体每个选项的意义，请见上文帮助。
在运行完一轮文件迁移后，请根据屏幕提示查看report文件，处理出错文件。

在批量上传时，如果文件数比较多且没有其他用户操作相同object时，可以使用--snapshot-path选项
进行额外的增量上传加速，更多信息参考上文关于--snapshot-path选项的介绍。命令为：
ossutil cp your_dir oss://your_bucket -r -f -u --shapshot-path=your-path

用法：

该命令有三种用法：

1) ossutil cp file_url oss://bucket[/prefix] [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]
该用法上传本地文件系统中文件或目录到oss。file_url可以为文件或目录。当file_url为文件
时，无论是否指定--recursive选项都不会影响结果。当file_url为目录时，即使目录为空或者只含
有一个文件，也必须使用--recursive选项，注意，此时ossutil会将file_url下的文件或子目录上传
到oss，但不同于shell拷贝，file_url所代表的首层目录不会被创建。
object命名规则：
当file_url为文件时，如果prefix为空或以/结尾，object名为：dest_url+文件名。
否则，object名为：dest_url。
当file_url为目录时，如果prefix为空或以/结尾，object名为：dest_url+文件或子目录相对
file_url的路径。
否则，object名为：dest_url+/+文件或子目录相对file_url的路径。

2) ossutil cp oss://bucket[/prefix] file_url [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]
该用法下载oss上的单个或多个Object到本地文件系统。如果未指定--recursive选项，则ossutil
认为src_url精确指定了待拷贝的单个object，此时不支持prefix匹配，如果object不存在则报错。如
果指定了--recursive选项，ossutil会搜索prefix匹配的objects，批量拷贝这些objects，此时file_url
必须为目录，如果该目录不存在，ossutil自动创建该目录。
文件命名规则：
当file_url为文件时，下载到file_url指定的文件，文件名与file_url保持一致。
当file_url为目录时，下载到file_url指定的目录中，文件名为：object名称，当object名称中含有/或\\时，会创建相应子目录。
注意：对于以/结尾且大小为0的object，会在本地文件系统创建一个目录，而不是尝试创建一个文件。
对于其他object会尝试创建文件。

3) ossutil cp oss://src_bucket[/src_prefix] oss://dest_bucket[/dest_prefix] [-r] [-f] [-u] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=file] [--snapshot-path=sdir]
该用法在oss间进行object的拷贝。其中src_bucket与dest_bucket可以相同，注意，当src_url与
dest_url完全相同时，ossutil不会做任何事情，直接提示退出。设置meta请使用set-meta命令。如果未
指定--recursive选项，则认为src_url精确指定了待拷贝的单个object，此时不支持prefix匹配，如果
object不存在则报错。如果指定了--recursive选项，ossutil会搜索prefix匹配的objects，批量拷贝这
些objects。
注意：批量拷贝时，src_url包含dest_url，或dest_url包含src_url是不允许的（dest_url以src_url为
前缀时，会产生递归拷贝，src_url以dest_url为前缀时，会覆盖待拷贝文件）。单个拷贝时，该情况是
允许的。
object命名规则：
当src_url为单个文件时，如果dest_url的prefix为空或以/结尾，object名为：dest_url+object名去除所在父目录的路径。
否则，object名为：dest_url。
当src_url为多个文件时，object名为：dest_url+源object名去除src_prefix。

SAMPLE

1) 上传文件到oss
假设本地local_dir目录中有文件a，b，目录c和d，目录c为空，目录d中包含文件dd。

ossutil cp local_dir/a oss://bucket1
生成：
oss://bucket1/a

ossutil cp local_dir/a oss://bucket1/b
生成：
oss://bucket1/b

ossutil cp local_dir/a oss://bucket1/b/
生成：
oss://bucket1/b/a

ossutil cp local_dir oss://bucket1/b/
报错

ossutil cp local_dir oss://bucket1/b -r
生成：
oss://bucket1/b/a
oss://bucket1/b/b
oss://bucket1/b/c/
oss://bucket1/b/d/
oss://bucket1/b/d/dd

ossutil cp local_dir oss://bucket1/b -r
如果某文件上传发生服务器内部错误等失败，会在当前目录下的ossutil_output目录中产生report文件
记录错误信息，并尝试其他文件的上传操作。

ossutil cp local_dir oss://bucket1/b -r --output-dir=your_dir
如果某文件上传发生服务器内部错误等失败，会在your_dir中产生report文件记录错误信息，并尝试其
他文件的上传操作。

ossutil cp local_dir oss://bucket1/b -r -u
使用--update策略进行增量上传

ossutil cp local_dir oss://bucket1/b -r --snapshot-path=your_local_path
使用--snapshot-path策略进行增量上传

ossutil cp local_dir oss://bucket1/b -r -u --snapshot-path=your_local_path
同时使用--snapshot-path和--update策略进行增量上传

2) 从oss下载object
假设oss上有下列objects：
oss://bucket/abcdir1/a
oss://bucket/abcdir1/b
oss://bucket/abcdir1/c
oss://bucket/abcdir2/a/
oss://bucket/abcdir2/b/e
其中oss://bucket/abcdir2/a/的size为0。

ossutil cp oss://bucket/abcdir1/a b
生成文件b

ossutil cp oss://bucket/abcdir1/a b --update
如果文件b已存在，且更新时间不晚于oss://bucket/abcdir1/a，则跳过本次操作。

ossutil cp oss://bucket/abcdir1/a b/
在目录b下生成文件a

ossutil cp oss://bucket/abcdir2/a/ b
如果b为已存在文件，报错。
如果b为已存在目录，在目录b下生成目录a。

ossutil cp oss://bucket/abc b
报错，object不存在。

ossutil cp oss://bucket/abc b -r
如果b为已存在文件，报错
否则在目录b下生成目录abcdir1和abcdir2，
目录abcdir1中生成文件a，b，c
目录abcdir2中生成目录a和b，目录b中生成文件e

ossutil cp oss://bucket/ local_dir -r
如果某文件下载发生服务器内部错误等失败，会在当前目录下的ossutil_output目录中产生report文件
记录错误信息，并尝试其他文件的下载操作。

ossutil cp oss://bucket/ local_dir -r --output-dir=your_dir
如果某文件下载发生服务器内部错误等失败，会在your_dir中产生report文件记录错误信息，并尝试其
他文件的下载操作。

ossutil cp oss://bucket/ local_dir -r -u
使用--update策略进行增量下载

3) 在oss间拷贝
假设oss上有下列objects：
oss://bucket/abcdir1/a
oss://bucket/abcdir1/b
oss://bucket/abcdir1/c
oss://bucket/abcdir2/a/
oss://bucket/abcdir2/b/e

ossutil cp oss://bucket/abcdir1/a oss://bucket1
生成：
oss://bucket1/a

ossutil cp oss://bucket/abcdir1/a oss://bucket1/b
生成:
oss://bucket1/b

ossutil cp oss://bucket/abcdir1/a oss://bucket/abcdir1/a/
生成:
oss://bucket/abcdir1/a/a

ossutil cp oss://bucket/abcdir1/a/ oss://bucket/abcdir1/b/
生成：
oss://bucket/abcdir1/b/a/

ossutil cp oss://bucket/abcdir1/a oss://bucket/abcdir1/a/ -r
报错，递归拷贝

ossutil cp oss://bucket/abcdir1/a oss://bucket1/b/
生成：
oss://bucket1/b/a

ossutil cp oss://bucket/abc oss://bucket1/b/
报错，object不存在

ossutil cp oss://bucket/abc oss://bucket1/123 -r
生成：
oss://bucket1/123dir1/a
oss://bucket1/123dir1/b
oss://bucket1/123dir1/c
oss://bucket1/123dir2/a/
oss://bucket1/123dir2/b/e

ossutil cp oss://bucket/abc oss://bucket1/123/ -r
生成：
oss://bucket1/123/dir1/a
oss://bucket1/123/dir1/b
oss://bucket1/123/dir1/c
oss://bucket1/123/dir2/a/
oss://bucket1/123/dir2/b/e

ossutil cp oss://bucket/abcdir1/a oss://bucket1/ -r
报错，因为此时目标object名称为空，非法

ossutil cp oss://bucket/ oss://bucket1/ -r
如果某文件拷贝发生服务器内部错误等失败，会在当前目录下的ossutil_output目录中产生report文件
记录错误信息，并尝试其他文件的拷贝操作。

ossutil cp oss://bucket/ oss://bucket1/ -r --output-dir=your_dir
如果某文件拷贝发生服务器内部错误等失败，会在your_dir中产生report文件记录错误文件的信息，并
尝试其他文件的拷贝操作。

ossutil cp oss://bucket/ oss://bucket1/ -r -u
使用--update策略进行增量拷贝

OPTIONS

-r, --recursive
递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对bucket下所有符合条件的objects进行操作，否则只对url中指定的单个object进行操作。

-f, --force
强制操作，不进行询问提示。

-u, --update
更新操作

--output-dir=ossutil_output
指定输出文件所在的目录，输出文件目前包含：cp命令批量拷贝文件出错时所产生的report文件（关于report文件更多信息，请参考cp命令帮助）。默认值为：当前目录下的ossutil_output目录。

--bigfile-threshold=104857600
开启大文件断点续传的文件大小阀值，默认值:100M，取值范围：0B-9223372036854775807B

--checkpoint-dir=.ossutil_checkpoint
checkpoint目录的路径(默认值为:.ossutil_checkpoint)，断点续传时，操作失败ossutil会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

-c, --config-file
ossutil工具的配置文件路径，ossutil启动时从配置文件读取配置，在config命令中，ossutil将配置写入该文件。

-e, --endpoint
ossutil工具的基本endpoint配置（该选项值会覆盖配置文件中的相应设置），注意其必须为一个二级域名。

-i, --access-key-id
访问oss使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。

-k, --access-key-secret
访问oss使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。

-t, --sts-token
访问oss使用的STSToken（该选项值会覆盖配置文件中的相应设置），非必须设置项。

--retry-times=3
当错误发生时的重试次数，默认值：3，取值范围：1-500

-j 5, --jobs=5
多文件操作时的并发任务数，默认值：5，取值范围：1-10000

--parallel
单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ossutil根据操作类型和文件大小自行决定。

--snapshot-path
该选项用于在某些场景下加速增量上传批量文件（目前，下载和拷贝不支持该选项）。在cp上传文件时使用该选项，ossutil在指定的目录下生成文件记录文件上传的快照信息，在下一次指定该选项上传时，ossutil会读取指定目录下的快照信息进行增量上传。用户指定的snapshot目录必须为本地文件系统上的可写目录，若该目录不存在，ossutil会创建该文件用于记录快照信息，如果该目录已存在，ossutil会读取里面的快照信息，根据快照信息进行增量上传（只上传上次未成功上传的文件和本地进行过修改的文件），并更新快照信息。注意：因为该选项通过在本地记录成功上传的文件的本地lastModifiedTime，从而在下次上传时通过比较lastModifiedTime来决定是否跳过相同文件的上传，所以在使用该选项时，请确保两次上传期间没有其他用户更改了oss上的对应object。当不满足该场景时，如果想要增量上传批量文件，请使用--update选项。另外，ossutil不会主动删除snapshot-path下的快照信息，为了避免快照信息过多，当用户确定快照信息无用时，请用户自行清理snapshot-path。