文档首页/ 对象存储服务 OBS/ 工具指南/ obsutil/ 对象相关命令/ 增量同步删除上传对象
更新时间：2026-08-05 GMT+08:00
查看PDF
分享

增量同步删除上传对象

功能说明

在增量同步上传的基础上，删除OBS目标桶中在本地源路径下已不存在的对象，使本地源路径与OBS目标桶的内容完全一致。此处的增量同步删除有三层含义：

  1. 增量，依次比较源文件和目标对象，只上传存在变化的源文件。
  2. 同步，命令执行完成后，保证本地源路径是OBS指定目标桶的子集，即本地源路径下的所有文件均能在OBS指定目标桶中找到对应对象。
  3. 删除，命令执行完成后，OBS目标桶中在本地源路径下没有对应文件的对象将被删除，即目标桶中多余的对象将被清除。
  • 同步删除上传时，请确保本地文件或文件夹在同步过程不发生变化，否则可能产生同步失败或者数据不一致的问题。
  • 同步上传每个文件时会对比桶中对应路径的对象，仅在对象不存在，或者对象大小与文件大小不一致，或者对象的最后修改时间早于文件的最后修改时间时进行上传。
  • 使用-delete参数会删除OBS桶中的对象，该操作不可逆，请谨慎使用。建议在执行删除前，先使用-dryRun参数进行测试，确认待删除的对象列表是否符合预期。
  • 如果源路径为空目录，命令将拒绝执行并报错，以防止误删除桶内全部对象。
  • 如果目标桶未开启版本控制，被删除的对象将无法恢复。建议开启桶版本控制以防止数据误删除。
  • 如果未指定目标对象名前缀（key），命令将扫描整个桶并可能删除桶内所有不在本地源路径中的对象，请务必确认后再执行。
  • 使用-delete参数时，命令会在执行删除前要求确认；如需跳过确认，请配合-f参数使用。

在比较每个本地文件与桶内对象差异时，会产生一次HEAD请求费用。在扫描目标桶中待删除对象时，会产生LIST请求费用。

命令结构

  • sync命令

    sync命令自带增量同步能力，直接使用-delete参数即可：

    • Windows操作系统 
      obsutil sync folder_url obs://bucket[/key] [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • macOS/Linux操作系统 
      ./obsutil sync folder_url obs://bucket[/key] [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • cp命令

    cp命令需同时使用-u、-r和-delete参数：

    • Windows操作系统 
      obsutil cp folder_url obs://bucket[/key] -r -u [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • macOS/Linux操作系统 
      ./obsutil cp folder_url obs://bucket[/key] -r -u [-delete] [-f] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • cp命令使用-delete时，必须同时指定-u（增量）和-r（递归文件夹）参数，否则会报错。
  • sync命令自带增量同步能力，无需额外指定-u和-r参数。
  • -delete参数仅支持上传模式（本地→OBS），不支持下载模式或复制模式。

运行示例

假设本地文件夹的内容如下：

└── src1     
      ├── src2
            ├── test1.txt         
            └── test2.txt     
      └── test3.txt

假设bucket-test桶内包含如下对象：

obs://bucket-test/src1/
obs://bucket-test/src1/src2/
obs://bucket-test/src1/src2/test1.txt
obs://bucket-test/src1/src2/old.txt
obs://bucket-test/src1/legacy.txt
  • 以Linux操作系统为例，运行./obsutil sync /src1 obs://bucket-test/src1 -delete，增量同步上传并删除桶中多余对象。

    执行过程如下：

    1. 增量上传本地有变化的文件（test2.txt、test3.txt）。
    2. 扫描桶内对象，找出本地不存在对应文件的对象（old.txt、legacy.txt）。
    3. 提示确认是否删除，输入y确认后删除old.txt和legacy.txt。
    ./obsutil sync /src1 obs://bucket-test/src1 -delete

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: /root/.obsutil_checkpoint

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
OutputDir: /root/.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] 

[Pre-scan] Local file count: 3
[Pre-scan] Scanning OBS objects under obs://bucket-test/src1/ ... 
[Pre-scan] OBS objects scanned: 4, objects to delete: 2 Found 2 objects to delete in obs://bucket-test/src1/ 
Full list saved to: /root/.obsutil_output/sync_delete_target_files_20240925_104810_104786c8.txt
Please input (y/n) to confirm: y 
[Step 5/6] Deleting 2 objects from obs://bucket-test/src1/ ... 
[Step 6/6] Delete completed: succeed 2, failed 0 

Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
  • 以Linux操作系统为例，运行**./obsutil sync /src1 obs://bucket-test/src1 -delete -f**，跳过确认提示直接删除。 
    ./obsutil sync /src1 obs://bucket-test/src1 -delete -f

    使用-f参数后，删除前不会弹出确认提示，直接执行删除操作。适用于脚本自动化场景。

  • 以Linux操作系统为例，运行**./obsutil sync /src1 obs://bucket-test/src1 -delete -dryRun**，仅测试不实际执行 
    ./obsutil sync /src1 obs://bucket-test/src1 -delete -dryRun

    使用-dryRun参数后，命令仅输出将要上传和删除的文件列表，不会实际执行上传和删除操作。建议首次使用-delete时先用-dryRun确认结果。

  • 以Windows操作系统为例，运行obsutil cp d:\temp obs://bucket-test/temp -r -u -delete，使用cp命令增量同步删除上传。 
    obsutil cp d:\temp obs://bucket-test/temp -r -u -delete

    cp命令使用-delete时，需同时指定-r和-u参数，否则会报错。

参数说明

以下仅列出与增量同步删除相关的参数，其他参数请参见增量同步上传对象。

参数

约束

描述

delete

附加参数，可选

增量同步上传时，删除OBS目标桶中在本地源路径下没有对应文件的对象。仅支持上传模式（本地→OBS）。使用cp命令携带该参数时，必须同时指定-u和-r参数；使用sync命令时无需额外参数

f

附加参数，使用-delete时可选

跳过-delete操作的确认提示。不指定该参数时，执行删除前会要求用户确认；指定该参数后直接执行删除，不再提示确认。

dryRun

附加参数，可选

测试模式运行，不执行实际的上传和删除操作，仅输出将要操作的文件列表。建议首次使用-delete时配合该参数确认结果。

常见问题

  • 使用-delete时报错"source is empty, --delete is not allowed"

    源路径为空目录时，命令将拒绝执行。这是为了防止误删除桶内全部对象。请检查源路径是否正确，确保源目录中包含需要上传的文件。

  • 使用-delete时报错"no files matched for upload, --delete is not allowed"

    源路径下的文件全部被过滤条件（如-include、-exclude、-timeRange）排除，导致没有需要上传的文件。此时不允许执行删除操作，以避免删除不应删除的对象。请检查过滤条件是否过于严格。

  • 使用-delete时报错"--delete is only supported in upload mode"

    -delete参数仅支持上传模式（本地→OBS），不支持下载模式或桶间复制模式。请确保命令的源路径为本地路径，目标路径为OBS桶路径。

  • 使用cp命令时报错"--delete must be used together with -u (--update)"

    使用cp命令的-delete参数时，必须同时指定-u（--update）参数以启用增量模式。

  • 使用cp命令时报错"--delete must be used together with -r to upload folder"

    使用cp命令的-delete参数时，必须同时指定-r参数以指定上传文件夹。

  • 桶未开启版本控制时出现警告

    当目标桶未开启版本控制时，命令会输出警告信息。因为未开启版本控制的桶中对象被删除后无法恢复，建议开启桶版本控制以防止数据误删除。

响应结果

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

与普通增量同步上传相比，使用-delete时响应结果中会额外显示删除统计信息：

Delete succeed:    2         Delete failed:    0
父主题： 对象相关命令