您可以通过cp命令将您的本地文件或文件夹上传至OSS。

注意事项

  • 本文各命令行示例均基于Linux 64位系统,其他系统请将命令开头的./ossutil64替换成对应的Binary名称。详情请参见命令行工具ossutil快速入门
  • 使用cp命令上传文件时,默认使用分片上传和断点续传。如果您因意外中断了文件上传的过程,且未继续完成该文件的上传,则已上传的部分会以碎片(Part)的形式存储在OSS的存储空间(Bucket)中。如果您不再需要这些Part,建议您通过以下方式删除,以免产生额外的存储费用。

命令格式

./ossutil64 cp file_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxupspeed <value>]
[--enable-symlink-dir]
[--disable-all-symlink]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--disable-dir-object]
[--payer <value>]
[--tagging <value>]
[-j, --job <value>]
[--parallel <value>]

参数及选项说明如下:

配置项 说明
file_url 本地文件路径。例如Linux系统文件路径/localfolder/examplefile.txt,Windows系统文件路径D:\localfolder\examplefile.txt
cloud_url OSS文件路径。格式为oss://bucketname/objectname。例如oss://examplebucket/examplefile.txt
-r, --recursive 递归操作。当指定该选项时,ossutil会对Bucket下所有符合条件的Object进行操作,否则只对指定的单个Object进行操作。
-f --force 强制操作,不进行询问提示。
-u,--update 只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ossutil才会执行上传操作。
--maxupspeed 最大上传速度,单位为KB/s。默认值为0,表示不限制上传速度。
--enable-symlink-dir 上传链接子目录,默认不上传。
--disable-all-symlink 上传时忽略所有的软链接子文件以及软链接子目录。
--disable-ignore-error 批量操作时不忽略错误。
--only-current-dir 仅上传当前目录下的文件,忽略子目录及子目录下的文件。
-bigfile-threshold 设置断点续传文件的大小阈值,单位为字节。

默认值:100 MB

取值范围:0~9223372036854775807

--part-size 设置分片大小,单位为字节。默认情况下ossutil会根据文件大小自行计算合适的分片大小值。

取值范围:1~9223372036854775807

--checkpoint-dir 指定断点续传记录信息所在的目录。断点续传操作失败时,ossutil会自动创建名为.ossutil_checkpoint的目录,并在该目录下记录checkpoint信息,断点续传成功后会删除该目录。如果指定了该选项,请确保指定的目录可以被删除。
--encoding-type 文件名称的编码方式。取值为url。如果不指定该选项,则表示文件名称未经过编码。
--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内文件进行读写操作。这有可能造成您数据的外泄以及费用激增,请谨慎操作。
--snapshot-path 指定保存上传文件时的快照信息所在的目录。在下一次上传文件时,ossutil会读取指定目录下的快照信息进行增量上传。
--disable-crc64 关闭CRC64数据校验。默认情况下,ossutil进行数据传输时都会打开CRC64校验。
--disable-dir-object 表示上传文件时不为目录生成Object。
--payer 请求的支付方式。如果希望访问指定路径下的资源产生的流量、请求次数等费用由请求者支付,请将此选项的值设置为requester
--tagging 上传文件时设置标签信息,格式为TagkeyA=TagvalueA&TagkeyB=TagvalueB....
-j,--jobs 多文件操作时的并发任务数,默认值为3,取值范围为1~10000。
--parallel 单文件操作时的并发任务数,取值范围为1~10000。 如果不设置此选项,默认由ossutil根据操作类型和文件大小自行决定。

从以上命令格式中的-j,--jobs--parallel选项得知,当ossutil自行设置的默认并发数达不到用户的性能要求时,您可以自行调整这两个选项来升降性能。默认情况下,ossutil会根据文件大小来计算parallel个数。当批量上传大文件时,实际的并发数为jobs个数乘以parallel个数。

  • 当ECS虚拟机或者服务器在网络、内存、CPU等资源不是特别大的情况下,建议将并发数调整到100以下。如果网络、内存、CPU等资源没有占满,可以适当增加并发数。
  • 由于线程间资源切换及抢夺等原因,如果并发数过大,ossutil上传性能可能会下降。此外,并发数过大还可能产生EOF错误。所以请根据实际的机器情况调整-j,--jobs--parallel选项的数值。如果要进行压测,可在一开始时调低这两项数值,然后逐渐调大直至找到最优值。

示例环境

本文以Linux系统为例,将本地文件或文件夹上传至OSS中。您在实际使用中,请根据您的系统和使用环境修改对应参数。本文涉及的通用示例说明如下:

  • 本地文件:examplefile.txt(根目录下的文件)
  • 本地文件夹:localfolder(根目录下的文件夹)
  • 目标Bucket:examplebucket
  • 目标Bucket指定目录:desfolder

简单上传

ossutil支持将本地文件上传到OSS,示例如下:

  • 上传单个文件

    上传文件时,如果不指定上传至OSS的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在OSS中。

    ./ossutil64 cp examplefile.txt oss://examplebucket/desfolder/
  • 仅上传文件夹内的文件
    使用cp命令时增加-r选项,可以将目标文件夹内的文件上传到OSS指定目录。
    ./ossutil64 cp -r localfolder/ oss://examplebucket/desfolder/
  • 上传文件夹及文件夹内的文件

    使用cp命令时增加-r选项,可以将目标文件夹以及文件夹内的文件上传到OSS指定目录。

    ./ossutil64 cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
  • 上传单个文件并指定--meta选项
    上传文件的同时可以使用--meta选项设置文件的meta信息,其内容格式为header:value#header:value...
    ./ossutil64 cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
  • 上传文件夹并跳过已有文件

    批量上传失败重传时,可以指定--update(可缩写为-u)选项跳过已经上传成功的文件,实现增量上传。示例如下:

    ./ossutil64 cp -r localfolder/ oss://examplebucket/desfolder/ -u
  • 上传文件到开通了请求者付费模式的Bucket
    ./ossutil64 cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester
  • 仅上传当前目录下的文件,忽略子目录
    ./ossutil64 cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r
  • 上传时不为目录生成Object

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

    ./ossutil64 cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
  • 上传软链接子目录下的文件
    ./ossutil64 cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r
  • 上传时忽略所有的软链接子文件以及软链接子目录
    ./ossutil64 cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

上传时限速

您可以在上传文件时,结合--maxupspeed选项来限制上传的最大速度,单位为KB/s。示例如下:
  • 上传文件并设置限速为1 MB/s
    ./ossutil64 cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024
  • 上传文件夹并设置限速为1 MB/s
    ./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

上传并设置对象标签

您可以在上传文件时,通过--tagging选项设置文件对象标签,多个标签以and(&)符号隔开。示例如下:
./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"

关于对象标签的更多说明请参见object-tagging(对象标签)

上传并指定文件类型

您可以在上传文件时,通过--meta选项设置文件存储类型。存储类型可选值为:
  • Standard:标准存储
  • IA:低频访问
  • Archive:归档存储
如果上传时未指定存储类型,则以存储空间的存储类型为准。更多详情请参见存储类型介绍。示例如下:
  • 上传单个文件并指定存储类型为低频访问类型
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA
  • 上传文件夹并指定存储类型为标准存储类型
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

上传并指定读写权限ACL

您可以在上传文件时,通过--meta选项设置文件的ACL。文件ACL可选值为:
  • default:继承Bucket(默认)
  • private:私有
  • public-read:公共读
  • public-read-write:公共读写
示例如下:
  • 上传单个文件并指定ACL为私有
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta x-oss-object-acl:private
  • 上传文件夹并指定ACL为公共读
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta x-oss-object-acl:public-read  -r

上传并指定加密方式

您可以在上传文件时指定文件的服务器端加密方式,将文件加密后保存在Bucket内。 示例如下:
  • 上传文件并指定加密方式为OSS完全托管,加密算法为AES256
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256
  • 上传文件并指定加密方式为OSS完全托管,加密算法为SM4
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:SM4
  • 上传文件并指定加密方式为KMS,指定加密算法为AES256,不指定CMK ID
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS

    使用KMS加密时,会产生少量KMS密钥使用费用,详情请参见KMS计费标准

  • 上传文件并指定加密方式为KMS,指定加密算法为SM4,指定CMK ID
    ./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-data-encryption:SM4#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

有关服务器端加密功能介绍,请参见服务器端加密

上传并生成快照

批量上传时,如果指定--snapshot-path选项,ossutil在指定的目录下生成文件上传的快照,记录成功上传的文件的本地lastModifiedTime,在下次上传时通过比较lastModifiedTime来决定是否跳过相同文件,所以在使用该选项时,请确保两次上传期间没有其他用户更改了OSS上对应的Object。--snapshot-path选项适用于加速增量上传的场景。示例如下:
./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path                                
注意
  • ossutil不会主动删除snapshot-path文件夹中的快照信息。为避免快照信息过多,请定期删除snapshot-path文件夹内无用的快照。
  • 由于读写snapshot信息需要额外开销,当待批量上传的文件数量较少、网络状况较好、或有其他用户操作相同Object时,不建议使用该选项。针对以上情况,您可以使用--update选项来增量上传。
  • --update选项和--snapshot-path选项可以同时使用,ossutil会优先根据snapshot-path信息判断是否跳过此文件,如果不满足跳过条件,再根据--update判断是否跳过此文件。

批量上传符合条件的文件

批量上传时,如果指定--include--exclude选项,ossutil会批量上传符合指定条件的文件。

--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(包含)和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符合条件。
注意 设定条件时不支持目录格式,例如--include "/usr/test/.jpg"
示例如下:
  • 上传所有文件格式为TXT的文件
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r
  • 上传所有文件名包含abc且不是JPGTXT格式的文件
    ./ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

通用选项

当您需要通过命令行工具ossutil管理不同地域的Bucket时,可以通过-e选项切换至指定Bucket所属的Endpoint。当您需要通过命令行工具ossutil管理多个阿里云账号下的Bucket时,可以通过-i选项切换至指定账号的AccessKey ID,并通过-k选项切换至指定账号的AccessKey Secret。

例如,您需要将本地文件exampleobject.txt上传至另一个阿里云账号下,华东2(上海)地域的存储空间examplebucket的destfolder目录下,命令如下:
./ossutil64 cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

有关此命令的其他通用选项的更多信息,请参见通用选项