对象多版本参数使用说明
更新时间：2026-09-09
BOS 开启 Bucket 多版本后，同一个 object key 会保留多个历史版本，每个版本有唯一的
versionId；删除对象默认不会真正删除数据，而是产生一个删除标记（delete marker）。
本文说明 bcecmd 各命令如何操作指定版本。
1. 前置：开启 Bucket 多版本
Bash
1# 开启
2bcecmd bosapi put-bucket-versioning --bucket-name mybucket --status enabled
3# 查询
4bcecmd bosapi get-bucket-versioning --bucket-name mybucket2. 支持 versionId 的命令一览
| 命令 | 参数 | 作用 |
|---|---|---|
bos ls |
--all-versions |
列举全部历史版本与删除标记 |
bosapi get-object-meta |
--version-id |
获取指定版本的元数据 |
bos cp |
--version-id |
复制/下载源对象的指定版本 |
bos mv |
--version-id |
移动源对象的指定版本（复制该版本后删除该版本） |
bos rm |
--version-id |
永久删除指定版本，而不是产生删除标记 |
bos restore |
--version-id |
解冻指定版本的归档对象 |
bos object-tagging |
--version-id |
读写指定版本的对象标签 |
bos object-acl |
--version-id |
读写指定版本的对象 ACL |
bos gen_signed_url |
--version-id |
生成指向指定版本的签名 URL |
不带
--version-id时，全部命令的行为与开启多版本前完全一致（操作最新版本）。
3. 列举版本
Bash
1bcecmd bos ls bos:/mybucket/dir/ --all-versions文本输出在存储类型之后额外增加两列：版本标记与 versionId。
Plain Text
1 2026-09-02 10:12:33 1024 STANDARD * kJ2mF...Qw dir/a.txt
2 2026-09-02 09:58:01 512 STANDARD bV9pL...Xz dir/a.txt
3 2026-09-01 18:20:44 0 STANDARD D aQ7dR...Ty dir/b.txt*：该版本是最新版本D：该条目是删除标记（size 为 0）- 空：历史版本
JSON 模式（--output json）下每个对象额外带 versionId / isLatest / deleteMarker
字段，翻页时除 nextMarker 外还需带上 nextVersionIdMarker，详见
json_output_use_guide.md。
4. 查询指定版本元数据
Bash
1bcecmd bosapi get-object-meta --bucket-name mybucket --object-name dir/a.txt \
2 --version-id kJ2mF...Qw5. 下载 / 复制指定版本
Bash
1# 下载历史版本到本地
2bcecmd bos cp bos:/mybucket/dir/a.txt /tmp/a.txt.old --version-id bV9pL...Xz
3
4# 把历史版本复制成一个新对象（相当于版本回滚到新 key）
5bcecmd bos cp bos:/mybucket/dir/a.txt bos:/mybucket/dir/a.txt.bak --version-id bV9pL...Xz限制：
- BOS 的分块复制接口无法携带源版本，因此指定版本的 BOS 间复制只走单次
CopyObject， 源对象大于 5GB 时会直接报错，请改为「先下载再上传」。 - 下载没有这个限制，大对象仍走分块 range 下载。同一 key 的不同版本使用互相独立的断点 续传记录与临时文件，不会串用。
6. 删除指定版本
Bash
1# 永久删除某个版本（不产生删除标记）
2bcecmd bos rm bos:/mybucket/dir/a.txt --version-id bV9pL...Xz
3
4# 不带 --version-id：仍然是产生删除标记，最新版本被隐藏但数据保留
5bcecmd bos rm bos:/mybucket/dir/a.txt7. 标签 / ACL / 解冻 / 签名 URL
Bash
1bcecmd bos object-tagging bos:/mybucket/dir/a.txt --method get --version-id bV9pL...Xz
2bcecmd bos object-acl bos:/mybucket/dir/a.txt --method get --version-id bV9pL...Xz
3bcecmd bos restore bos:/mybucket/dir/a.txt --restore-days 3 --version-id bV9pL...Xz
4bcecmd bos gen_signed_url bos:/mybucket/dir/a.txt -e 1800 --version-id bV9pL...Xzgen_signed_url 会把 versionId 纳入签名计算，生成的 URL 直接可用。
8. 共同限制
--version-id只作用于单个对象，与--recursive互斥（BOS 的批量删除、批量解冻等 接口无法按 key 携带版本），同时使用会直接报错退出。cp/mv的--version-id只在源为 BOS 对象时有效，源为本地路径时报错。sync不支持--version-id，它始终同步最新版本。- 批量回滚整个前缀到某个时间点请用
bos revert，见 revert_use_guide.md。
评价此篇文章