cp（上传文件）

注意事项

• 要上传文件，您必须具有oss:PutObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。

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

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

  • 如果上传的文件大小小于断点续传上传文件大小的阈值（该阈值通过--bigfile-threshold选项指定，默认值是100 MB），ossutil将采用简单上传的方式。

  • 如果上传的文件大小大于等于断点续传上传文件大小的阈值，ossutil将采用断点续传上传的方式。

    如果您因意外中断了文件上传的过程，且未继续完成该文件的上传，则已上传的部分会以碎片（Part）的形式存储在OSS的存储空间（Bucket）中。如果您不再需要这些Part，建议您通过以下方式删除，以免产生额外的存储费用。

    • 手动删除Part，请参见删除碎片。

    • 通过生命周期规则自动删除Part，请参见设置生命周期规则。

命令格式

ossutil 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>]
[--start-time <value>]
[--end-time <value>]

参数及选项说明如下：

从以上命令格式中的-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

简单上传

当您需要将本地文件、图片、视频等资源上传到OSS，可以使用ossutil，示例如下：

• 上传单个文件

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

  ossutil cp examplefile.txt oss://examplebucket/desfolder/

• 仅上传文件夹内的文件

  使用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/

• 上传单个文件并指定--meta选项

  上传文件的同时可以使用--meta选项设置文件的meta信息，其内容格式为header:value#header:value...。

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

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

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

  ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u

• 上传文件到开通了请求者付费模式的Bucket

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

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

  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

上传时限速

上传并设置对象标签

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"

关于对象标签的更多说明请参见object-tagging（对象标签）。

上传并指定存储类型

您可以在上传文件时，通过--meta选项设置文件存储类型。存储类型可选值为：

• Standard：标准存储

• IA：低频访问

• Archive：归档存储

• ColdArchive：冷归档存储

• DeepColdArchive：深度冷归档存储

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

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

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

  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

上传并指定加密方式

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

上传并生成快照

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path                                

批量上传符合条件的文件

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

通用选项

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

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

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