百度对象存储 BOS（Baidu Object Storage）

是一种面向Internet的存储服务，向用户提供稳定、安全、高效以及高扩展存储服务。

用户可以通过控制台界面，简单快捷的完成对象的存储和检索等基本功能。

BOS核心概念

• Object

在 BOS 中，用户操作的基本数据单元是 Object。

每个 Object 包含

• Key 是 Object 的名字
• Meta 是用户对该 Object 的描述，由一系列 Name-Value 对组成
• Data 是 Object 的数据。
• Bucket

Bucket 是存放数据的容器，可以当成是存储桶。

Bucket 具有区域属性，只能位于一个区域。

因为 Bucket 名称创建后不能修改名称和所属区域，所以建议根据业务情况就近存储，方便上传和下载以提高访问速度。

Bucket 名称具有全局唯一性。

每个 Object 必须都包含在某个 Bucket 中。

一个用户最多可创建 100 个 Bucket，但每个 Bucket 中存放的 Object 的数量和大小总和没有限制，用户不需要考虑数据的可扩展性。

• 文件夹

Bucket 中为了更好的归类 Object，可以创建文件夹用于存储同类的 Object

• Referer 白名单

Referer 白名单即准入列表，是一种基于HTTP header referer 字段的防盗链方法

目的是防止用户存储在 BOS上 的数据被其他人盗链。

用户可以通过 BOS 控制台设置 Referer 字段的白名单。

设置白名单后，只有 Referer 字段在白名单内的用户才可以访问 Bucket 中存储的数据，不在白名单内的请求会被拒绝。

但如果用户的 Referer 为空，默认可以访问，不受白名单限制。

• Region

Region代表一个独立地域。

百度智能云中的服务除了极少数如账号服务全局有效之外，绝大部分服务都是区域间隔离的。

每个区域的服务独立部署互不影响。

服务间共享数据需要通过显式拷贝完成。

百度智能云目前开放了多区域支持，请参考 区域选择说明。

在 API 中引用区域必须使用其对应区域的服务域名。

区域	服务域名
北京	bj.bcebos.com
保定	bd.bcebos.com
苏州	su.bcebos.com
广州	gz.bcebos.com
香港	hkg.bcebos.com
金融云武汉专区	fwh.bcebos.com
金融云上海专区	fsh.bcebos.com

用户在访问的BOS服务的时候，可以通过URL指定请求落到哪个Region，例如：http(s)://bj.bcebos.com将会把请求落到北京。

• Access Key ID / Secret Access Key

用户开通 BOS 服务后，系统会自动分配一对 Access Key ID (AK)/ Secret Access Key(SK)

该密钥对将在用户向 BOS 发起请求时用做签名验证。

• Access Key ID 用于标示用户
• Secret Access Key 是用户用于加密签名字符串 和 BOS 服务用来验证签名字符串的密钥。

请参考获取AK/SK

除系统分配的密钥对外，用户还可自行申请多对AK/SK，总量最多为20对

• 权限控制

BOS 提供用户签名验证、访问控制列表 ACL 和对象限时访问相结合的权限控制方式，为用户提供安全可靠的数据保护。

其中用户签名验证采用 AK/SK 非对称加密的方法对 URL 进行签名来实现用户身份验证；

ACL 根据签名识别用户身份后，提出请求Bucket的访问权限信息，并根据相应的权限信息对请求做出响应；

对象限时访问让用户可以提供自定义时间内有效的 URL 用于下载等应用场景。

• CDN加速

不仅能为包括地图、图片、文档在内的静态网页加载进行加速，也可为音频、下载、游戏等业务提供加速服务，使网站可被高速访问，有效提升网站的用户体验。

开发及基本使用

• 注册登录

https://login.bce.baidu.com/?account=&redirect=http%3A%2F%2Fconsole.bce.baidu.com%2F

登录成功后，选择 “产品服务>对象存储 BOS”，认证并开通BOS

• 新建 bucket

关于存储方式：https://cloud.baidu.com/doc/BOS/s/Ajwvyr3q5/

• 上传文件

• 获取 object

BOS BCE CMD 的基本使用

安装更方便，执行效率更高，而且使用方法与 BCE CLI 相同的命令行工具 —— BCE CMD。

BCE CMD 当前只包含了 BOS 的功能，所以下文都用 BOS CMD 代指 BCE CMD。

BOS CMD 提供了丰富的功能，您不仅可以通过 BOS CMD 完成 Bucket 的创建和删除，Object的上传、下载、删除和拷贝等,

当您从 BOS 下载文件或者上传文件到BOS遇到问题时，还可以使用 BCE CMD 的子命令 bosprobe 进行错误检查。

1. 下载

https://cloud.baidu.com/doc/BOS/s/qjwvyqegc

2. 解压

Mac 用户解压命令为

$ unzip mac-bcecmd-0.2.6.zip

3. 将 bcecmd 可执行文件移入系统环境变量

4. 配置支持中文显示的CMD环境，请执行如下命令配置

加一行 

5. 配置 AK/SK、Region、Host 信息

• <conf-path> 为本地文件目录，当用户有多个百度智能云账户时，通过指定 <conf-path> 将不同账号的配置文件写到不同目录下，执行命令时可以指定目录选择对应账户的配置。
• 不指定 <conf-path> 时，CMD 在配置完成后将配置文件自动写到当前用户主目录 ~/.go-bcecli 
• 指定 <conf-path>时，将配置文件自动写到指定目录。
• 即使不设置 AK/SK，您也可以通过 BOS CMD 访问 public 权限的 bucket。
• 指定 Region 之后您可以不指定Host，BOS CMD 可自动拼接 Host 为 Region.bcebos.com。
• 如果您指定了 Host，那么 BOS CMD 不再自动拼接 Host，而是访问您指定的 Host。
• 可以填写 None 将 AK/SK/Region 以及 Domain 设置为空。当 Region 设置为空时默认值为 bj。当 Domain 设置为空时默认使用 Region 拼接，当两个同时为空时默认访问 bj.bcebos.com。

6. 使用 ls 查看线上 bos 的文件

$ bcecmd --conf-path ~/kjfboscmd/ bos ls bos:/kjf-bucket/

7. 创建一个新的 bucket

$ bcecmd --conf-path ~/kjfboscmd/ bos mb bos:/kjf-new-bucket/

8. 删除一个 bucket

$ bcecmd --conf-path ~/kjfboscmd/ bos rb bos:/kjf-new-bucket/

9. 上传 object 

BOS CMD 支持同步上传、单文件上传、批量上传三种方式，

上传过程中可以指定 Object 的存储类型是标准存储、低频存储或冷存储。

此外 BOS CMD 还支持

• 对于大于 32M 的文件自动分块并发上传，并设置上传的并发连接数等

当您需要在本地和 BOS 之间进行数据上传，同步上传（sync）是最方便的上传命令

• $ bcecmd bos sync <local_dir> bos:/<bucket_name>/[prefix] [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--storage-class STORAGE-CLASS] [--sync-type SYNC-TYPE] [--concurrency CONCURRENCY] [--restart]

• local_dir

必须为本地目录，不能为单个文件。也不支持通配符匹配的语法，如 <local_dir>/* 以及 <local_dir>/prefix* 等。

• --exclude

执行本地到 bos 的 sync 的时候, 需要跳过的文件

支持通配符 * 和多项配置, 如要跳过 tmp 文件和当前目录所有子目录下的 svn 目录: --exclude ./*.tmp --exclude */.svn

• --include

执行本地到bos的sync的时候, 只同步指定文件

支持通配符*和多项配置, 如只同步当前目录所有子目录下的 log 文件和html文件: --include ./*.log --include ./*.html

• --delete

删除 BOS 有而本地没有的文件，使 BOS 和本地的数据完全一致。

执行后默认会提示用户是否要执行删除

• --exclude-delete

用于在删除本地文件时排除特定文件或目录， 具体用法请参考 --exclude 的使用规则

此选项需要同 --delete 一起使用

• --dryrun

列出会执行的操作但不实际执行

• --yes

执行删除动作时不需要确认直接删除

• --quiet

同步上传但不输出任何中间过程

• --storage-class [STORAGE_CLASS]

通过 storage-class 参数指定同步上传的 Object 的存储类型。

指定 storage-class 为 STANDARD_IA 或者 COLD 时表示存储为低频存储或者冷存储类型

指定的 storage-class 为 STANDARD 或者 不指定 storage-class 时 为标准存储

• -sync-type

同步类型可以为 time-size， time-size-crc32 和 only-crc32， 默认为 time-size。

bcecmd 执行 sync 时首先会判断要同步的文件在目的端是否存在，如果不存在就会上传或者下载文件，

当源端和目的端都存在时， 就会根据同步类型来决定是否需要同步文件。

• time-size:

比较源端和目的端文件的修改日期和大小来判断是否同步，当源端文件的修改日期早于目的端文件时，不会同步文件；当源端文件的修改日期等于目的端文件的修改日期，且它们的大小相同时不同步文件， 否则同步;

• time-size-crc32

bcecmd 先使用 time-size 模式判断是否需要同步文件， 当 time-size 输出结果为需要同步文件时, bcecmd 将比较源端和目的端文件的 crc32， 当 crc32 的值不同时才会同步文件;

• only-crc32

bcecmd 只会比较源端和目的端文件的crc32， 如果不同就会同步文件

• --concurrency

用于设置 sync 命令并发上传下载的文件数

• --restart

忽略断点续传，重头开始上传文件

同步上传默认支持批量操作，可以将本地目录同步到 BOS

如果 BOS 端已经有名称相同且修改时间比本地文件新，同步上传会忽略此文件，只同步新文件或有改动的文件

sync 命令会同时列举本地和 BOS 侧文件, 对于不同情况分别执行以下动作：

• 对于新增的文件（本地的某个文件BOS侧没有）：上传
• 对于已上传但是有改动的文件（本地文件的更新时间晚于BOS侧文件的创建时间, 或者本地文件的大小跟BOS侧不一致）：覆盖上传
• 对于已上传且没改动的文件：跳过不处理
• 对于已上传但是在本地没有的文件：根据--delete参数来做不同的处理

单文件上传

$ bcecmd bos cp <local-path> <bos-path> [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

批量上传

$ bcecmd bos cp <local-path> <bos-path> --recursive [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

注意：

• 执行 $ bcecmd bos cp /tmp/file1 bos:/bucket/file2 命令时，file2 可以与 file1 相同，如果 file2 在 bucket 中已存在则会被覆盖
• 执行 $ bcecmd bos cp /tmp/file bos:/bucket/ 命令时，自动使用本地文件名作为 bos 端文件名，如果已存在重名文件会被覆盖
• 执行 $ bcecmd bos cp /tmp/file bos:/bucket/prefix[/] -r 命令时，本地为文件时会退化为单文件上传，bos 路径结尾为”/”时prefix会当做目录，新文件保存在prefix下一级；结尾不为"/"时会当做object名直接上传
• 执行 $ bcecmd bos cp /tmp/dir/ bos:/bucket/prefix[/] -r 命令时，本地为目录时 bos 路径结尾不论是否有”/”都会以 prefix 为目录名在 bos 端新建目录； 并将 dir 中 Object 全部拷贝到 prefix 目录下
• 执行批量上传时，local-path 只能是本地目录且以"/"结尾，bos-path 必须为 bucket/prefix
• 上传 Object 过程中可以通过 storage-class 参数指定 Object 的存储类型，storage-class 默认为 STANDARD 即标准存储，storage-class 为STANDARD_IA 或者 COLD 时表示存储为低频存储或者冷存储类型。如果 storage-class 输入参数错误依旧会按照 STANDARD 进行存储，不会提示错误信息
• --disable-bar 禁止使用进度条

实例：

• 同步当前目录下的 sample 目录到 bos:/bce-test/test 下

$ bcecmd bos sync ./sample/ bos:/bce-test/test

• 列出会执行的同步操作但不执行

$ bcecmd bos sync ./sample/ bos:/bce-test/test --dryrun

• 同步上传但不输出任何中间过程

$ bcecmd bos sync ./sample/ bos:/bce-test/test --quiet

• 同步 sample 目录到 bos:/bce-test/test 上且删除 BOS 有而本地没有的文件

$ bcecmd bos sync ./sample/ bos:/bce-test/test --delete

• 同步 sample 目录到 bos:/bce-test/test 上并存储为低频存储类型

$ bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class STANDARD_IA

• 同步 sample 目录到 bos:/bce-test/test 上并存储为冷存储类型

$ bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class COLD

• 单文件上传

$ bcecmd bos cp text.txt bos:/mybucket/test.txt

• 批量上传

$ bcecmd bos cp ./temp/ bos:/bce-test -r

• 上传 Object 并存储为低频存储类型

$ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class STANDARD_IA

• 上传 Object 并存储为冷存储类型

$ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class COLD

10. 下载 object

BOS CMD 支持同步下载、单个文件下载和批量文件下载

同步下载默认支持批量操作，可以将BOS同步到本地目录。

如果本地已经有同名文件，且本地文件修改时间晚于BOS上的同名文件，同步上传会忽略这些文件，只同步新文件或有改动的文件

同步下载 sync 命令会同时列举本地和 BOS 侧文件, 对于不同情况分别执行以下动作

$ bcecmd bos sync <bos-dir> <local-dir> [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--sync-type SYNC-TYPE] [--download-tmp-path DOWNLOAD-TMP-PATH] [--concurrency CONCURRENCY] [--restart]

• 对于新增的文件（BOS的某个文件本地没有）：下载
• 对于已下载但是有改动的文件（BOS侧文件的创建时间晚于本地文件的更新时间, 或者BOS侧文件的大小跟本地不一致）：覆盖下载
• 对于已下载且没改动的文件：跳过不处理
• 对于已下载但是BOS侧没有的文件：根据--delete参数来做不同的处理

说明

• 同步下载中，local-dir 和 bos-dir 必须为目录，不能为单个文件。

--exclude

执行 bos 到本地的 sync 的时候, 需要跳过的文件, 支持通配符*和多项配置

如要跳过 bucket sample 下 tmp 文件和所有目录下的 svn 目录: --exclude bos:/sample/*.tmp --exclude bos:/sample/*/.svn/*

--include

执行 bos 到本地的 sync 的时候, 只同步指定文件, 支持通配符*和多项配置,

如只同步 bucket sample 下的 log 文件和 html 文件： --include bos:/sample/*.log --include bos:/sample/*.html

--delete

删除本地有而BOS没有的文件，使本地和BOS的数据完全一致。执行后默认会提示用户是否要执行删除。

--exclude-delete

此选项需要同 --delete 一起使用，用于在删除在目的端存在而在源端不存在的文件时排除目的端特定文件或目录，

具体用法请参考 --exclude的使用规则。

--dryrun

列出会执行的操作但不实际执行。

--yes

执行删除动作时不需要确认直接删除。

--quiet

同步下载但不输出任何中间过程。

--sync-type:

同步类型可以为 time-size， time-size-crc32 和 only-crc32， 默认为 time-size。

bcecmd 执行 sync 时首先会判断要同步的文件在目的端是否存在，

如果不存在就会上传或者下载文件， 当源端和目的端都存在时， 就会根据同步类型来决定是否需要同步文件。

• time-size:

比较源端和目的端文件的修改日期和大小来判断是否同步，当源端文件的修改日期早于目的端文件时，不会同步文件；当源端文件的修改日期等于目的端文件的修改日期，且它们的大小相同时不同步文件， 否则同步;

• time-size-crc32

bcecmd 先使用 time-size 模式判断是否需要同步文件， 当time-size 输出结果为需要同步文件时, bcecmd 将比较源端和目的端文件的 crc32， 当crc32的值不同时才会同步文件;

• only-crc32

bcecmd 只会比较源端和目的端文件的crc32， 如果不同就会同步文件。

--download-tmp-path

用于手动指定断点下载时用于保存临时文件的目录， 如果不指定， 默认使用执行命令时所在目录。

--concurrency

用于设置 sync 命令并发上传下载的文件数。

--restart

忽略断点续传，重头开始上传文件。

注意

• 当 --delete 与过滤（include 或exclude）同时使用时，如果一个文件被过滤，尽管它同时存在于源端和目的端， 它也会被删除。

因为bcecmd只会比较未被过滤的文件。

• 需要注意 BOS 在2018年1月之后才全面支持 CRC32, 所以当 bcecmd sync-type 选择为 time-size-crc32 或only-crc32时，如果 bcecmd 未能从 BOS 获取到 object 的 CRC32 信息时， bcecmd 将总是会同步这些文件

下载单个Object

$ bcecmd bos cp <bos-path> <local-path> [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]

批量下载Object

$ bcecmd bos cp <bos-path> <local-path> --recursive [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]