You need to enable JavaScript to run this app.
导航
上传对象(cp)
最近更新时间:2024.12.20 13:14:20首次发布时间:2022.11.03 10:30:29

您可以通过 cp 命令将本地对象上传至 TOS。

命令语法

  • 上传单个对象

    ./tosutil cp file_url tos://bucket[/key] [-dryRun] [-link] [-u] [-vchecksum] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-arcDir=xxx] [-fr] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]
    
  • 上传文件夹

    ./tosutil cp folder_url tos://bucket[/prefix] -r [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]
    
  • 上传文件列表

    ./tosutil cp file1_url,folder1_url|filelist_url tos://bucket[/prefix] -msm=1 [-r] [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]
    

性能优化建议

tosutil 支持通过 -j-p 参数调整并发数。当您批量上传大文件时,实际并发数为 -j 乘以 -p 参数。调整建议如下:

  • 资源不充足场景
    当网络、内存等资源不充足的场景下,建议您不要设置过高的并发数,避免因资源占满导致的性能下降或失败等问题。您可以根据实际资源情况,先设置一个较低的并发数,然后逐渐增大参数,直至调整至一个较优的设置。
  • 提升整体执行的 QPS 和带宽
    • 上传、下载、拷贝小文件:需要设置较高的并发数提升 QPS。
    • 上传、下载、拷贝大文件:避免并发数过高导致带宽抢占造成性能衰减。
      您可以通过 -nfj 参数和 -j 参数分别控制非分片任务和分片任务的并发数。例如设置 -j=100,-nfj=80,表示总并发数为 100,当执行非分片任务(一般是小文件)时,最大的并发数为 80;当执行分片任务(一般是大文件)时,最大的并发数为 20。
  • 公网运行场景
    由于公网网络不稳定以及客户端带宽较低等因素,容易导致上传缓慢且失败等问题,您可以参考以下建议调整参数:
    • 调大配置文件中的 maxRetryCount 参数,通过不断重试错误解决公网网络不稳定的问题。
    • 如果客户端带宽有限,您需要合理减少 -j-p 参数,避免因并发过高导致客户端超带宽,进而出现断流失败等情况。
    • 合理调整 -ps 参数,降低分片大小,有利于提高单个分片上传/下载/复制的成功率。

注意

在海量小文件场景中,如果您设置了较高的 -j,导致 TPS 超过 1000,您需要同步上调 maxConnections 参数,更多信息,请参见配置文件说明

参数说明

通用可选参数的说明,请参见通用可选参数

参数名

参数类型

描述

file_url

String

本地文件路径。

说明

如果您需要上传文件列表,可在命令中添加多个 file_url,以英文逗号(,)分隔。

folder_url

String

本地文件夹路径,需要 -r 参数配合使用。

bucket

String

桶名。

key

String

对象名。

prefix

String

批量操作时的对象名前缀。

-r

Bool

执行批量上传、下载或复制操作。

-dryRun

Bool

测试模式运行,不执行实际的上传、下载或复制操作。

-link

Bool

上传软链接文件或文件夹指向的真实路径。

-msm

Enum

开启多文件或文件夹上传模式,说明如下:

  • -msm=1:代表上传路径是一组文件或文件夹列表,以英文逗号(,)分隔。
  • -msm=2:代表上传路径是一个包含文件或文件夹列表的清单文件。

注意

  • 如果文件或文件夹名本身包含英文逗号,请不要使用 -msm=1 的模式。
  • 如果没有设置 -r 参数,则列表中的文件夹不会被上传。

-recover

String

待恢复上传、下载或复制对象任务的结果清单文件任务 ID。

-u

Bool

增量上传、下载或复制对象,设置该参数后,会比较源端和目标端,建议您在以下情况下使用:

  • 目标端不存在。
  • 目标端与源端的文件大小不一致。
  • 目标端的最后修改时间早于源端的最后修改时间时执行对应的操作。

-vchecksum

Bool

上传或下载对象时通过 CRC64 算法验证数据一致性。

-flat

Bool

上传、下载或复制对象时不包含相对父目录。

-j

Integer

批量任务的最大并发数,默认为配置文件中的 defaultJobs,默认值为 3。

-p

Integer

每个分片任务的最大并发数,默认为配置文件中的 defaultParallels,默认值为 1。

-threshold

Integer

开启分片任务的阈值,单位为字节,默认为配置文件中的 defaultBigfileThreshold

说明

支持带容量单位配置,例如,配置 1MB 代表 1048576 字节。

-nfj

Integer

批量任务的处理普通文件或对象(非分片任务)的最大并发数。当设置该参数后,-j 参数设置的并发数会分为两部分,普通文件的并发数为 nfj,分片任务的并发数为 j-nfj。仅在批量操作时生效。

-ps

Integer/String

每个分片任务的段大小,单位为字节,默认为配置文件中的 defaultPartSize

说明

支持带容量单位配置,例如,配置 1MB 代表 1048576 字节。

-cpd

String

生成断点记录文件的文件夹,默认为配置文件中的 defaultCheckpointDir

-acl

String

上传或复制对象时可指定的预定义访问策略。支持的值如下:

  • private
  • public-read
  • public-read-write
  • authenticated-read
  • bucket-owner-read
  • bucket-owner-full-control
  • bucket-owner-entrusted

-sc

Enum

上传对象时可指定的对象存储类型,取值说明如下:

  • STANDARD:标准存储,默认值。
  • IA:低频访问存储。
  • ARCHIVE_FR:归档闪回存储。
  • ARCHIVE:归档存储。
  • COLD_ARCHIVE:冷归档存储。
  • DEEP_COLD_ARCHIVE:深度冷归档存储。

说明

  • 当前华北2(北京)和华东2(上海)支持冷归档存储,华南1(广州)处于邀测状态,如您需要在华南1(广州)使用冷归档存储,请联系客户经理。
  • 当前仅华北2(北京)、华东2(上海)、华南1(广州)支持深度冷归档,且都处于邀测状态,如您需要使用该存储类型,请联系客户经理。

-meta

String

上传或复制对象时可指定的自定义元数据。

-sse

String

上传、复制对象时使用的服务端加密算法,支持的值:

  • aes256
  • kms

默认为配置文件中的 defaultSse。

-sseKeyId

String

上传、复制对象且指定服务端加密算法为 kms 时,使用的 kms 密钥,默认为配置文件中的 defaultSseKeyId。

-contentType

String

上传、复制对象时设置对象的 Content-Type。

-contentDisposition

String

上传、复制对象时设置对象的 Content-Disposition。

-contentEncoding

String

上传、复制对象时设置对象的 Content-Encoding。

-contentLanguage

String

上传、复制对象时设置对象的 Content-Language。

-cacheControl

String

上传、复制对象时设置对象的 Cache-Control。

-expires

String

上传、复制对象时设置对象的 Expires,格式为:YYYYMMDDHHmmSS。

-include

String

上传、下载或复制时对包含文件的名称匹配模式,支持以下字符:

  • ? :匹配单个任意字符。
  • * :匹配多个任意字符。
  • # :作为分隔符。

例如 -include=*.png#*.txt 表示匹配所有以 .png.txt 结尾的文件。

说明

  • 为了避免因操作系统转义特殊符号的导致的解析失败等问题,建议您使用引号设置名称匹配模式。
  • 名称匹配模式只在上传文件夹或文件列表时生效。
  • 名称匹配模式在文件全路径生效(包含文件名和文件目录)。

-exclude

String

上传、下载或复制时对不包含文件的名称匹配模式,支持以下字符:

  • ? :匹配单个任意字符。
  • * :匹配多个任意字符。
  • # :作为分隔符。

例如 -exclude=*.png#*.txt 表示匹配所有以 .png.txt 结尾的文件。

说明

  • 为了避免因操作系统转义特殊符号导致的解析失败等问题,建议您使用引号设置名称匹配模式。
  • 名称匹配模式只在上传文件夹或文件列表时生效。
  • 名称匹配模式在文件全路径生效(包含文件名和文件目录)。

-timeRange

String

上传、下载或复制时文件最后修改时间的时间段匹配模式,格式为:YYYYMMDDHHmmSS-YYYYMMDDHHmmSS

-at

Bool

上传文件夹中文件的最后访问时间满足 -timeRange 参数的文件列表。

-ddo

Bool

上传时文件夹本身不会作为单独一个对象上传。

-dmf

Bool

设置名称匹配模式 -include/-exclude 和时间段匹配模式 -timeRange 对文件夹不生效。

-arcDir

String

上传文件成功后的归档文件夹。

-fr

Bool

操作单个对象时生成结果清单文件。

-o

String

生成结果清单文件的文件夹,默认为配置文件中的 defaultOutputDir

使用示例

上传单个文件

以下命令用于将 /Users/Downloads/TOS/tosutil 文件夹中的 object 文件上传至 bucketname 存储桶,上传后文件名为 object

  • 命令

    ./tosutil cp /Users/Downloads/TOS/tosutil/object  tos://bucketname/object
    
  • 返回

    Start at 2022-10-27 10:49:12.407874 +0000 UTC
     
     
    Parallel:      1                   Jobs:          5                   
    Threshold:     100.00MB            PartSize:      auto                
    VerifyChecksum: false                         
    CheckpointDir: /.tosutil_checkpoint
     
    [-------------------------------------------] 100.00% ?/s 50.50KB/50.50KB 162ms
     
    Upload successfully, 50.50KB, n/a, /Users/Downloads/TOS/tosutil/object --> tos://bucketname/object, cost [164], status [200], request id [2643485a6228acbb635a6228-ac1173a1-1oo0Rk-PuO-cb-tos-bj-3]
    

上传文件夹

以下命令用于将 /Users/Downloads/TOS/tosutil 文件夹中的所有文件上传至 bucketname 存储桶,上传后文件夹命名为 cpfile

说明

该命令会上传文件夹本身,上传后所有的文件仍在 cpfile 文件夹内。

  • 命令

    ./tosutil cp /Users/Downloads/TOS/tosutil  tos://bucketname/cpfile -r
    
  • 返回

    Start at 2022-10-27 10:50:43.872787 +0000 UTC
     
     
    Parallel:      1                   Jobs:          5                   
    Threshold:     100.00MB            PartSize:      auto                
    VerifyChecksum: false                         
    CheckpointDir: /Users/.tosutil_checkpoint
    OutputDir: /Users/.tosutil_output
     
    [----------------------------] 100.00% tps:0.00 ?/s 4/4 181.45KB/181.45KB 183ms
    Succeed count is:   4         Failed count is:    0         
    Succeed bytes is:   181.45KB  
    Metrics [max cost:178 ms, min cost:103 ms, average cost:143.75 ms, average tps:21.62]
     
    Task id is: 34c8480e-55e5-11ed-806b-aa665a3c7f26
    

说明

更多上传场景的示例命令,请参见上传示例