使用手动部署的 RapidFS
使用手动部署的 RapidFS
前提
目前 RapidFS 尚未开放公开下载，想要不通过 CCE 或 BMR 集成的方式使用 RapidFS，可以发送申请邮件到 rapidfs@baidu.com。
以下文档假设已经部署了 RapidFS 集群。
准备工作
Master 服务地址
一套完整的 RapidFS 集群，包含 Master、MetaServer、DataServer 3 个服务。通常用户在使用的时候，只需要和 Master 服务打交道。
通常情况下，Master 会以 3 节点高可用的方式部署。
在接下来的操作过程中，如无特殊说明，可以给任意一台 Master 节点发送命令。用户也可以为这三个节点配置 DNS 或者 VIP，通过 DNS 和 VIP 来访问。下文以 master_node 代表接受命令的 Master 服务地址和端口，格式如 10.0.0.1:8000。
rapidfs_cli 管理工具
RapidFS 的管理命令均通过 rapidfs_cli 来执行，通常相关的命令应该由管理员来执行。
数据源
RapidFS 作为一个缓存加速服务，可以为指定的数据源提供加速服务，目前支持以下种类的数据源：
- 对象存储 BOS
- 私有化对象存储 ABC Storage
- 兼容 S3 接口的对象存储（目前的支持属于实验性质，不应在生产环境使用）
- HDFS（开发中，敬请期待）
客户需要准备数据源相关的信息提供给管理员，供管理员配置到 RapidFS。每种类型的 Namespace 如何配置请参阅 “创建 Namespace” 章节。
Namespace 管理
创建 Namespace
创建以 BOS、ABC Storage、S3 为数据源的 Namespace
管理员通过以下命令创建对象存储 Namespace：
./rapidfs_cli -op create_bos_namespace \
-group <group> \
-namespace <namespace> \
[-type <type>]
-bucket <bucket_name> \
-source_endpoint <endpoint> \
[-ak <access_key>] [-sk <secret_key>] [-sts_token <sts_token>] \
[-source_prefix <source_prefix>] \
-master_node <master_node>其中，参数的含义如下：
- group: Namespace 所属的 Namespace Group 的名称，在 RapidFS 中，Namespace Group 唯一标识了一组 MetaServer。
- namespace：Namespace 的名字，该名字全局唯一。
- type：可选参数，对象存储的类型，取值可以为 bos、abc_storage、s3。如不指定，默认取值为 bos。
- bucket：对象存储 Bucket 的名字。
- source_endpoint：对象存储的服务地址，百度智能云 BOS 的服务地址请查阅 帮助文档，其它类型的对象存储服务请咨询服务提供商。
- ak、sk、sts_token：可选参数，对象存储的鉴权参数，分别代表 Access Key、Access Sceret Key，和 STS Token。
-
source_prefix：可选参数，不配置会加载整个 Bucket 里的全部数据，配置将仅加载符合指定前缀的对象。例如一个 Bucket A 下有以下数据：
dir1/dir2/file1 dir1/dir2/file2 dir1/dir3/ dir2/file2如果想加载目录
dir1/dir2下的数据，可以指定dir1/dir2/为前缀，RapidFS 将仅加载dir1/dir2/file1和dir1/dir2/file2。注意，末尾的/是必不可少的，理由下面会解释。如果仅想加载
dir1/dir为前缀的数据，可以指定dir1/dir为前缀，那么dir1/dir2/file1、dir1/dir2/file2和dir1/dir3/将会被加载。加载到 RapidFS 的软链接、文件、目录接显示的时候会自动移除
source_prefix前缀。 - master_node：Master 组件的服务地址。
create_bos_namespace 命令成功之后, RapidFS 开始从对象存储导入软链接、文件、目录。在导入完成前，Namespace 处于不可服务的状态。
RapidFS 对文件所做的全部修改都会同步更新到对象存储，但在 RapidFS 中创建的软链接、目录不会同步回对象存储。
RapidFS 导入数据时存在以下限制：
- 名字以
/开头、名字中包含连续/的对象将会被忽略，这是因为尽管/a/b、a/b、a//b在 RapidFS 里会被视作同一个文件，但是在对象存储里却对应 3 个不同的对象，RapidFS 无法区分和处理这种情况。同样，dir1/dir2/file1如果设置dir1/dir2为source_prefix导入，剩余的部分以/开头了，因此也会被忽略。 - 如果同时存在路径相同的目录和文件, 文件将被忽略。例如，同时存在
a/b和a/b/两个对象，用户将只能看到a/b/。
创建以 HDFS 为数据源的 Namespace
开发中，敬请期待。
更新 Namespace
Namespace 创建完之后，管理员可以更新 Namespace 的部分配置：
./rapidfs_cli -op update_namespace \
-namespace <namespace> \
[-source_endpoint <endpoint>] \
[-ak <access_key>] [-sk <secret_key>] [-sts_token <sts_token>] \
-master_node <master_node>其中，参数的含义如下：
- namespace：要更新的 Namespace。
- source_endpoint：可选参数 对象存储的服务地址，百度智能云 BOS 的服务地址请查阅 帮助文档，其它类型的对象存储服务请咨询服务提供商。
- ak、sk、sts_token：可选参数，对象存储的鉴权参数，分别代表 Access Key、Access Sceret Key，和 STS Token。
- master_node：Master 组件的服务地址。
删除 Namespace
当 Namespace 不再使用时，管理员可以删除它：
./rapidfs_cli -op drop_namespace \
-namespace <namespace> \
[-force <true|false>] \
-master_node <master_node>其中，参数的含义如下：
- namespace：要删除的 Namespace。
- force：可选参数，是否强制删除 Namespace，取值为
true或false，默认为false。当为true时，RapidFS 会清理 Namespace 的所有数据；当为false时，RapidFS 仅仅是从 Master 中把 Namespace 的信息删除，Namespace 数据会残留。 - master_node：Master 组件的服务地址。
无论是否使用 force 模式删除 namespace，重复的 Namespace 名字在删除返回成功之后可以再次使用。
查询 Namespace
RapidFS 的 Master 提供了一个简单的网页查询 Namespace 的状态信息，地址是：
http://<master_node>/ns_status下图是网页展示信息的示意图：
任务管理
数据预热
Namespace 正常工作之后，用户可以在任何时候发起数据预热任务，让 RapidFS 主动预热数据：
./rapidfs_cli -op warmup_dataset \
-job_uuid <job_uuid> \
-namespace <namespace> \
[-path <path>] \
-master_node <master_node>其中，参数的含义如下：
- job_uuid：唯一标识一个任务，是一个字符串。
- namespace：要操作的 Namespace。
- path：可选参数，指定一个预热的路径，只有该子树下的文件会被预热。如果不指定，则会预热整个 Namespace。
- master_node：Master 组件的服务地址。
整个预热工作是尽力而为的，在后台执行，如果缓存空间存在不足，会出现预热完之后又被淘汰的情况。任务执行结果在任务完成之后会保留一段时间供查询。对同一个 job_uuid 的 warmup_dataset，在任务信息清理前重复调用，效果等同于查询。
查询任务
在任务发起之后，用户可以查询任务状态：
./rapidfs_cli -op stat_dataset_job \
-job_uuid <job_uuid> \
-master_node <master_node>其中，参数的含义如下：
- job_uuid：唯一标识一个任务，是一个字符串。
- master_node：Master 组件的服务地址。
状态信息在任务完成之后仍然会保留数个小时，在此期间内可以重复查询。
撤销任务
在任务完成前，用户可以撤销任务：
./rapidfs_cli -op cancel_dataset_job \
-job_uuid <job_uuid> \
-master_node <master_node>其中，参数的含义如下：
- job_uuid：唯一标识一个任务，是一个字符串。
- master_node：Master 组件的服务地址。
注意，撤销任务只是让任务不再继续运行，已经产生的变化不会回退。
使用 RapidFS
RapidFS 目前提供两种使用方式，一种是通过 HCFS SDK 集成到 Hadoop 大数据体系，一种是通过 FUSE 客户端挂载到本地使用。
通过 HCFS SDK 使用
修改 hadoop 的配置文件 core-site.xml，添加如下配置：
<property>
<name>fs.rapidfs.impl</name>
<value>com.baidu.bce.bmr.rapidfs.RapidFileSystemImpl</value>
<description>The Rapid FileSystem</description>
</property>
<property>
<name>rapidfs.master.address</name>
<value>10.0.0.1:8000</value>
<description>RapidFS Master 服务地址，可以是一个列表</description>
</property>
<property>
<name>rapidfs.debug.mode</name>
<value>false</value>
<description>是否开启 Debug 模式</description>
</property>
<property>
<name>rapidfs.data.cache.size</name>
<value>50000000000</value>
<description>本地临时数据缓存空间大小，必须比 (2G)2000000000 大</description>
</property>
<property>
<name>rapidfs.data.cache.dir</name>
<value>/ssd1/rapidfs_client/cache_dir</value>
<description>本地临时数据缓存路径, 必须对目录具备写权限</description>
</property>
<property>
<name>rapidfs.internal.config.path</name>
<value>/tmp/rapidfs.conf</value>
<description>RapidFS 的内部配置文件，一般用户无需配置</description>
</property>配置之后，可以通过 RapidFS 提供的 rapidfs.jar 包，直接在 hadoop 中使用 RapidFileSystem 类。
RapidFS 的 schema 为格式为：
rapidfs://namespace_name/path其中，namespace_name 为 Namespace 的名字，path 为实际的文件或目录路径。
通过 FUSE 客户端使用
挂载客户端
通过 rfsmount 挂载 RapidFS：
./rfsmount <local_mount_point> <master_nodes> \
--namespace_name=<namespace_name> \
[--conf=<client.conf>] \
[-o uid=<uid>,gid=<gid>,umask=<umask>...]其中，参数的含义如下：
- local_mount_point：本机挂载目录，必须是一个已经存在的目录。
- master_nodes：Master 组件的服务地址。如果没有配置 VIP 或 DNS，建议此处配置全部 Master 节点，列表以
,隔开，例如10.0.0.1:8000,10.0.0.2:8000,10.0.0.3:8000。 - namespace_name：要挂载的 Namespace。
- conf：可选参数 用户可以指定一个额外的配置文件，传递其它参数。
- -o uid=
,gid= ,umask= ...：FUSE 支持的参数仍然可以通过 -o 选项传递，具体可参见 FUSE 帮助文档。性能相关的参数 rfsmount 已经做了充分调优，不建议用户直接调整，如确需调整，应该优先参考 rfsmount 提供的配置项。权限相关的参数如何配置参见rfsmount 的建议安全配置-2. 限制挂载点的使用权限。
一般情况下，客户可能会关注的额外配置项包括：
# --- 日志相关 ---
# 日志级别为 INFO/NOTICE/WARNING/FATAL，取值分别为 0、1、2、3
# 详细 debug 日志，设置值为 88 打开，0 为关闭
--verbose=0
# --- FUSE 相关 ---
# 属性缓存超时时间，单位是秒
--rapidfs_fuse_attr_timeout_s=3
# 目录项查找缓存超时时间，单位是秒
--rapidfs_fuse_entry_timeout_s=3
# 处理请求的并发度
--rapidfs_fuse_concurrency=64
# 是否开启 close-to-open 一致性。如果开启，每次 open 文件都会校验文件是否变化。如果不打开，只有属性、目录项缓存超时才会校验。开启此选项对小文件性能影响较大，数据变化较少的场景不建议打开
--rapidfs_fuse_cto=0
# 预读参数。0 会根据 RapidFS 内部的数据切片大小自适应（默认为 4MB），负数值（如 -1）为关闭预读
--rapidfs_fuse_readahead_kb=0更多的配置参见客户端内置网页的 flags 子页面（参见查看客户端内置网页）。
rfsmount 的建议安全配置
我们建议将挂载权限收缩到只有 root，同时配合合适的 uid、gid、umask 限制只有指定用户/用户组可以访问挂载点的数据。
1. 限制 rfsmount 只有 root 才能执行
在未安装 fuse3 的情况下，rfsmount 只能被 root 执行，无需特殊处理。如果安装了 fuse3，默认情况下任何客户都可以执行 rfsmount，建议做一些处理来限制执行权限。
用户可以以 root 用户执行以下命令确认 fuse3 是否安装：
which fusermount3如果提示 /usr/bin/which: no fusermount3 in 则表明系统未安装 fuse3。
如果已经安装了 fuse3，可以通过以下步骤限制挂载权限到只有 root 可以执行：
# 移除 other 用户的可执行权限
chmod o-x `/usr/bin/which fusermount3`2. 限制挂载点的使用权限
rfsmount 默认赋予所有软链接、文件、文件夹 0777 权限，即所有的客户均具有读写和执行权限。如果有更严格的权限控制需求，用户可以通过 FUSE 提供的 uid、gid、umask 参数来控制。例如：
./rfsmount /mnt 10.0.0.1:8000 --namespace_name=test -o uid=1001,gid=1002,umask=0007这条挂载命令通过 umask=0007 撤销了 other 用户的读、写、访问权限，所有软链接、文件、文件夹权限变为 0770。命令同时通过 uid=1001、gid=1002 设定了挂载点所属的用户和用户组。
更多说明请阅读 FUSE 帮助文档。
查看客户端内置网页
rfsmount 是基于 bprc 实现的，通过在工作目录下创建 dummy_server.port 文件，可以开启 brpc 的内置网页：
echo 8111 > dummy_server.port上述命令在 8111 端口启动了 brpc 的内置页面。一般情况下，用户关心的包括 vars 和 flags 两个子页面：
- vars：vars 页面包含系统的各类监控信息，搜索
rapidfs_可以快速筛选，监控项的名字简单明了，不再详细解释。 - flags：包含系统可以调节的全部配置信息，和 rfsmount 相关的配置项主要是以
rapidfs_fuse_和rapidfs_client_开头，相关配置均有简要说明。
使用客户端
挂载成功之后，用户可以像本地文件系统一样使用 RapidFS。对所有的数据源，RapidFS 均支持随机读、顺序读、顺序写，但对随机写的支持取决于底层的数据源：
- 当数据源是对象存储时，对随机写的支持较弱，已经存在的对象随机写会导致所有的数据拷贝一遍。
- 当数据源是 HDFS 时，不支持随机写。
整体上，RapidFS 不适合对随机写要求较高的场景。
卸载客户端
当不再使用客户端时，用户可以通过 umount 命令卸载挂载点：
umount <local_mount_point>其中，参数的含义如下：
- local_mount_point：本机挂载目录。