Object管理
更新时间：2026-05-25
同步对象
描述： sync命令用于在本地与BOS之间、或BOS与BOS之间同步文件，类似rsync命令。通过比较源和目标的文件差异，仅传输需要更新的文件。支持多种同步策略、文件过滤、并发传输、断点续传等功能。
命令格式：
$ bcecmd bos sync <SRC> <DST> [--sync-type TYPE] [--delete] [--exclude PATTERN] [--include PATTERN] [--exclude-delete PATTERN] [--concurrency NUM] [--traffic-limit LIMIT] [--storage-class CLASS] [--dryrun] [--yes] [--quiet] [--restart] [--disable-bar] [--download-tmp-path PATH] [--queue-size SIZE] [--follow-symlink] [--deleteSrc]
说明：
- SRC: 源路径，本地目录路径或BOS路径（格式：bos:/<bucket_name>/<prefix>）。
- DST: 目标路径，本地目录路径或BOS路径。
- --sync-type: 同步比较策略（见下方策略说明），默认为 time-size。
- --delete: 删除目标端存在但源端不存在的文件，使目标与源完全一致。
- --exclude: 排除匹配指定模式的文件（glob模式，如 *.log），可多次指定。
- --include: 仅同步匹配指定模式的文件（glob模式，如 *.jpg），可多次指定。
- --exclude-delete: 保护匹配模式的目标文件不被 --delete 删除。
- --concurrency: 最大并发数，控制同时同步的文件数量。
- --traffic-limit: 带宽限速（KB/s）。
- --storage-class: 指定目标对象的存储类型，可选值：STANDARD、STANDARD_IA、COLD、ARCHIVE。
- --dryrun: 预览模式，仅列出将执行的操作，不实际同步。
- -y, --yes: 跳过确认提示。
- --quiet: 静默模式，不显示操作过程信息。
- --restart: 忽略断点续传记录，重新开始传输。
- --disable-bar: 隐藏进度条。
- --download-tmp-path: 指定下载临时文件的存放目录。
- --queue-size: 任务队列大小。
- --follow-symlink: 跟随符号链接，上传链接目标文件的内容。
- --deleteSrc: 上传成功后删除本地源文件。
- --rand: 随机顺序同步（BOS到本地时有效）。
- --make-src-empty-dir: 在目标端创建源端的空目录。
- --cache-control: 设置Cache-Control头。
- --content-type: 设置Content-Type头。
- --content-disposition: 设置Content-Disposition头。
- --expires: 设置对象过期时间。
- --user-meta: 设置用户自定义元数据，格式："name1:value1,name2:value2"。
支持的同步方向：
- 本地 → BOS（上传同步）
- BOS → 本地（下载同步）
- BOS → BOS（远程同步）
- 不支持本地 → 本地
同步策略（--sync-type）： | 策略值 | 说明 | |--------|------| | time-size | （默认）比较修改时间和文件大小，源端更新或大小不同时同步 | | time-size-crc32 | 先比较时间和大小，再比较CRC32校验和 | | only-crc32 | 仅比较CRC32校验和 | | force-overwrite | 强制覆盖，不做比较直接同步所有文件 | | dest-not-exist | 仅同步目标端不存在的文件，跳过已存在的文件 |
注意事项：
- sync命令默认递归同步，无需指定 -r 参数。
- 源路径必须是目录（以/结尾或为空前缀），不支持单文件同步。
- --exclude 和 --include 互斥，不可同时使用。
- 大文件自动使用分片传输并支持断点续传。
示例：
- 将本地目录同步到BOS
操作示例：
Plain Text
1$ bcecmd bos sync /local/data/ bos://testbucket/data/说明：将本地 /local/data/ 目录中有变更的文件同步到BOS。
- 将BOS目录同步到本地
操作示例：
Plain Text
1$ bcecmd bos sync bos://testbucket/data/ /local/data/- BOS间同步
操作示例：
Plain Text
1$ bcecmd bos sync bos://srcbucket/logs/ bos://dstbucket/logs/说明：在BOS内部同步对象，无需经过本地中转。
- 使用 --delete 保持目标与源完全一致
操作示例：
Plain Text
1$ bcecmd bos sync /local/website/ bos://testbucket/website/ --delete说明：同步文件并删除BOS上存在但本地已不存在的对象，使BOS与本地完全一致。
- 保护特定文件不被删除
操作示例：
Plain Text
1$ bcecmd bos sync /local/website/ bos://testbucket/website/ --delete --exclude-delete "*.config"说明：同步时删除多余文件，但保护匹配 *.config 模式的文件不被删除。
- 排除特定文件
操作示例：
Plain Text
1$ bcecmd bos sync /local/project/ bos://testbucket/project/ --exclude "*.log" --exclude "*.tmp"说明：同步时排除所有 .log 和 .tmp 文件。
- 仅同步特定类型文件
操作示例：
Plain Text
1$ bcecmd bos sync /local/images/ bos://testbucket/images/ --include "*.jpg"说明：仅同步匹配 *.jpg 模式的文件。
- 指定同步策略
操作示例：
Plain Text
1$ bcecmd bos sync /local/data/ bos://testbucket/data/ --sync-type only-crc32说明：使用CRC32校验和比较文件内容，确保数据完全一致。
- 仅同步新增文件（增量同步）
操作示例：
Plain Text
1$ bcecmd bos sync /local/data/ bos://testbucket/data/ --sync-type dest-not-exist说明：仅上传目标端不存在的文件，已存在的文件不做任何比较和覆盖。
- 多并发加速同步
操作示例：
Plain Text
1$ bcecmd bos sync /local/bigdir/ bos://testbucket/bigdir/ --concurrency 10说明：使用10个并发线程同时传输多个文件，加速大目录同步。
- 预览同步操作（不实际执行）
操作示例：
Plain Text
1$ bcecmd bos sync /local/data/ bos://testbucket/data/ --delete --dryrun说明：列出将要同步和删除的文件，不实际执行任何操作，适合在正式同步前确认。
- 限速同步
操作示例：
Plain Text
1$ bcecmd bos sync /local/data/ bos://testbucket/data/ --traffic-limit 2048说明：限制传输带宽为2048KB/s，避免占满网络带宽。
- 上传后删除本地源文件
操作示例：
Plain Text
1$ bcecmd bos sync /local/logs/ bos://testbucket/logs/ --deleteSrc -y说明：文件上传成功后自动删除本地源文件，适合日志归档场景。
- 指定存储类型同步
操作示例：
Plain Text
1$ bcecmd bos sync /local/archive/ bos://testbucket/archive/ --storage-class ARCHIVE说明：将文件同步为归档存储类型，适合长期保存且不频繁访问的数据。
拷贝对象
描述： cp命令用于在本地与BOS之间、或BOS与BOS之间拷贝对象，类似Linux的cp命令。支持断点续传、多线程并发、存储类型指定、流量限速等功能。
命令格式：
$ bcecmd bos cp <SRC> <DST> [-r] [-y] [--quiet] [--restart] [--storage-class CLASS] [--concurrency NUM] [--traffic-limit LIMIT] [--include PATTERN] [--follow-symlink] [--keep-symlink] [--queue-size SIZE] [--disable-bar] [--download-tmp-path PATH]
说明：
- SRC: 源路径，本地路径或BOS路径（格式：bos:/<bucket_name>/<object_key>）。
- DST: 目标路径，本地路径或BOS路径。
- -r, --recursive: 递归拷贝目录下的所有对象。拷贝目录时必须指定此参数。
- -y, --yes: 跳过确认提示，直接执行拷贝。
- --quiet: 静默模式，不显示操作过程信息。
- --restart: 忽略断点续传记录，重新开始拷贝。
- --storage-class: 指定目标对象的存储类型，可选值：STANDARD、STANDARD_IA、COLD、ARCHIVE。
- --concurrency: 目录拷贝时的最大并发数，控制同时拷贝的文件数量。
- --traffic-limit: 带宽限速（上传/下载单位为KB/s；BOS间拷贝范围为819200-838860800）。
- --include: 文件匹配模式（如 *.jpeg），仅拷贝匹配的文件，递归拷贝时有效。
- --follow-symlink: 跟随符号链接，上传链接目标文件的内容。
- --keep-symlink: 保留符号链接属性，在创建symlink对象而非上传内容。
- --queue-size: 任务队列大小。
- --disable-bar: 隐藏进度条。
- --download-tmp-path: 指定下载临时文件的存放目录。
- --cache-control: 设置Cache-Control头（如 private、no-cache、max-age=3600）。
- --content-type: 设置Content-Type头（MIME类型）。
- --content-disposition: 设置Content-Disposition头（inline或attachment）。
- --expires: 设置对象过期时间。
- --user-meta: 设置用户自定义元数据，格式："name1:value1,name2:value2"。
支持的拷贝方向：
- 本地 → BOS（上传）
- BOS → 本地（下载）
- BOS → BOS（远程拷贝）
- 不支持本地 → 本地
注意事项：
- 大文件自动使用分片上传/下载（上传阈值32MB，下载阈值100MB，远程拷贝阈值100MB）。
- 单文件最大支持5TB。
- 默认支持断点续传，使用
--restart可强制重新开始。--follow-symlink和--keep-symlink互斥，不可同时使用。
示例：
- 上传单个文件到BOS
操作示例：
Plain Text
1$ bcecmd bos cp /local/path/file.txt bos://testbucket/file.txt- 从BOS下载单个文件
操作示例：
Plain Text
1$ bcecmd bos cp bos://testbucket/file.txt /local/path/file.txt- 递归上传整个目录
操作示例：
Plain Text
1$ bcecmd bos cp /local/dir/ bos://testbucket/backup/ -r说明：将本地 /local/dir/ 下的所有文件递归上传到 BOS 的 backup/ 前缀下。
- 递归下载整个目录
操作示例：
Plain Text
1$ bcecmd bos cp bos://testbucket/logs/ /local/logs/ -r- BOS间远程拷贝
操作示例：
Plain Text
1$ bcecmd bos cp bos://srcbucket/data/ bos://dstbucket/data/ -r说明：在BOS内部拷贝对象，无需经过本地中转。
- 指定存储类型上传
操作示例：
Plain Text
1$ bcecmd bos cp /local/archive/ bos://testbucket/archive/ -r --storage-class COLD说明：将文件上传为低频存储（COLD）类型，降低存储成本。
- 多并发上传大目录
操作示例：
Plain Text
1$ bcecmd bos cp /local/bigdir/ bos://testbucket/bigdir/ -r --concurrency 10说明：使用10个并发线程同时上传多个文件，加速大目录的拷贝。
- 限速上传
操作示例：
Plain Text
1$ bcecmd bos cp /local/path/largefile.bin bos://testbucket/largefile.bin --traffic-limit 1024说明：限制上传带宽为1024KB/s，避免占满网络带宽。
- 按模式过滤文件上传
操作示例：
Plain Text
1$ bcecmd bos cp /local/images/ bos://testbucket/images/ -r --include "*.jpeg"说明：仅上传目录中匹配 *.jpeg 模式的文件。
- 忽略断点续传记录重新上传
操作示例：
Plain Text
1$ bcecmd bos cp /local/path/bigfile.tar.gz bos://testbucket/bigfile.tar.gz --restart说明：忽略之前的断点续传记录，从头开始上传。
- 处理符号链接
操作示例：
Plain Text
1$ bcecmd bos cp /local/dir/ bos://testbucket/dir/ -r --follow-symlink说明：跟随符号链接，将链接目标文件的实际内容上传到BOS。
- 设置自定义元数据上传
操作示例：
Plain Text
1$ bcecmd bos cp /local/data.csv bos://testbucket/data.csv --user-meta "source:import,version:v2"说明：上传时为对象设置自定义元数据。
列举对象
描述： ls命令可以列出一个Bucket内的不超过1000条Objects，可以通过指定Prefix来过滤结果。ls会自动以/作为delimiter来达到模拟文件夹的效果。
命令格式： $ bcecmd bos ls bos:/<bucket-name>/[prefix]
操作示例： bcecmd bos ls bos:/mybucket/web
返回示例：
Plain Text
1 PRE pre/
22016-04-01 16:43:01 8698 STANDARD web_bos.png
32016-04-01 16:41:49 17188 STANDARD web_server_bos.png
42016-04-01 16:43:53 24620 STANDARD_IA webtobos_cors.png
52016-04-01 16:45:53 24623 COLD cold_abc.png说明
- -a, --all：超过1000个Object时会全部显示出来。
- -r, --recursive：不显示目录，直接显示下面的Object。
- -s, --summerize：显示个数以及总大小等统计信息。
- 示例输出第一列代表Object的创建日期，第二列代表创建时间，第三列代表Object的大小（以Byte为单位），第四列表示Object的存储类型，第五列表示Object的名称。
- pre/表示为文件夹，不会显示创建时间及大小信息。
获取Object的URL
描述： gen_signed_url命令可以获取指定Object的URL，根据提供的URL可以下载Object。
命令格式 $ bcecmd bos gen_signed_url bos:/<bucket-name>/<object-key> [-eTIME]
说明：
- 获取的URL地址输入浏览器中可以直接下载Object。生成URL前，需要确认配置的AK/SK与Bucket对应账户的AK/SK一致，否则生成的URL无效不能正常下载Object。
- -e: 指定URL过期时间（单位秒），值必须大于等于-1，其中-1表示URL永久有效。
- 不指定过期时间时默认过期时间为1800秒。
注意： 参数-e 与过期时间之前不能有空格。
示例：
-
不指定过期时间
操作示例：
Plain Text1 $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png返回示例：
Plain Text1 http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2Fd35a0b8750114e49b3567e0b0542c2f1%2F2016-08-25T02%3A03%3A57Z%2F1800%2F%2F96d77180ec2cb7e8de522c15ca42bf67c30bae0edb47bad495fe8e7953794a4f -
指定过期时间为100秒
操作示例：
Plain Text1 $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e100返回示例：
Plain Text1 http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F100%2F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a -
指定URL永久有效
操作示例：
Plain Text1 $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e-1返回示例：
Plain Text1 http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F-12F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a
删除对象
描述： rm命令用于删除BOS上的对象，类似Linux的rm命令。支持单个对象删除和递归批量删除，支持多线程并发加速大目录下的批量删除操作。
命令格式：
$ bcecmd bos rm bos:/<bucket_name>/<object_key> [-r] [-y] [--quiet] [--dryrun] [--singleDelete] [--level LEVEL] [--thread-num THREAD_NUM]
说明：
- -r, --recursive: 递归删除指定前缀下的所有对象。当删除目录前缀时必须指定此参数。
- -y, --yes: 跳过确认提示，直接执行删除操作。
- --quiet: 静默模式，不显示操作过程信息。
- --dryrun: 预览模式，仅列出将被删除的对象，不实际执行删除。
- --singleDelete: 使用逐个删除方式代替批量删除（适用于不支持批量删除API的场景）。
- --level: 任务拆分层级，0表示不拆分（默认），大于0时从第N层子目录开始拆分任务进行并行删除。
- --thread-num: 工作线程数，默认为1。当level>0时可配合使用多线程加速删除。
注意事项：
- 删除操作不可逆，请谨慎使用。
- 删除目录前缀下的对象时，必须添加
-r参数，否则会提示错误。- 默认会弹出确认提示，使用
-y参数可跳过确认。- level参数必须大于等于0。
- thread-num参数必须大于等于1。
示例：
- 删除单个对象
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/testobject输出示例：
Plain Text
1Do you really want to DELETE bos://testbucket/testobject? (yes or no)
2yes
3Delete object testobject success.- 跳过确认直接删除
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/testobject -y- 递归删除目录下所有对象
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/logs/ -ry说明：递归删除 logs/ 前缀下的所有对象，跳过确认提示。
- 预览将被删除的对象（不实际删除）
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/logs/ -r --dryrun输出示例：
Plain Text
1logs/2024/01/access.log
2logs/2024/01/error.log
3logs/2024/02/access.log
4...
5Total: 1234 objects would be deleted.- 多线程并发删除大目录
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/bigdir/ -ry --level 2 --thread-num 8说明：从第2层子目录开始拆分任务（如 bigdir/subdir1/、bigdir/subdir2/ 等），使用8个线程并发删除，适合包含大量对象的目录。
- 静默模式删除
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/logs/ -ry --quiet说明：递归删除且不输出任何过程信息，适合在脚本中使用。
- 使用逐个删除模式
操作示例：
Plain Text
1$ bcecmd bos rm bos://testbucket/logs/ -ry --singleDelete说明：逐个删除对象而非批量删除，适用于需要精确控制删除过程的场景。
取回object
描述： restore命令用于取回指定object，支持批量取回。
命令格式：
$ bcecmd bos restore bos://${bucket-name}/{object-key} --restore-tier STANDARD --restore-days 7 -r
说明：
- --bucket-name: bucket名称
- --object-key：要取回的object名称
- --restore-tier：解冻优先级。Expedited：加急取回，表示30min内完成取回。
Standard：标准取回，表示2~5小时内完成取回。LowCost：延缓取回，表示12小时内完成取回。- --restore-days：表示解冻后状态的持续时间，要求是数字，单位是天，取值大于0且不超过30即可。默认解冻持续天数是7天,最长30天。
- -r: 当object-key为文件夹时，需添加-r参数，批量取回该前缀下的所有object
示例：
操作示例：
Plain Text
1$ bcecmd bos restore bos://testbucket/testobject移动object
描述： mv命令用于将指定对象移动到指定目录下，支持批量取回。
命令格式：
$ bcecmd bos mv bos:/<bucket_name>/[object key] bos:/<bucket_name>/[object key] [--recursive] [--quiet] [--yes] [--disable-bar] [--ignore-not-allow-modify] [--concurrency CONCURRENCY] [--queue-size QUEUE-SIZE]
说明：
- -r, --recursive: 当object-key为文件夹时，需添加-r参数，批量取回该前缀下的所有object
- -y, --yes: 使用该选项时跳过确认步骤。
- --quiet: 日志和进度信息不打印在控制台.
- --disable-bar: 不显示进度条。
- --concurrency: 用于设置 mv 命令并发上传下载的文件数，默认为10。
- --queue-size: 指定 mv 任务的队列长度，默认为1000。
示例：
- 移动单个文件
操作示例：
Plain Text
1$ bcecmd bos mv bos://testbucket/testobject bos://testbucket/testobject-mv- 批量移动文件
操作示例：
Plain Text
1$ bcecmd bos mv bos://testbucket/dir1/ bos://testbucket/dir2/ -r统计对象数量和大小
描述： du命令用于统计指定bucket的prefix下的对象总数和总占用存储空间大小，类似Linux的du命令。支持多线程并发统计大型bucket。
命令格式：
$ bcecmd bos du bos:/<bucket_name>/[prefix] [--friendly] [--level LEVEL] [--thread-num THREAD_NUM] [--detail] [--quiet]
说明：
- --friendly: 以可读格式输出大小（如 1.5 GiB），默认输出字节数。
- --level: 任务拆分层级，0表示不拆分（默认），大于0时从第N层子目录开始拆分任务进行并行统计。
- --thread-num: 工作线程数，默认为1。当level>0时可配合使用多线程加速统计。
- --detail: 输出各子目录的统计详情。
- --quiet: 静默模式，不显示操作过程信息。
注意事项：
- level参数必须大于等于0。
- thread-num参数必须大于等于1。
- 统计结果不包含目录占位对象（以"/"结尾且大小为0的对象）。
示例：
- 统计整个bucket
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket输出示例：
Plain Text
1Total Objects: 12345
2Total Size: 1234567890 bytes- 统计指定前缀
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket/logs/- 友好格式输出
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket --friendly输出示例：
Plain Text
1Total Objects: 12345
2Total Size: 1.15 GiB- 多线程并发统计
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket/logs/ --level 1 --thread-num 4说明：从第1层子目录开始拆分任务，使用4个线程并发统计。
- 输出各子目录统计详情
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket/logs/ --level 1 --thread-num 4 --detail --friendly输出示例：
Plain Text
1PREFIX OBJECTS SIZE
2---------------------------------------------------------------------------------------
3logs/2024/01/ 1234 512.00 MiB
4logs/2024/02/ 2345 1.00 GiB
5logs/2024/03/ 567 256.00 MiB
6---------------------------------------------------------------------------------------
7Total Objects: 4146
8Total Size: 1.75 GiB- 深层级拆分统计
操作示例：
Plain Text
1$ bcecmd bos du bos://testbucket/logs/ --level 2 --thread-num 8 --detail --friendly说明：从第2层子目录开始拆分任务（如 logs/2024/01/、logs/2024/02/ 等），使用8个线程并发统计，适合层级较深的大型bucket。
恢复对象历史版本
描述： revert命令用于在开启多版本的bucket中，将指定prefix下的对象恢复到指定的历史版本。
命令格式：
$ bcecmd bos revert bos:/<bucket_name>/[prefix] [--version-index VERSION_INDEX] [--thread-num THREAD_NUM] [--dryrun] [--yes] [--quiet]
说明：
- -n, --version-index: 恢复到第N个历史版本（按修改时间降序排列），默认为1，即恢复到上一个版本。
- -t, --thread-num: 工作线程数，默认为1。
- --dryrun: 模拟运行，只显示将要恢复的对象而不实际执行。
- -y, --yes: 使用该选项时跳过确认步骤。
- --quiet: 静默模式，只输出最终统计结果。
注意事项：
- 该命令仅支持已开启版本控制的bucket。
- 会自动跳过delete marker和没有历史版本的对象。
- 当历史版本数量不足version-index个时，会选择最后一个历史版本。
示例：
- 恢复单个prefix下的对象到上一个版本
操作示例：
Plain Text
1$ bcecmd bos revert bos://testbucket/logs/ -y- 恢复对象到第3个历史版本
操作示例：
Plain Text
1$ bcecmd bos revert bos://testbucket/logs/ -n 3 -y- 多线程恢复
操作示例：
Plain Text
1$ bcecmd bos revert bos://testbucket/logs/ -t 4 -y- 模拟运行（不实际执行）
操作示例：
Plain Text
1$ bcecmd bos revert bos://testbucket/logs/ --dryrun输出示例：
Plain Text
1[DRY-RUN] Reverting objects under bos:/testbucket/logs/ to version index 1...
2
3[WOULD REVERT] logs/file1.txt: -> version abc123
4[WOULD REVERT] logs/file2.txt: -> version def456
5
6Dry-run Summary:
7 Would revert: 2
8 Would skip: 0- 静默模式
操作示例：
Plain Text
1$ bcecmd bos revert bos://testbucket/logs/ --quiet -y输出示例：
Plain Text
1Summary:
2 Total: 5
3 Success: 3
4 Skipped: 2
5 Failed: 0评价此篇文章