命令格式

• 上传文件

  ./ossutil cp file_url cloud_url  [-r] [-f] [-u] [--enable-symlink-dir] [--disable-all-symlink] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--snapshot-path=sdir] [--payer requester]

• 下载文件

  ./ossutil cp cloud_url file_url  [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--range=x-y] [--payer requester] [--version-id versionId]

• 拷贝文件

  ./ossutil cp cloud_url cloud_url [-r] [-f] [-u] [--only-current-dir] [--output-dir=odir] [--bigfile-threshold=size] [--checkpoint-dir=cdir] [--payer requester] [--version-id versionId]

上传示例

• 上传单个文件

  ./ossutil cp a.txt oss://bucket/path

• 上传单个文件并指定--meta选项
  上传文件的同时可以使用--meta选项设置文件的meta信息，其内容格式为header:value#header:value...，如下将当前目录下文件a.txt上传并设置其meta信息。

  ./ossutil cp a.txt oss://bucket/path --meta=Cache-Control:no-cache#Content-Encoding:gzip

  说明 更多关于meta设置的信息请参见set-meta。
• 上传文件夹
  使用cp命令时增加-r选项可以将目标文件夹上传到OSS。

  ./ossutil cp -r dir oss://bucket/path

  说明 若上传目标对象为符号链接（软链接），且指向本地文件夹，则使用cp命令上传时，应当给软链接加上正斜线（/）。

  ./ossutil cp -r symbolic_link/ oss://bucket/path

• 上传文件/文件夹并设置限速
  上传文件时，指定--maxupspeed选项，可设置上传时的最高速度，单位为KB/s，缺省为0（不限速）。

  • 上传文件并设置限速为1MByte/s

    ./ossutil cp a.jpg oss://bucket/path --maxupspeed 1024

  • 上传文件夹并设置限速为1MByte/s

    ./ossutil cp -r dir oss://bucket/path --maxupspeed 1024

• 批量上传符合条件的文件

  您可以使用--include/--exclude，在cp操作时批量选择对应条件的文件。

  --include/--exclude选项支持格式：

  • *：通配符，匹配所有字符。例如：*.txt表示匹配所有txt格式的文件。
  • ?：匹配单个字符，例如：abc?.jpg表示匹配所有文件名为abc+任意单个字符的jpg格式的文件，如 abc1.jpg
  • [sequence]：匹配序列的任意字符，例如：abc[1-5].jpg表示匹配文件名为abc1.jpg~abc5.jpg的文件
  • [!sequence]：匹配不在序列的任意字符，例如：abc[!0-7].jpg，表示匹配文件名不为abc0.jpg~abc7.jpg的文件。

  说明

  • 不支持带目录的格式，例如：--include "/usr/test/.jpg"。
  • 指定--include/--exclude选项时，需同时指定--recursive（-r）选项。
  • 一条规则中可以包含多个include（包含）和exclude（排除）条件，且每个文件从左到右逐一运用每个规则，直至最后才能最终确定匹配的结果。
    示例：当指定生效的文件夹中包含名为test.txt的文件，匹配不同的规则产生的结果如下。

    • 规则一：--include "*test*" --exclude "*.txt" ，当规则匹配到--include "*test*"，匹配的结果为test.txt符合条件；当规则继续匹配到--exclude "*.txt"时，因test.txt为txt文件，所以被排除。则匹配的最终结果为test.txt不符合条件。
    • 规则二：--exclude "*.txt" --include "*test*"，当规则匹配到--exclude "*.txt"，匹配的结果为test.txt不符合条件；当规则继续匹配到--include "*test*"，因test.txt文件名包含test，所以符合条件。则匹配的最终结果为test.txt符合条件。
    • 规则三：--include "*test*" --exclude "*.txt" --include "te?t.txt" ，当规则匹配到--include "*test*"，匹配的结果为test.txt符合条件；当规则继续匹配到--exclude "*.txt"时，因test.txt为txt文件，所以被排除；当规则最后匹配到--include "te?t.txt"时，因test.txt符合条件，所以被包含。则匹配的最终结果为test.txt符合条件。
  示例：

  • 上传所有文件格式为txt的文件

    ./ossutil cp dir/ oss://my-bucket/path --include "*.txt" -r

  • 上传所有文件名包含abc且不是jpg和txt格式的文件

    ./ossutil cp dir/ oss://my-bucket/path --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

• 上传文件并指定存储类型
  您可以在上传文件时，通过--meta选项修改对象存储类型。

  • 上传单个文件并指定存储类型为IA（低频访问）类型

    ./ossutil cp dir/sys.log  oss://my-bucket/path --meta X-oss-Storage-Class:IA

  • 上传文件目录并指定存储类型为IA类型

    ./ossutil cp dir/ oss://my-bucket/path --meta X-oss-Storage-Class:IA -r

• 上传文件并指定服务器端加密方式
  您可以在上传文件时指定文件的服务器端加密方式，将文件加密后保存在Bucket内，关于服务器端加密功能介绍请参见服务器端加密。

  • 上传文件并指定加密方式为AES256

    ./ossutil cp a.txt oss://my-bucket/path --meta=x-oss-server-side-encryption:AES256

  • 上传文件并指定加密方式为KMS

    ./ossutil cp a.txt oss://my-bucket/path --meta=x-oss-server-side-encryption:KMS

    使用KMS加密时，OSS会为这个文件在KMS平台上创建一个主密钥，会产生少量KMS密钥API调用费用，详情请参见KMS计费标准。

• 上传文件夹并跳过已有文件

  批量上传时，若指定--update（可缩写为-u）选项，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ossutil才会执行上传操作。命令如下：

  ./ossutil cp -r dir oss://bucket1/path -u

  该选项可用于当批量上传失败重传时，跳过已经成功的文件，实现增量上传。

• 上传文件夹并生成快照信息

  批量上传时，若指定--snapshot-path选项，ossutil在指定的目录下生成文件上传的快照信息，在下一次指定该选项上传时，ossutil会读取指定路径下的快照信息进行增量上传。命令如下：

  ./ossutil cp -r dir oss://bucket1/path --snapshot-path=path                                

  注意

  • --snapshot-path选项用于在某些场景下加速增量上传/下载批量文件（拷贝不支持该选项）。例如，文件数较多且两次上传期间没有其他用户更改OSS上对应的Object。
  • --snapshot-path选项通过在本地记录成功上传/下载的文件的本地lastModifiedTime，从而在下次上传/下载时通过比较lastModifiedTime来决定是否跳过相同文件，所以在使用该选项时，请确保两次上传/下载期间没有其他用户更改了OSS上的对应Object。当不满足该场景时，如果想要增量上传/下载批量文件，请使用--update选项。
  • ossutil不会主动删除snapshot-path下的快照信息，为了避免快照信息过多，当您确定快照信息无用时，请自行清理snapshot-path。
  • 由于读写snapshot信息需要额外开销，当要批量上传/下载的文件数比较少或网络状况比较好或有其他用户操作相同Object时，并不建议使用该选项。可以使用--update选项来增量上传/下载。
  • --update选项和--snapshot-path选项可以同时使用，ossutil会优先根据snapshot-path信息判断是否跳过此文件，如果不满足跳过条件，再根据--update判断是否跳过此文件。
• 上传文件到开通了请求者付费模式的Bucket

  ./ossutil cp dir/test.mp4 oss://payer/ --payer=requester

• 仅上传当前目录下的文件，忽略子目录

  ./ossutil cp dir/ oss://bucket1/path --only-current-dir -r

• 上传时不为目录生成Object

  ./ossutil cp dir/ oss://bucket1/path --disable-dir-object -r

  OSS的目录是用一个0KB大小，名称以正斜线（/）结尾的Object模拟的。上传时增加--disable-dir-object参数，ossutil不会为该目录生成Object，但您仍可以在OSS控制台看到对应的目录结构。当您删除目录内的文件时，该目录也会消失。
• 上传符号链接（软链接）子目录下的文件

  ./ossutil cp dir/ oss://bucket1/path --enable-symlink-dir -r

• 上传时忽略所有的符号链接子文件以及符号链接子目录

  ./ossutil cp dir/ oss://bucket1/path -r --disable-all-symlink

下载示例

• 下载单个文件

  ./ossutil cp oss://my-bucket/path/test1.txt /dir

• 指定范围下载文件

  下载文件时，可以通过--range选项进行指定范围下载。

  示例：将test1.txt的第10到第20个字符作为一个文件载到本地。

  ./ossutil cp oss://my-bucket/path/test1.txt /dir  --range=10-20
  Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).
  0.290769(s) elapsed

• 从开通了请求者付费模式的 Bucket 下载文件

  ./ossutil cp oss://payer/test.mp4 dir/ --payer=requester

• 下载文件夹

  ./ossutil cp -r oss://my-bucket/path /dir 

• 下载文件夹并指定--update选项
  批量下载时，若指定--update选项，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ossutil才会执行下载操作。命令如下：

  ./ossutil cp -r oss://bucket/path  /dir  --update                           

  该选项可用于当批量下载失败重传时，跳过已经下载成功的文件，实现增量下载。
• 下载文件夹并生成快照信息

  批量下载时，若指定--snapshot-path选项，ossutil在指定的目录下生成文件下载的快照信息，在下一次指定该选项下载时，ossutil会读取指定路径下的快照信息进行增量下载。详情请参见--snapshot-path选项。

  ./ossutil cp -r oss://bucket1/path dir --snapshot-path=path                                

• 批量下载符合指定条件的文件
  您可以使用--include/--exclude参数，在下载时选定符合条件的文件。详情请参见过滤选项。

  • 下载所有文件格式不为jpg的文件

    ./ossutil cp oss://my-bucket/path dir/ --exclude "*.jpg" -r

  • 下载所有文件名包含abc且不是jpg和txt格式的文件

    ./ossutil cp oss://my-bucket1/path dir/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

• 在已开启版本控制的Bucket内下载指定版本的文件

  ./ossutil cp oss://bucket1/test.jpg dir/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

  在使用--version-id选项前，需使用ls --all-versions命令获取文件的versionid。
  说明 --version-id选项仅支持在已开启版本控制的Bucket内使用。开启Bucket版本控制命令请参见bucket-versioning。
• 仅下载当前目录下的文件，忽略子目录

  ./ossutil cp oss://bucket1/path dir/ --only-current-dir -r

拷贝示例

目前只支持拷贝文件，不支持拷贝未完成的Multipart，不支持跨region拷贝文件。

• 拷贝单个文件

  ./ossutil cp oss://bucket/path1/a oss://bucket/path2/                                 

• 拷贝单个文件并重命名

  ./ossutil cp oss://bucket/path1/a oss://bucket/path2/b                           

• 批量拷贝符合指定条件的文件
  您可以使用--include/--exclude，在拷贝时选定符合条件的文件。详情请参见过滤选项。

  • 拷贝所有文件格式不为jpg的文件

    ./ossutil cp oss://my-bucket1/path oss://my-bucket2/path --exclude "*.jpg" -r

  • 拷贝所有文件名包含abc且不是jpg和txt格式的文件

    ./ossutil cp oss://my-bucket1/path oss://my-bucket2/path --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

• 拷贝文件并修改文件存储类型
  • 修改已有文件的存储类型为Archive（归档存储）类型

    ./ossutil cp oss://my-bucket/path/0104_6.jpg oss://my-bucket/path/0104_6.jpg --meta X-oss-Storage-Class:Archive

  • 修改已有文件目录下所有文件的文件类型为Standard（标准存储）类型

    ./ossutil cp oss://my-bucket/path/ oss://my-bucket/path/ --meta X-oss-Storage-Class:Standard -r

    注意

    • 存储类型为归档类型的文件不能通过cp命令直接转换成其他类型，必须先通过restore命令将该文件解冻，之后再使用cp命令转换文件类型。
    • 使用cp覆写文件时涉及到数据覆盖操作。如果低频访问型或归档型文件分别在创建后30和60天内被覆盖，则它们会产生提前删除费用。详情请参见计量项和计费项。
• 拷贝文件并指定服务器端加密方式
  您可以在拷贝文件时指定文件的服务器端加密方式，将文件加密后保存在Bucket内，关于服务器端加密功能介绍请参见服务器端加密。

  • 拷贝文件并指定加密方式为AES256

    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=x-oss-server-side-encryption:AES256

  • 拷贝文件并指定加密方式为KMS

    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=x-oss-server-side-encryption:KMS

    使用KMS加密时，OSS会为这个文件在KMS平台上创建一个主密钥，会产生少量KMS密钥API调用费用，详情请参见KMS计费标准。

• 拷贝单个文件并指定--meta选项
  拷贝文件的同时可以使用 --meta 选项设置 Object 的 meta 信息，其内容格式为 header:value#header:value...。

  ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=Cache-Control:no-cache

• 同region不同Bucket之间的文件拷贝
  拷贝文件时，搭配 -r 选项可以实现批量文件拷贝功能。

  ./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r                                   

• 同region不同Bucket之间的增量文件拷贝
  批量拷贝时，若指定--update选项，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ossutil才会执行拷贝操作。命令如下：

  ./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r --update

  该选项可用于当批量拷贝失败重传时，跳过已经拷贝成功的文件，实现增量拷贝。
• 从开通了请求者付费模式的Bucket拷贝文件到普通Bucket

  ./ossutil cp oss://payer/test.mp4 oss://my-bucket/path  --payer=requester

• 从普通Bucket拷贝数据到开通了请求者付费模式的Bucket

  ./ossutil cp oss://my-bucket/path/test.mp4 oss://payer --payer=requester

• 在已开启版本控制的Bucket内拷贝指定版本的文件

  ./ossutil cp oss://bucket1/test.jpg oss://bucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

  在使用--version-id选项前，需使用ls --all-versions命令获取文件的versionid。
  说明 --version-id选项仅支持在已开启版本控制的Bucket内使用。开启Bucket版本控制命令请参见bucket-versioning。
• 仅拷贝当前目录下的文件，忽略子目录

  ./ossutil cp oss://bucket1/path oss://bucket2/path --only-current-dir -r

性能调优

默认情况下，ossutil会根据文件大小来计算parallel个数（该选项对于小文件不起作用，进行分片上传/下载/拷贝大文件的文件阈值可由--bigfile-threshold选项来控制）。当进行批量大文件的上传/下载/拷贝时，实际的并发数为jobs个数乘以parallel个数。

常用选项