使用ossutil cp命令上传本地文件和文件夹-对象存储-阿里云

将本地文件或目录上传至指定的存储空间（Bucket），支持简单上传、断点续传、批量上传、增量上传，并支持在上传时指定文件元数据、存储类型、访问权限等。

工作机制

使用cp命令上传文件时，ossutil会根据文件大小自动选择不同的上传方式：

简单上传：当文件大小小于断点续传文件的大小阈值（可通过 --bigfile-threshold 选项指定，默认值为 100 MB）时，采用简单上传方式。
断点续传：当文件大小大于或等于该阈值时使用。若上传意外中断，已上传的分片（Part）会临时存储在Bucket中。为避免产生存储费用，建议定期清理分片。可手动删除分片，或配置生命周期规则自动删除。

注意事项

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

当在OSS ON云盒中使用该命令时：
1. 将配置文件中的Endpoint替换为云盒Endpoint。更多信息，请参见云盒Endpoint。
2. 在本文已有示例的基础上添加--sign-version、--region以及--cloudbox-id选项。关于这三个选项的具体用法，请参见通用选项。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API Action	说明
`oss:PutObject`	上传Object。
`oss:PutObjectTagging`	可选。上传Object并设置标签信息时，需要此权限。
`kms:GenerateDataKey`	可选。上传Object并设置KMS服务器端加密时，需要此权限。
`kms:Decrypt`	可选。上传Object并设置KMS服务器端加密时，需要此权限。

命令格式

ossutil cp cloud_url file_url [options]

参数及选项说明如下：

参数	说明
file_url	本地文件路径。如果目标是目录，需以路径分隔符（/ 或 \）结尾。如Linux系统文件路径`/localfolder/examplefile.txt`，Windows系统文件路径`D:\localfolder\examplefile.txt`。
cloud_url	OSS文件路径，格式为`oss://bucket[/prefix]`。如`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	文件的元数据。包括部分HTTP标准属性（HTTP Header）以及以`x-oss-meta-`开头的用户自定义元数据（User Meta）。文件元数据格式为`header:value#header:value`，示例为`Cache-Control:no-cache#Content-Encoding:gzip`。有关OSS支持元数据的更多介绍，请参见管理文件元数据。
--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根据操作类型和文件大小自行决定。
--start-time	Unix时间戳。如果输入这个选项，最后更新时间早于该时间的Object会被忽略。说明仅1.7.18及以上版本支持设置该参数。关于如何升级版本，请参见update（ossutil版本升级）。
--end-time	Unix时间戳。如果使用该选项，则最后更新时间晚于通过此选项指定时间的Object会被忽略。说明如果同时指定了start-time和end-time，文件的修改时间在start-time和end-time之间才会执行拷贝命令。仅1.7.18及以上版本支持设置该参数。关于如何升级版本，请参见update（ossutil版本升级）。

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

当默认并发数达不到用户的性能要求时，可以调整-j，--jobs和--parallel选项来升降性能。默认情况下，ossutil根据文件大小来计算parallel。当批量传输大文件时，实际的并发数为jobs数乘以parallel数。

若执行命令的ECS或服务器的资源（网络、内存、CPU）有限，建议将并发数调低（如100以下）。如果资源未占满，可适当增加并发数。
并发数过高可能因线程切换开销和资源竞争导致性能下降，甚至引发EOF错误。请根据机器的实际资源状况调整-j，--jobs和--parallel。进行性能压测时，建议从较低的并发数开始，逐步增加以找到最佳值。

使用示例

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

Bucket 名称：examplebucket
OSS 目录：destfolder/
本地目录：localfolder/
本地文件：examplefile.txt

上传单个文件

上次文件到指定目录，并沿用原文件名。若不指定上传至OSS的文件名，则默认使用原文件名进行保存；若指定文件名，则按照指定的文件名保存在OSS中。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```

上传单个文件并指定--meta选项设置文件的meta信息，其内容格式为header:value#header:value...。

ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip

批量上传

仅上传文件夹内的文件
使用cp命令时增加-r选项，可以只将本地文件夹内的文件上传到OSS指定路径。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
上传文件夹内的文件并指定时间戳
将本地文件夹内的文件上传到OSS指定路径，文件修改时间限定在北京时间2023年10月31日10:09:18至2023年10月31日12:55:58内。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
上传文件夹及文件夹内的文件
使用cp命令时增加-r选项，并在OSS指定路径下添加本地文件夹名称，可以将本地文件夹以及文件夹内的文件上传到OSS指定路径。对于文件夹内的文件夹，OSS会对应创建0 KB大小、以正斜线（/）结尾的Object；对于指定的文件夹，OSS不会创建对应的Object。如果需要创建对应的Object，可以使用mkdir（创建目录）。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
上传文件夹并跳过已有文件
批量上传失败重传时，可以指定--update（可缩写为-u）选项跳过已经上传成功的文件，实现增量上传。示例如下：
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

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

上传软链接子目录下的文件

ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

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

ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

批量上传符合条件的文件

批量上传时，如果指定--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且不是JPG和TXT格式的文件

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

上传时限速

可以在上传文件时，结合--maxupspeed选项来限制上传的最大速度，单位为KB/s。示例如下：

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

ossutil 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：归档存储
ColdArchive：冷归档存储
DeepColdArchive：深度冷归档存储

说明

在OSS ON云盒使用场景中，仅支持Standard类型。

如果上传时未指定存储类型，则以存储空间的存储类型为准。更多信息，请参见存储类型。

上传并指定存储类型的示例如下：

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

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

可以在上传文件时，通过--acl选项设置文件的读写权限ACL。文件ACL可选值为：

default：继承Bucket（默认）
private：私有
public-read：公共读
public-read-write：公共读写

示例如下：

上传单个文件并指定ACL为私有

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

上传文件夹并指定ACL为公共读

ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

上传并指定加密方式

可以在上传文件时指定文件的服务器端加密方式，将文件加密后保存在Bucket内。示例如下：

说明

在OSS ON云盒使用场景中，仅支持AES256加密方式。

上传文件并指定加密方式为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判断是否跳过此文件。

上传并配置请求者付费

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

跨账号或跨地域上传

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

说明

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

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret