文档首页/ 对象存储服务 OBS/ 用户指南/ 对象管理/ 上传对象/ 多段上传

更新时间：2026-10-30 GMT+08:00

多段上传

使用场景

多段上传将单个对象拆分为多个分段分别上传，当对象的所有分段都上传后，OBS将这些段合并起来，然后创建对象。一般而言，如果您的对象大小达到了100MB，应考虑使用多段上传，而不是使用简单上传。使用多段上传具有以下优势：

提高吞吐量：多个分段并行上传可以提高上传速度，最大限度地利用您的带宽。
更好地适应网络波动：如果某一个分段因为网络原因上传失败，只需要重新上传该分段即可，无需重新上传整个对象，帮助您节省时间和流量。
在未知对象大小之前开始上传：如果您在上传对象时无法确认对象的最终大小，例如视频监控场景下，视频文件是实时生成并上传的，这种情况下可使用分段上传。

约束与限制

文件夹不支持多段上传。
一个请求只能上传一个段，可以同时发起多个请求。

分段相关限制：

表1 分段相关限制
项目	限制
对象大小	最大48.8TB
每次上传的段的数量	最大10000
段编号	1到10000（含）
段大小	5MB到5GB，最后一个段大小是0到5GB
列举已上传的段请求返回的段数量	最大1000
列举已初始化多段任务请求返回的任务数量	最大1000

如果您使用SSE-C加密（用户提供密钥），需要在初始化上传段任务、上传段、拷贝段的过程中携带密钥信息，且同一个任务内的多段操作，携带的密钥必须保持一致。合并段无需携带密钥，合并后的对象是一个使用SSE-C方式加密的对象。
如果您使用SSE-KMS或者SSE-OBS加密方式，只需要在初始化上传段任务时配置好加密方式、算法和密钥信息。

费用说明

如果要上传深度归档对象，且上传数量较多的时候，为了降低PUT类请求费用，建议您先使用标准存储进行上传，然后通过生命周期规则将其转储为深度归档类型。
初始化上传段任务并上传一个或多个段之后，您必须合并段或取消多段上传任务，OBS才能释放已上传段的存储空间，并停止向您收取已上传段的存储空间费用。

权限说明

执行多段上传相关操作前，您需要按照下表获取相关权限：

操作	所需权限
初始化上传段任务	您必须是桶拥有者或者拥有PutObject权限。
上传段	您必须是桶拥有者或者拥有PutObject操作的权限。
合并段	您必须是桶拥有者或者拥有PutObject操作的权限。
拷贝段	您必须是桶拥有者或者拥有PutObject、GetObject操作的权限。
列举已上传的段	您必须是桶拥有者或者拥有ListMultipartUploadParts权限。
列举多段上传任务	您必须是桶拥有者或者拥有ListBucketMultipartUploads权限。
取消多段上传任务	您必须是桶拥有者或者拥有AbortMultipartUpload权限。

注意事项

如果上传过程中本地文件发生了改变，则需要重新上传所有分段。
多并发上传同一对象的同一段时，服务端遵循Last Write Win策略，但“Last Write”的时间定义为段元数据创建时间。为了保证数据准确性，客户端需要加锁保证同一对象的同名段上传的并发性。同一对象的不同段并发上传不需要加锁。

上传大量对象时，不要使用顺序前缀（如时间戳或字母顺序）的对象名。因为顺序前缀命名可能会出现大量对象索引集中存储于存储空间中某个特定分区的情况。此时如果请求速率过大，会导致请求速率下降。
建议您开启多版本控制功能防止同名对象被意外覆盖。开启后，被覆盖的对象会以历史版本的形式保存下来，您可以随时恢复历史版本对象。

多段上传流程

图1 多段上传流程图

表2 多段上传流程
序号	操作	说明
1	文件分段	在本地客户端将大文件进行分段处理，单个分段的大小限制为5MB到5GB，最后一个段大小限制是0到5GB。
2	初始化上传段任务	初始化上传任务并获取任务ID，后续的上传段、合并段、列举段等操作都需要携带这个ID，以表明这些操作都归属于指定ID的分段任务。初始化阶段还会设置对象的多个属性，例如对象的存储类别、对象ACL等。后续的上传段、合并段无需再重复设置这些属性。
3	上传段	上传分段，每一个分段都可以独立上传，并且可以按照任意顺序上传。如果您的网络状况良好，可以使用并发上传以提高速度并充分利用带宽。如果任意分段传输失败，只需重新传输该分段且不会影响其它分段。如需取消上传，请使用取消多段上传任务接口取消上传并删除已上传至桶中的分段。
4	合并段	当所有分段都成功上传后，开始合并段，将多个分段合并成一个完整的对象。

多段上传使用方式

OBS管理控制台、OBS Browser+、obsutil将详细的多段上传步骤进行了封装，您无需感知具体步骤，只需使用界面或者命令行直接上传即可，详情参见使用OBS控制台多段上传、使用图形化工具OBS Browser+多段上传、使用命令行工具obsutil多段上传，使用SDK参见使用SDK多段上传。为了帮助您理解多段上传的流程，此处使用API Explorer工具调用OBS API，为您详细演示的使用API多段上传的完整过程：

使用API多段上传

步骤一：文件分段

在本地客户端对文件进行分段处理。

【可选】创建指定大小的文件。此处我们构造一个20M大小的文件test.file，如果您已经准备好待上传的文件，可以跳过此步骤。

Linux或macOS环境：
```
dd if=/dev/urandom of=test.file bs=1M count=20
```
Windows环境下打开命令提示符cmd，执行以下命令：
```
fsutil file createnew test.file 20971520
```

将文件进行分段。此处将20M大小的test.file文件，分为5个4M大小的分段，分段名为test-part**，**为00至04的数字后缀。

Linux或macOS环境：

split -b 4M -d test.file test-part

其中，-b表示每个分段大小的最大值，-d表示分段名称使用数字作为后缀，如：test-part00。

Windows环境，请使用PowerShell运行以下命令：

$inputFile = "test.file"
$outputFilePrefix = "test-part"
$chunkSize = 4MB

$fs = [System.IO.File]::OpenRead($inputFile)
$buffer = New-Object byte[] $chunkSize
$fileNumber = 0

while ($fs.Position -lt $fs.Length) {
$bytesRead = $fs.Read($buffer, 0, $chunkSize)
$outputFile = "{0}{1:D2}" -f $outputFilePrefix, $fileNumber
$fileStream = [System.IO.File]::Create($outputFile)
$fileStream.Write($buffer, 0, $bytesRead)
$fileStream.Close()
$fileNumber++
}

$fs.Close()

拆分完成后，您能在执行该命令的目录中看到各个分段。每个分段都有一个与其分段编号对应的后缀，例如：

步骤二：初始化上传段任务

调用初始化上传段任务接口，获取多段上传任务ID。

进入API Explorer的初始化上传段任务接口调试页面。

填写API调用参数。

参数名称	示例	说明
object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字。
bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶。
uploads	置为空值	该参数表明本次API调用是一个分段上传任务，而不是普通的POST上传。单击“置为空值”将参数置空。

单击“调试”。
调用成功后，可在页面右下角查看响应结果，得到任务ID。

如图所示本次任务的ID为“000001987D77252A002424CADFB90B1C”

步骤三：上传段

将步骤一中拆分的文件分段上传至桶中。

进入API Explorer的上传段接口调试页面。

填写API调用参数。

点击放大

参数名称	示例	说明
object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
partNumber	1	上传段的段编号，取值为从1到10000的整数。注意，段编号唯一地标示了段及其位置，每个段必须按照在对象中的位置有序编号，比如20M的对象分成5段，第一段编号为1，第二段编号为2。如果您使用之前上传的段的同一段编号上传新段，则之前上传的段将被覆盖。
uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。
Body	test-part00	分段文件。单击参数框右侧的，选择分段文件。

单击“调试”。
调用成功后，右侧调试结果页签会提示“调用成功”，可在页面右下角查看响应结果，响应结果中包含该段的ETag值。
重复2~3，完成所有分段的上传。

完成上传后，调用列举已上传的段接口，填写参数后单击“调试”，查看所有已上传的段。

参数名称	示例	说明
object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。

检查分段是否都上传成功，并获取所有段的段号和ETag值。

如果6中列举段接口响应结果包含所有分段，说明所有分段都上传成功，此时请记录响应结果中所有段的段编号和ETag值，这些值将作为下一步合并段的请求参数。

步骤四：合并段

本步骤将上传至桶中的分段合并成一个完整的对象。

进入API Explorer的合并段接口调试页面。

填写API调用参数。

参数名称	示例	说明
object_key	test.file	对象名，上传成功后桶内对象的名字，是整个对象的名字，不是分段名字，与初始化中填写的对象名一致。
bucket_name	example-bucket-a-intl	桶名，请单击选择对象要上传的桶，与初始化中填写的桶名一致。
uploadId	000001987D77252A002424CADFB90B1C	上传任务ID，与初始化中获取的任务ID保持一致。
Body	<CompleteMultipartUpload> <Part> <PartNumber>1</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f6877"</ETag> </Part> <Part> <PartNumber>2</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f8678"</ETag> </Part> <Part> <PartNumber>3</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7687"</ETag> </Part> <Part> <PartNumber>4</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7876"</ETag> </Part> <Part> <PartNumber>5</PartNumber> <ETag>"ef0bff811bdb99fb44804719bd0f7786"</ETag> </Part> </CompleteMultipartUpload>	任务中所有分段的段信息和ETag值，您可以待所有分段都上传后，调用列举段接口批量获取，参见7。或者每上传一个段，在响应结果中获取，参见4。注意：如果合并段时，遗漏了某个段，那么未被合并的段将会被系统自动删除且不可恢复。例如上传了10个段，但合并时只选择了9个段进行合并，那么遗漏的一个段会被删除且不可恢复。所以合并段前请列出已上传的段，仔细核对所有段，确保没有段被遗漏。

单击“调试”。
调用成功后，右侧调试结果页签会提示“调用成功”，响应结果会返回最终的对象名、桶名和完整对象的ETag值：

使用OBS控制台多段上传

对象大于8M时管理控制台会自动使用多段上传。控制台将详细的多段上传步骤进行了封装，您无需感知具体步骤，使用界面直接上传即可。

在OBS管理控制台左侧导航栏选择“桶列表”。
在OBS管理控制台桶列表中，单击待操作的桶，进入“对象”页面。
在对象列表页，单击“上传对象”，系统弹出“上传对象”对话框。

也可以进入待上传文件的文件夹，单击“上传对象”。

此处以批量上传为例。仅支持单个上传的区域请根据界面提示进行操作。

如果待上传至OBS的文件存放在Microsoft OneDrive中，建议这些待上传文件的名称不要超过32位，以保证兼容性。

图2 上传对象
指定对象的存储类别。如果不指定，默认与桶的存储类别一致。

对象存储类别和桶存储类别可以不一致。上传对象时，对象的存储类别默认继承桶的存储类别，您也可以重新指定对象的存储类别，同时也支持在对象上传完成后修改对象的存储类别。
拖拽本地文件或文件夹至“上传对象”区域框内添加待上传的文件。

也可以通过单击“上传对象”区域框内的“添加文件”，选择本地文件进行添加。
服务端加密：选择“不开启加密”、“SSE-KMS”或“SSE-OBS”。详情请参见服务端加密。

如果桶配置了服务端加密，上传对象时您可以选择“继承桶的加密配置”。
可选：如果您需要配置元数据、保留策略、对象标签，可单击“（可选）高级配置”进行配置。

当桶开启了WORM功能，高级配置才支持配置WORM保留策略。

配置元数据：可配置的对象元数据包括：ContentDisposition、ContentLanguage、WebsiteRedirectLocation、ContentEncoding、ContentType。各元数据具体含义请参见OBS元数据。元数据是一组名称值对，包括名称和值，值不能为空。如需配置多个元数据，单击“添加”即可新增。

保留策略：可选择“继承桶保留策略”或者选择“配置”后输入保留期，自动保护上传到此存储桶的新对象，保证其在指定时间点前不被删除。

配置标签：通过使用标签来标识对象。输入标签键和值。关于标签相关内容，具体请参见对象标签。

图3 配置元数据或WORM保留策略
如果您需要配置元数据，可单击“(Optional) Configure Advanced Settings”，添加元数据。
单击“确定”。

使用SDK多段上传

使用图形化工具OBS Browser+多段上传

大于50M的对象OBS Browser+会在后台自动转换为断点续传（本质上是分段上传）。您无需感知后台的切换动作，使用工具直接上传即可。

登录OBS Browser+。
单击想要上传文件或文件夹的桶。
单击“上传”，并选择“添加文件”或“添加文件夹”，如图4所示。

图4 上传文件或文件夹

使用“添加文件”功能上传对象时，为了更好的体验，建议您最多同时选择100个文件进行上传，如果超过此限制，建议将多个文件放在文件夹中，然后使用“添加文件夹”功能进行上传。
1. 如果上传文件时弹出“Service Unavailable”的错误提示，则可能是因为当前服务器繁忙，请稍后重试。
2. 如果上传文件或文件夹时弹出拒绝访问的错误提示，则有可能是如下几种情况导致的：
- 通过桶的ACL设置功能，限制了该桶的访问权限（如：该用户无桶的写入权限）。
- 通过桶的桶策略功能，限制了该桶的访问权限(如:当前时间段不允许对桶进行写入、该用户无桶的写入权限等)。
  请检查桶的ACL设置和桶策略配置，排查错误。
文件必须有访问权限才可以上传，否则上传任务会失败。
在弹出的对话框中，选中需要上传的文件或文件夹后单击“打开”。

客户端支持一次上传一个文件夹，或一次同时上传多个文件。上传多个文件时，按住“Ctrl”或“Shift”同时选择多个文件即可，同时支持“Ctrl+A”全选操作。操作习惯与Windows操作系统上的操作习惯保持一致。
单击“确定”。

使用命令行工具obsutil多段上传

大于50M的对象obsutil会在后台自动转换为断点续传（本质上是分段上传）。您无需感知后台的切换动作，使用工具直接上传即可。

命令结构：

Windows操作系统

上传文件

obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

上传文件夹

obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

多文件/文件夹上传

obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

命令中的“/prefix”即为上传文件夹时的对象名前缀。运行示例请参见上传示例。

Linux/Mac操作系统

上传文件

./obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

上传文件夹

./obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

多文件/文件夹上传

./obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

命令中的“/prefix”即为上传文件夹时的对象名前缀。运行示例请参见上传示例。

运行示例：

以Windows操作系统为例，运行obsutil cp d:\temp\test.txt obs://bucket-test/key，将D盘temp路径下名为test.txt的文件上传至bucket-test桶中，并且重命名为key。

obsutil cp d:\temp\test.txt obs://bucket-test/key
Start at 2024-09-30 08:11:41.6724827 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint

[====================================================] 100.00% 1.68 MB/s 8.46MB/8.46MB 5s
Upload successfully, 8.46MB, n/a, d:\temp\test.txt --> obs://bucket-test/key, cost [5], status [200], request id [0000016979E1D2B2860BB5181229C72C]

以Windows操作系统为例，运行obsutil cp d:\temp obs://bucket-test -f -r，递归上传D盘temp文件夹中的所有文件和子文件夹至bucket-test桶的temp文件夹中。

obsutil cp d:\temp obs://bucket-test -f -r
Start at 2024-09-30 08:14:12.1406275 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
OutputDir: C:\Users\Administrator\.obsutil_output

[========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s
Succeed count:   5         Failed count:    0
Succeed bytes:      xxx
Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71, transferred size: 7.20MB]

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed

更多运行示例，请参见常见示例。

参数说明：

参数	约束	描述
file_url	多文件/文件夹上传时可选上传文件时必选	本地文件路径。多文件/文件夹上传时，禁止路径嵌套，例如：/a/b/c和/a/b/。多文件/文件夹上传时，必须配置msm=1，此时可以用英文逗号分隔多个文件，例如：file_url1,file_url2。多文件/文件夹上传时，文件和文件夹可以同时存在，例如：file_url1,folder_url1,file_url2,folder_url2。
folder_url	多文件/文件夹上传时可选上传文件夹时必选	本地文件夹路径。上传文件夹时，如果未设置flat选项，则直接上传整个文件夹；如果设置了flat选项，则上传文件夹下的所有内容。多文件/文件夹上传时，禁止路径嵌套，例如：/a/b/c和/a/b/。多文件/文件夹上传时，必须配置msm=1，此时可以用逗号分隔多个文件夹，例如：folder_url1,folder_url2。多文件/文件夹上传时，文件和文件夹可以同时存在，例如：file_url1,folder_url1,file_url2,folder_url2。
filelist_url	多文件/文件夹上传时可选	包含待上传文件/文件夹列表的文件，必须配置msm=2。该文件为普通文本文件（如.txt文件、.csv文件），文件中的每行代表一个待上传的文件/文件夹，例如： file_url1 file_url2 folder_url1 folder_url2 文件中待上传的文件/文件夹禁止路径嵌套，例如：/a/b/c和/a/b/。
bucket	必选	上传文件/文件夹所属的桶的名称。
key	可选	上传文件时的对象名或对象名前缀，或上传文件夹时的对象名前缀。在上传文件或文件夹时，根据指定值的不同情况，对象的上传路径和名称如下：如果该值为空：对象将上传到桶的根目录（存储桶的顶级目录），对象名将使用所上传文件或文件夹的名称。如果该值不为空：如果该值以“/”结尾：对象将上传到该值指定的目录下，对象名将为“该值+文件名”，如：folder/filename.txt和folder/foldername。如果该值不以“/”结尾：对于文件，其名称将直接使用该值，如：filename.txt；对于文件夹，将上传到以该值加上“/”结尾的目录下。如：folder/。说明：您还可以参考上传示例理解该参数的使用方式。
fr	附加参数，上传文件时可选	上传文件时生成结果清单文件。
flat	附加参数，多文件/文件夹上传或上传文件夹时可选	上传文件夹时，只上传该文件夹下的所有内容。
arcDir	附加参数，可选	上传文件成功后的归档路径，上传成功后的文件会移动到该路径下。
dryRun	附加参数，可选	测试模式运行，不执行实际的上传操作。
u	附加参数，可选	增量上传操作。设置该参数后，上传每个文件时会对比桶中对应路径的对象，仅在对象不存在，或者对象大小与所上传文件大小不一致，或者对象的最后修改时间早于所上传文件的最后修改时间时进行上传。在比较每个本地文件与桶内对象差异时，会产生一次HEAD请求费用。说明：该参数可以与-last-modify-only搭配使用，具体效果查看-last-modify-only的描述说明。
-last-modify-only	附加参数，可选	对比逻辑仅比较目标对象是否存在和对象的修改时间，并针对最后更新的对象进行增量操作。说明：该参数与-u搭配使用，单独使用并不生效。
vlength	附加参数，可选	上传完成后，验证桶中对象的大小是否与本地文件大小一致。
vmd5	附加参数，可选	上传完成后，验证桶中对象的MD5值是否与本地文件的MD5值一致。如果您的业务涉及加密场景，请勿使用该参数。如果待上传的本地文件较大，使用该参数将会因为计算MD5而导致整体性能下降。 MD5值校验通过后，会将该值设置为对象元数据x-obs-meta-md5chksum，用于下载或复制时校验MD5。了解更多请参见基于crc64或MD5的OBS数据完整性校验，了解几种数据校验方式的区别请参见几种校验对象数据完整性的方式。
p	附加参数，可选	每个分段上传任务的最大并发数。默认为配置文件中的defaultParallels。
threshold	附加参数，可选	开启分段上传任务的阈值。如果待上传的文件小于该阈值，则使用直接上传模式；否则使用分段上传模式。默认为配置文件中的defaultBigfileThreshold。单位：字节支持带容量单位配置，例如：配置1MB代表1048576字节。说明：直接上传模式不会产生断点记录文件，不支持断点续传。
acl	附加参数，可选	上传文件时可指定对象的预定义访问策略。支持的值： private：私有读写，除对象ACL授权外的其他用户无对象的访问权限。 public-read：公共读，任何用户都可以对桶内对象进行读操作。 public-read-write：公共读写，任何用户都可以对桶内对象进行读/写/删除操作。 bucket-owner-full-control：桶拥有者完全控制，其他任何人都没有访问权限。
sc	附加参数，可选	上传文件时可指定的对象的存储类型。支持的值： standard：标准存储，访问时延低、吞吐量高，适用于有大量热点文件（平均一个月多次）或小文件（小于1MB）。 warm：低频访问存储，可用性略低于standard，适用于不频繁访问（平均一年少于12次）但在需要时也要求快速访问数据的业务场景。 cold：归档存储，安全、持久且成本极低，适用于很少访问（平均一年访问一次）数据的业务场景。 deep-archive：深度归档存储，适用于长期不访问（平均几年访问一次）数据的业务场景，其成本相比归档存储更低，但相应的数据恢复时间将更长，一般为数小时。
meta	附加参数，可选	上传文件时可指定的标准和自定义元数据。标准元数据包括：Content-Type、Content-Encoding、Cache-Control、Content-Disposition、Content-Language、Expires。自定义元数据格式为：key:value，多个自定义元数据使用#链接。例如key1:value1#key2:value2#key3:value3，其含义是，上传文件后，桶内目标对象包含三组自定义元数据，分别为：key1:value1、key2:value2、key3:value3。
ps	附加参数，可选	每个分段上传任务的段大小。默认为配置文件中的defaultPartSize，支持配置为auto，此时obsutil会根据源文件大小自动设置每个分段任务的段大小。取值范围：100KB~5GB 单位：字节。支持带容量单位配置，例如，配置1MB代表1048576字节。
cpd	附加参数，可选	生成断点记录文件的文件夹，默认为运行obsutil命令的用户目录的子文件夹.obsutil_checkpoint。每个分段上传任务会产生唯一对应的断点记录文件并保存至该文件夹的upload子文件夹下。分段任务执行成功后，对应的断点记录文件会被自动删除；分段任务执行失败或被中断后，下次执行该分段任务时会尝试通过对应的断点记录文件恢复任务。
r	附加参数，上传文件夹时必选多文件上传时可选	递归上传文件夹中的所有文件和子文件夹。
f	附加参数，多文件/文件夹上传或上传文件夹时可选	强制操作，不进行询问提示。
j	附加参数，多文件/文件夹上传或上传文件夹时可选	上传文件夹时批量任务的最大并发数，默认为配置文件中的defaultJobs。说明：工具会保证该值至少为1。
msm	附加参数，多文件/文件夹上传时必选	开启多文件/文件夹上传模式，支持的值：[1\|2]。如果msm=1，则代表上传的URL是一组文件/文件夹列表（以英文逗号分隔）。如果msm=2，则代表上传的URL是一个包含文件/文件夹列表的文件。如果文件/文件夹名本身包含英文逗号，请不要使用“msm=1”的模式。如果没有设置r参数，则列表中的文件夹不会被上传。
exclude	附加参数，多文件/文件夹上传或上传文件夹时可选	不包含文件的匹配模式，设置该参数后，如果待上传的文件名匹配该参数，则跳过该文件的上传。如：.txt，代表所有后缀为.txt的文件自动跳过，不上传。 “”匹配多个任意字符，如：“abc.txt”表示匹配所有以“abc”开头，中间可以包含任意数量的任意字符，以“.txt”结尾的文件名。 “?”匹配单个任意字符，如：“abc?.txt”表示匹配所有以“abc”开头，中间包含1个任意字符，以“.txt”结尾的文件名。您可以使用“\”代表匹配“”字符本身，使用“\?”代表匹配“?”字符本身。支持指定多个exclude参数，如 -exclude=.xxx -exclude=.xxx 约束限制：* 该匹配模式仅对文件夹中的文件生效。说明：建议使用引号传递该匹配模式（Linux/Mac操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。该匹配模式作用于文件全路径（含文件名和文件目录）。
include	附加参数，多文件/文件夹上传或上传文件夹时可选	包含文件的匹配模式，设置该参数后，如果待上传的文件名匹配该参数，则上传该文件。如：.txt，代表所有后缀为.txt的文件将会被上传。 “”匹配多个任意字符，如：“abc.txt”表示匹配所有以“abc”开头，中间可以包含任意数量的任意字符，以“.txt”结尾的文件名。 “?”匹配单个任意字符，如：“abc?.txt”表示匹配所有以“abc”开头，中间包含1个任意字符，以“.txt”结尾的文件名。您可以使用“\”代表匹配“”字符本身，使用“\?”代表匹配“?”字符本身。支持指定多个include参数，如 -include=.xxx -include=.xxx 约束限制：* 该匹配模式仅对文件夹中的文件生效。如果同时配置了exclude和include参数，则首先执行exclude的匹配规则，如果待上传的文件名不匹配exclude参数，则判断待上传的文件名是否匹配include参数，如果匹配则上传该文件，否则跳过该文件的上传。示例： ./obsutil cp /localpath/ obs://test/ -include=/localpath/2022-12-09/* -f -r 以上命令的含义是：上传本地路径localpath下符合匹配规则的文件到test桶下，匹配规则是以“/localpath/2022-12-09/”开头的。说明：建议使用引号传递该匹配模式（Linux/Mac操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。该匹配模式作用于文件全路径（含文件名和文件目录）。
at	附加参数，多文件/文件夹上传或上传文件夹时可选	指定按照文件最后访问时间作为timeRange匹配模式，仅上传最后访问时间满足timeRange时间段的文件。该参数需配合timeRange参数使用。
disableDirObject	附加参数，多文件夹上传时可选	上传文件夹时，文件夹本身不会作为一个单独的对象上传，因此在有很多空文件夹的情况下，可以避免无用的文件夹上传到对象存储桶中。如果文件夹下有文件，这些文件会按原有路径格式上传，文件夹结构不受影响。
timeRange	附加参数，多文件/文件夹上传或上传文件夹时可选	上传文件时的时间段匹配模式，仅上传最后修改时间在该时间段内的文件。该匹配模式优先级低于文件名匹配模式：exclude和include，即优先执行exclude和include参数匹配，然后执行该匹配模式。该匹配模式表示的时间是UTC时间。使用“time1-time2”，代表匹配的时间段，其中time1必须小于等于time2，格式为yyyyMMddHHmmss。时间格式支持自动补全，例如：yyyyMMdd等价于yyyyMMdd000000，yyyyMM等价于yyyyMM01000000。使用“-time2”，代表匹配最后修改时间在time2之前的所有文件，使用“time1-”，代表匹配最后修改时间time1之后的所有文件。
mf	附加参数，可选	设置名称匹配模式（include、exclude）和时间匹配模式（timeRange）对文件夹也生效。
o	附加参数，可选	生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果、失败结果、警告结果三个文件）。默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。结果清单文件命名规则：cp_{succeed \| failed \| warning}_report_时间_TaskId.txt。单个结果清单文件默认情况下最大为30MB，可在配置文件中通过recordMaxLogSize分别配置。单个结果清单文件默认情况下最多可保留1024个文件，可在配置文件中通过recordBackups分别配置。当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件“cp_failed_report_时间_TaskId.txt”和日志路径下的日志文件。
bucket-cname	附加参数，可选	指定桶绑定的自定义域名说明： Util 5.7.9版本及以上支持该参数。
config	附加参数，可选	运行当前命令时的自定义配置文件。可支持的配置参数请参考配置参数说明。
e	附加参数，可选	指定终端节点。
i	附加参数，可选	指定用户的AK。
k	附加参数，可选	指定用户的SK。
t	附加参数，可选	指定用户的securitytoken。

响应结果：

字段名	描述
Parallel	请求中的-p参数。
Jobs	请求中的-j参数。
Threshold	请求中的-threshold参数。
PartSize	请求中的-ps参数。
Exclude	请求中的-exclude参数。
Include	请求中的-include参数。
TimeRange	请求中的-timeRange参数。
VerifyLength	请求中的-vlength参数。
VerifyMd5	请求中的-vmd5参数。
CheckpointDir	请求中的-cpd参数。
OutputDir	请求中的-o参数。
ArcDir	请求中的-arcDir参数。
Succeed count	成功的任务数。
Failed count	失败的任务数。
Skip count	增量上传/下载/复制、同步上传/下载/复制跳过的任务数。说明：跳过的任务数也会记录到成功的任务数中。
Warning count	执行完成但包含警告的任务数。说明：产生警告的任务可能是失败的也可能是成功的，需要根据成功或失败的结果清单进一步判断。产生警告的任务数与成功/失败任务数是相互独立的，总任务数仍是成功的任务数+失败的任务数。
Succeed bytes	成功上传的字节数。
max cost	所有任务中的最长耗时，单位：毫秒。
min cost	所有任务中的最短耗时，单位：毫秒。
average cost	平均耗时，单位：毫秒。
average tps	平均每秒的任务完成个数。
Task id	每次运行的唯一标识号，用于查找批量任务生成的结果清单文件。

列举桶中已初始化多段任务

什么是已初始化的多段任务：指初始化后还未合并以及未取消的多段上传任务。

列举的原理：调用该接口会获得桶中所有已初始化但未合并、未取消的多段上传任务列表。每个请求最多返回1000个多段上传任务，如果正在进行的多段上传任务超过1000个，您需要发送其他请求以检索剩余的多段上传任务。

如何列举：

列举已上传未合并的段

什么是已上传未合并的段：指已成功上传到桶中但是未进行合并的分段。

列举的原理：列出指定任务已上传但未合并的分段，OBS将返回特定任务的分段信息，每个请求最多返回1000个分段。如果分段超过1000个，您必须发送一系列请求以列举所有段。请注意，返回的分段列表不包括已合并的分段。

如何列举：

控制台：
1. 在OBS管理控制台左侧导航栏选择“桶列表”
2. 单击要查看的桶，进入“对象”页面。
3. 单击“碎片”页签，即可查看桶内所有分段。
OBS Browser+：碎片管理
API：列举已上传未合并的段
SDK：

拷贝段

什么是拷贝段：多段上传任务创建后，用户可以通过指定多段上传任务ID，为特定的任务调用拷贝段接口，将桶中已上传对象的一部分或全部拷贝为段。

拷贝段的原理：将源对象A拷贝为段part1，如果在拷贝前part1已存在，拷贝后老段数据part1会被新拷贝的段数据覆盖。拷贝成功后，只能列举到最新的段part1，老段数据将会被删除。因此拷贝段前请确保目标段不存在或者已无价值，避免因拷贝段导致数据误删除。拷贝过程中源对象A不会受到任何影响。

如何拷贝段：

obsutil：复制对象
API：拷贝段
SDK：

如何判断拷贝段是否成功：拷贝段成功的标志是响应消息的body中包含段的ETag值，否则拷贝失败。拷贝段接口返回状态码200并不代表拷贝成功，只是代表服务端已经收到请求，且开始处理拷贝段请求。

取消多段上传任务

取消多段上传任务的原理：取消多段上传任务之后无法再次使用任务ID上传任何段。取消后OBS将释放任务中每个段的存储空间。如果有分段正在上传过程中，即使您已执行取消多段上传操作，它们仍可以上传成功或失败。如果要释放所有分段使用的存储空间，建议等待分段全部上传完成后再取消多段上传任务。

如何取消多段上传任务：

多段上传最佳实践

合理控制并发数，兼顾速度与稳定
多段上传可通过并发分段提升传输速度，但并非并发越多越好。过多并发会增加系统负载、引发网络拥塞，反而降低上传速度；过少则无法充分利用带宽资源。建议根据网络带宽和设备性能动态确定合理的并发分段数量。
避免使用顺序前缀给对象命名
OBS按照对象名的UTF-8编码范围来进行分区管理。如果用户在对象命名规则上使用了顺序前缀（如时间戳或字母顺序），可能导致大量对象的请求访问集中于某个特定分区，造成访问热点。热点分区上的请求速率受限，访问时延会上升。推荐使用随机前缀对象名，这样请求就会均匀分布在多个分区，达到水平扩展的效果，详见OBS性能优化建议。
利用断点续传，保障可靠传输
多段上传任务无过期时间限制，支持暂停与恢复。每个上传任务以Upload ID为唯一标识，当某个分段因网络抖动或设备故障上传失败时，只需重传该分段，无需从头上传整个文件，从而提升传输效率。

多段上传

使用场景

约束与限制

费用说明

权限说明

注意事项

多段上传流程

多段上传使用方式

使用API多段上传

使用OBS控制台多段上传

使用SDK多段上传

使用图形化工具OBS Browser+多段上传

使用命令行工具obsutil多段上传

相关操作

列举桶中已初始化多段任务

列举已上传未合并的段

拷贝段

取消多段上传任务

多段上传最佳实践

相关文档

您对此文档页面的整体评价？