文档首页/ 对象存储服务 OBS/ 工具指南（obsutil）（巴黎区域）/ 对象相关命令/ 增量同步上传对象
更新时间：2025-02-10 GMT+08:00
查看PDF
分享

增量同步上传对象

功能说明

将本地源路径下的所有内容同步到OBS指定目标桶，使两边内容保持一致。此处的增量同步有两层含义：

  1. 增量，依次比较源文件和目标对象，只上传存在变化的源文件。
  2. 同步，命令执行完成后，保证本地源路径是OBS指定目标桶的子集，即本地源路径下的所有文件均能在OBS指定目标桶中找到对应对象。
  • 同步上传时，请确保本地文件或文件夹在同步过程不发生变化，否则可能产生同步失败或者数据不一致的问题。
  • 同步上传每个文件时会对比桶中对应路径的对象，仅在对象不存在，或者对象大小与文件大小不一致，或者对象的最后修改时间早于文件的最后修改时间时进行上传。

命令结构

  • Windows操作系统
    • 同步上传文件 
      obsutil sync file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx]
    • 同步上传文件夹 
      obsutil sync folder_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-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]
  • macOS/Linux操作系统
    • 同步上传文件 
      ./obsutil sync file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx]
    • 同步上传文件夹 
      ./obsutil sync folder_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-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]

运行示例

  • 以Windows操作系统为例，运行obsutil sync d:\temp\test.txt obs://bucket-test/key，同步上传文件。 
    obsutil sync d:\temp\test.txt obs://bucket-test/key

Start at 2024-09-25 04:48:10.1147483 +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, d:\temp\test.txt --> obs://bucket-test/key, cost [55], status [200], request id [00000192421F4E224012B8470C0CCCDC]
  • 以Windows操作系统为例，运行obsutil sync d:\temp obs://bucket-test/temp ，同步上传文件夹。 
    obsutil sync d:\temp obs://bucket-test/temp

Start at 2024-09-25 04:48:10.1147483 +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:     xxxx
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

同步上传文件时必选

本地文件路径。

folder_url

同步上传文件夹时必选

本地文件夹路径。

bucket

必选

桶名。

key

可选

同步上传文件时的对象名/对象名前缀，或同步上传文件夹时的对象名前缀。

规则如下：

  • 同步上传文件时，如果该值为空，则将对象上传到桶的根目录，对象名为文件名。如果该值不为空，如果该值以“/”结尾，则以该值作为对象名前缀上传对象，对象名为该值+文件名；否则，将该值作为对象名进行上传；
  • 同步上传文件夹时，如果该值为空，则将桶的根目录下的所有对象与本地文件夹下的所有内容保持一致；如果该值不为空，则将对象名前缀为该值的所有对象与本地文件夹下的所有内容保持一致。
说明：
  • 同步上传文件夹时，如果该值不为空且不以“/”结尾，则工具会自动为该值末尾加上“/”作为对象名前缀。
  • 请参考同步上传示例理解该参数的使用方式。

fr

附加参数，同步上传文件时可选

同步上传文件时生成结果清单文件。

arcDir

附加参数，可选

同步上传文件成功后的归档路径，上传成功后的文件会移动到该路径下。

dryRun

附加参数，可选

测试模式运行，不执行实际的上传操作。

link

附加参数，可选

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

须知：
  • 如果未指定该参数，而待上传的文件是一个软链接且该软链接指向的目标文件不存在，则Windows操作系统会产生“The system cannot find the file specified”的上传失败异常，而macOS/Linux操作系统会产生“No such file or directory”的上传失败异常。
  • 文件夹软链接不能形成环，否则上传会以panic的形式退出；如果不希望产生panic，请在配置文件中配置panicForSymbolicLinkCircle为false。

vlength

附加参数，可选

同步上传完成后，验证上传到桶中对象的大小是否与本地文件大小一致。

vmd5

附加参数，可选

同步上传完成后，验证上传到桶中对象的MD5值是否与本地文件的MD5值一致。

说明：
  • 如果待上传的本地文件较大，使用该参数将会因为计算MD5而导致整体性能下降。
  • MD5值校验通过后，会将该值设置为对象元数据x-obs-meta-md5chksum，用于下载或复制时校验MD5。
注意：

如果您的业务涉及加密场景，请勿使用该参数。

p

附加参数，可选

每个分段上传任务的最大并发数，默认为配置文件中的defaultParallels。

threshold

附加参数，可选

开启分段上传任务的阈值，单位：字节，默认为配置文件中的defaultBigfileThreshold。

说明：
  • 如果待上传的文件小于该阈值，则使用直接上传模式；否则使用分段上传模式。
  • 直接上传模式不会产生断点记录文件，不支持断点续传。
  • 支持带容量单位配置，例如，配置1MB代表1048576字节。

acl

附加参数，可选

同步上传文件时可指定的预定义访问策略。支持的值：

  • private
  • public-read
  • public-read-write
  • bucket-owner-full-control
说明：

以上四个值分别对应：私有读写、公共读、公共读写、桶拥有者完全控制，四种预定义访问策略。

sc

附加参数，可选

同步上传文件时可指定的对象的存储类型。支持的值：

  • standard：标准存储，访问时延低、吞吐量高，适用于有大量热点文件（平均一个月多次）或小文件（小于1MB）。
  • warm：温存储，可用性略低于standard，适用于不频繁访问（平均一年少于12次）但在需要时也要求快速访问数据的业务场景。
  • cold：冷存储，安全、持久且成本极低，适用于很少访问（平均一年访问一次）数据的业务场景。

meta

附加参数，可选

上传文件时可指定的自定义元数据。格式为：key1:value1#key2:value2#key3:value3。

说明：

以上值表示上传文件完成后，桶内对象包含三组自定义元数据，分别为：key1:value1、key2:value2、key3:value3。

ps

附加参数，可选

每个分段上传任务的段大小，单位：字节，取值范围是100KB~5GB，默认为配置文件中的defaultPartSize。

说明：
  • 支持带容量单位配置，例如，配置1MB代表1048576字节。
  • 支持配置为auto，此时obsutil会根据源文件大小自动设置每个分段任务的段大小。

cpd

附加参数，可选

生成断点记录文件的文件夹，默认为运行obsutil命令的用户目录的子文件夹.obsutil_checkpoint。

说明：

每个分段上传任务会产生唯一对应的断点记录文件并保存至该文件夹的upload子文件夹下，分段任务执行成功后，对应的断点记录文件会被自动删除；分段任务执行失败或被中断后，下次执行该分段任务时会尝试通过对应的断点记录文件恢复任务。

j

附加参数，同步文件夹时可选

同步上传文件夹时批量任务的最大并发数，默认为配置文件中的defaultJobs。

说明：

工具会保证该值至少为1。

exclude

附加参数，同步文件夹时可选

不包含文件的匹配模式，如：*.txt。

说明：
  • 支持“*”匹配多个任意字符和“?”匹配单个任意字符，例如abc*.txt代表匹配以abc开头以.txt结尾的任意文件。
  • 您可以使用“\*”代表匹配“*”字符本身，使用“\?”代表匹配“?”字符本身。
  • 如果待上传的文件名匹配该参数，则跳过该文件的上传。
须知：
  • 建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。
  • 该匹配模式作用于文件全路径（含文件名和文件目录）。
  • 该匹配模式仅对文件夹中的文件生效。
  • 支持指定多个exclude参数，如-exclude=*.xxx -exclude=*.xxx

include

附加参数，同步文件夹时可选

包含文件的匹配模式，如：*.jpg。

说明：
  • 支持“*”匹配多个任意字符和“?”匹配单个任意字符。
  • 您可以使用“\*”代表匹配“*”字符本身，使用“\?”代表匹配“?”字符本身。
  • 首先执行exclude的匹配规则，如果待上传的文件名不匹配exclude，则判断待上传的文件名是否匹配该参数，如果匹配则上传该文件，否则跳过该文件的上传。
须知：
  • 建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。
  • 该匹配模式作用于文件全路径（含文件名和文件目录）。
  • 该匹配模式仅对文件夹中的文件生效。
  • 支持指定多个include参数，如-include=*.xxx -include=*.xxx

at

附加参数，同步上传文件夹时可选

同步上传文件时指定按照文件最后访问时间作为timeRange匹配模式，仅上传最后访问时间满足timeRange时间段的文件。

说明：
  • 需配合timeRange使用

disableDirObject

附加参数，同步上传多文件夹时可选

同步上传文件夹时，文件夹本身不会作为一个对象上传，在有很多空文件夹场景时候可以避免无用文件夹上传到对象存储桶中；文件夹下有文件时候，文件夹下文件依然会上传并保持原有路径格式，不受影响。

timeRange

附加参数，同步上传文件夹时可选

同步上传文件时的时间段匹配模式，仅上传最后修改时间在该时间段内的文件。

该匹配模式优先级低于文件名匹配模式：exclude和include，优先执行文件名匹配模式后才会执行该匹配模式。

说明：
  • 使用“time1-time2”，代表匹配的时间段，其中time1必须小于等于time2，格式为yyyyMMddHHmmss。
  • 时间格式支持自动补全，例如yyyyMMdd等价于yyyyMMdd000000，yyyyMM等价于yyyyMM01000000。
  • 使用“*-time2”，代表匹配最后修改时间在time2之前的所有文件，使用“time1-*”，代表匹配最后修改时间time1之后的所有文件。
须知：

该匹配模式表示的时间是UTC时间。

mf

附加参数，可选

设置名称匹配模式（include、exclude）和时间匹配模式（timeRange）对文件夹也生效。

o

附加参数，可选

生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果、失败结果和警告结果三个文件），默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。

说明：
  • 结果清单文件命名规则：sync_{succeed | failed | warning}_report_时间_TaskId.txt。
  • 单个结果清单文件默认情况下最大为30MB且最大可保留的文件个数为1024，可在配置文件中通过recordMaxLogSize和recordBackups分别配置。
  • 当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件"sync_failed_report_时间_TaskId.txt"及日志路径下的日志文件；

config

附加参数，可选

运行当前命令时的自定义配置文件，可支持的配置参数请参考配置参数说明。

响应结果

请参考上传对象的响应结果。

父主题： 对象相关命令