cubefs/docs-zh/source/dev-guide/admin-api/master/volume.md

卷管理

创建

curl -v "http://10.196.59.198:17010/admin/createVol?name=test&capacity=100&owner=cfs&mpCount=3"

为用户创建卷，并分配一组数据分片和元数据分片. 在创建新卷时，默认分配10个数据分片和3个元数据分片。

CubeFS以 Owner 参数作为用户ID。

• 在创建卷时，如果集群中没有与该卷的 Owner 同名的用户，会自动创建一个用户 ID 为 Owner 的用户
• 如果集群中已存在用户 ID 为 Owner 的用户，则会自动将该卷的所有权归属于该用户。

详情参阅：用戶说明

参数列表

参数	类型	描述	必需	默认值
name	string	卷名称	是	无
volType	int	卷类型：0-副本卷，1-纠删码卷	否	0
capacity	int	卷的配额，单位是GB	是	无
owner	string	卷的所有者，同时也是用户 ID	是	无
mpCount	int	初始化元数据分片个数	否	3
dpCount	int	初始化数据分片个数	否	默认10， 最大值200
replicaNum	int	副本数	否	副本卷默认3（支持1,3），纠删码卷默认1（支持1-16个）
dpSize	int	数据分片大小上限，单位 GB	否	120
enablePosixAcl	bool	是否配置 posix 权限限制	否	false
followerRead	bool	允许从 follower 读取数据，纠删码卷默认 true	否	false
crossZone	bool	是否跨区域，如设为 true，则不能设置 zoneName 参数	否	false
normalZonesFirst	bool	是否优先写普通域	否	false
zoneName	string	指定区域	否	如果 crossZone 设为 false，则默认值为 default
cacheRuleKey	string	纠删码卷使用	否	非空时，匹配该字段的才会写入 cache，空
ebsBlkSize	int	每个块的大小，单位 byte	否	默认8M
cacheThreshold	int	纠删码卷小于该值时，才写入到 cache 中，单位 byte	否	默认10M

删除

curl -v "http://10.196.59.198:17010/vol/delete?name=test&authKey=md5(owner)"

首先把卷标记为逻辑删除（status 设为1），然后通过周期性任务删除所有数据分片和元数据分片，最终从持久化存储中删除。

::: warning 注意

1. 纠删码卷使用大小为0时才能删除；
2. 从 v3.3.1 起，卷的 Dentry 数需要小于配置项 volDeletionDentryThreshold 的值才允许删除，此配置项为整型数字，默认值为0 :::

在删除卷的同时，将会在所有用户的信息中删除与该卷有关的权限信息。

参数列表

参数	类型	描述
name	string	卷名称
authKey	string	计算 vol 的所有者字段的32位 MD5 值作为认证信息

查询卷详细信息

curl -v "http://10.196.59.198:17010/admin/getVol?name=test" | python -m json.tool

展示卷的基本信息，包括卷的名字、所有的数据分片和元数据分片信息等。

参数列表

参数	类型	描述
name	string	卷名称

响应示例

{
    "Authenticate": false,
     "CacheRule": "",
     "CacheThreshold": 10485760,
     "Capacity": 10,
     "CreateTime": "2022-03-31 16:08:31",
     "CrossZone": false,
     "DefaultPriority": false,
     "DefaultZonePrior": false,
     "DentryCount": 0,
     "Description": "",
     "DomainOn": false,
     "DpCnt": 0,
     "DpReplicaNum": 16,
     "DpSelectorName": "",
     "DpSelectorParm": "",
     "FollowerRead": true,
     "ID": 706,
     "InodeCount": 1,
     "MaxMetaPartitionID": 2319,
     "MpCnt": 3,
     "MpReplicaNum": 3,
     "Name": "abc",
     "NeedToLowerReplica": false,
     "ObjBlockSize": 8388608,
     "Owner": "cfs",
     "PreloadCapacity": 0,
     "RwDpCnt": 0,
     "Status": 0,
     "VolType": 1,
     "ZoneName": "default"
}

查询卷数据分片详细信息

curl -v "http://192.168.0.12:17010/client/partitions?name=ltptest" | python -m json.tool

展示卷的所有的数据分片信息

参数列表

参数	类型	描述
name	string	卷名称

响应示例

{
    "Epoch": 0,
    "Hosts": [
        "192.168.0.34:17310",
        "192.168.0.33:17310",
        "192.168.0.32:17310"
    ],
    "IsRecover": false,
    "LeaderAddr": "192.168.0.33:17310",
    "PartitionID": 4,
    "ReplicaNum": 3,
    "Status": 2
}

查询卷元数据分片详细信息

curl -v "http://192.168.0.12:17010/client/metaPartitions?name=ltptest" | python -m json.tool

展示卷的所有的元数据分片信息

参数列表

参数	类型	描述
name	string	卷名称

响应示例

{
    "DentryCount": 1,
    "End": 16777216,
    "InodeCount": 1,
    "IsRecover": false,
    "LeaderAddr": "192.168.0.23:17210",
    "MaxInodeID": 3,
    "Members": [
        "192.168.0.22:17210",
        "192.168.0.23:17210",
        "192.168.0.24:17210"
    ],
    "PartitionID": 1,
    "Start": 0,
    "Status": 2
}

统计

curl -v http://10.196.59.198:17010/client/volStat?name=test

展示卷的总空间大小、已使用空间大小及是否开启读写 token 控制的信息。

参数列表

参数	类型	描述
name	string	卷名称
version	int	卷版本：0-副本卷，1-ec-卷。默认0-副本卷，访问纠删码卷必填

响应示例

{
    "CacheTotalSize": 0,
    "CacheUsedRatio": "",
    "CacheUsedSize": 0,
    "EnableToken": false,
    "InodeCount": 1,
    "Name": "abc-test",
    "TotalSize": 10737418240,
    "UsedRatio": "0.00",
    "UsedSize": 0
}

更新

curl -v "http://10.196.59.198:17010/vol/update?name=test&capacity=100&authKey=md5(owner)"

增加卷的配额，也可调整其它相关参数。

参数列表

参数	类型	描述	必需
name	string	卷名称	是
description	string	卷描述信息	否
authKey	string	计算 vol 的所有者字段的32位MD5值作为认证信息	是
capacity	int	更新卷的 datanode 容量，单位G, 副本卷不能小于已使用容量	否
zoneName	string	更新后所在区域，若不设置将被更新至 default 区域	是
followerRead	bool	允许从 follower 读取数据，若设置为 true，客户端也需配置该字段为 true	否
enablePosixAcl	bool	是否配置 posix 权限限制	否
emptyCacheRule	string	是否置空 cacheRule	否
cacheRuleKey	string	缓存规则，纠删码卷使用，满足对应规则的才缓存	否
ebsBlkSize	int	纠删码卷的每个块的大小	否
cacheCap	int	纠删码卷使用二级 cache 时，cache 的容量大小	否
cacheAction	int	纠删码卷使用，0-不写 cache, 1-读数据写 cache, 2-读写数据都写到 cache	否
cacheThreshold	int	缓存文件大小限制，纠删码卷小于该值时，才会写到 cache 当中	否
cacheTTL	int	缓存过期时间，单位天	否
cacheHighWater	int	淘汰高水位	否
cacheLowWater	int	缓存淘汰低水位	否
cacheLRUInterval	int	缓存检测周期，单位分钟	否

获取卷列表

curl -v "http://10.196.59.198:17010/vol/list?keywords=test"

获取全部卷的列表信息，可按关键字过滤。

参数列表

参数	类型	描述	必需
keywords	string	获取卷名包含此关键字的卷信息	否

响应示例

[
   {
       "Name": "test1",
       "Owner": "cfs",
       "CreateTime": 0,
       "Status": 0,
       "TotalSize": 155515112832780000,
       "UsedSize": 155515112832780000
   },
   {
       "Name": "test2",
       "Owner": "cfs",
       "CreateTime": 0,
       "Status": 0,
       "TotalSize": 155515112832780000,
       "UsedSize": 155515112832780000
   }
]

扩容

curl -v "http://10.196.59.198:17010/vol/expand?name=test&capacity=100&authKey=md5(owner) "

对指定卷进行扩容到指定容量

参数列表

参数	类型	描述	必需
name	string	卷名称	是
authKey	string	计算 vol 的所有者字段的32位 MD5 值作为认证信息	是
capacity	int	扩充后卷的配额,单位是GB	是

缩容

curl -v "http://10.196.59.198:17010/vol/shrink?name=test&capacity=100&authKey=md5(owner) "

对指定卷进行缩小到指定容量

参数列表

参数	类型	描述	必需
name	string	卷名称	是
authKey	string	计算 vol 的所有者字段的32位 MD5 值作为认证信息	是
capacity	int	压缩后卷的配额,单位是GB	是

回收站

curl -v "http://127.0.0.1:17010/vol/setTrashInterval?name=test&authKey=trashInterval=7200" 

对指定卷开启/关闭回收站功能

参数列表

参数	类型	描述	必需
name	string	卷名称	是
authKey	string	计算 vol 的所有者字段的32位 MD5 值作为认证信息	是
trashInterval	int	回收站清理过期数据的时间间隔，单位分钟。0关闭回收站，其他正值开启回收站	是

回收站

curl -v "http://127.0.0.1:17010/vol/setTrashInterval?name=test&authKey=trashInterval=7200" 

对指定卷开启/关闭回收站功能

参数列表

参数	类型	描述	必需
name	string	卷名称	是
authKey	string	计算vol的所有者字段的32位 MD5 值作为认证信息	是
trashInterval	int	回收站清理过期数据的时间间隔，单位分钟。0关闭回收站，其他正值开启回收站	是

两副本

主要事项

两个副本可以正常支持修改和写入（使用其他 dp 及其范围）

1. 支持已创建的3副本卷设置2副本，并在创建新 dp 生效，但不包括老的 dp。
2. 两副本卷有一个副本崩溃然后没有 leader 的情况下，使用 raftForceDel 参数删除异常副本。

异常场景处理

例如存在一个dp，有两个副本A、B

两副本迁移的异常场景

迁移目标是C，我们实现的过程是先添加副本C，然后删除源A，迁移过程B crash。解决方式： 如果 B crash了，raft 不可用，先删除B，等待迁移完成，删除A，再添加一个副本

正常运营过程某一个副本crash，例如B

没有 leader，根据 raft 规则两副本不能删除B的，因为需要先 commit，然后 apply，但 commit 的条件是大多数存活。解决方式： 强制删除B

::: danger 警告 raft 支持新接口 del，replica 直接不使用 raft log commit（先备份dp数据） :::

curl "http://127.0.0.1:17010/dataReplica/delete?raftForceDel=true&addr=127.0.0.1:17310&id=47128

• addr 为副本B的地址
• id 为分区id（dpid）
• raftForceDel 强制删除 raft 副本
• DataNode 将检查副本数（volume 和 dp 必须都是 2 个副本，以防使用不当）和 force 字段。

命令行

1. 两副本卷的创建

curl -v "http://192.168.0.11:17010/admin/createVol?name=2replica&capacity=100&owner=cfs&mpCount=3&replicaNum=2&followerRead=true"

2. 原有三副本卷降为两副本

• 存量的数据只读（建议批量脚本执行）

curl -v "http://192.168.0.13:17010/admin/setDpRdOnly?id=**&rdOnly=true"

• 更新卷副本数量，更新后3副本分区会异步降低为2副本

curl -v "http://192.168.0.13:17010/vol/update?name=ltptest&replicaNum=2&followerRead=true&authKey=0e20229116d5a9a4a9e876806b514a85"

• 强制删除(无 leader 情况下使用，注意：确定删除副本已经不可用)

curl "10.86.180.77:17010/dataReplica/delete?raftForceDel=true&addr=10.33.64.33:17310&id=47128"  

流控

主要事项

• 考虑到不区分 volume 的存储组件，在 client 端做 volume 限流
• 分布式场景，需要中心控制 client 端流量，master 做中心，保证 iops，不增加额外流控 server，可以减少运维压力
• client 采用幂函数控制流量增长，在流量在资源充足的场景下，可以快速增长
• 保证 volume 整体流量调控下平稳
• master 可以均衡客户端流量，根据客户端请求情况自适应调节

配置项

无配置项，通过url命令设置

QOS流控参数及接口

• 创建卷时启用QOS：

# 启用qos，写流量设置为10000MB
curl -v "http://192.168.0.11:17010/admin/createVol?name=volName&capacity=100&owner=cfs&qosEnable=true&flowWKey=10000"

• 获取卷的流量情况：

curl  "http://192.168.0.11:17010/qos/getStatus?name=ltptest"

• 获取客户端数据：

curl  "http://192.168.0.11:17010/qos/getClientsInfo?name=ltptest"

• 更新服务端参数，关闭、启用流控，调节读写流量值：

curl  "http://192.168.0.11:17010/qos/update?name=ltptest&qosEnable=true&flowWKey=100000"|jq

涉及字段包括：

• FlowWKey = "flowWKey" 写（卷）
• FlowRKey = "flowRKey" 读（卷）

一些系统参数说明

1. 默认单位

无论是 client 端还是 datanode 端，目前流量都是 MB 为单位

2. 最低参数流量和 io，作用于 datanode 和 volume 的设置，如果设置值，则需要保证一下要求，否则报错

   • MinFlowLimit = 100 * util.MB
   • MinIoLimit = 100

3. 如果没有设置流量值，但启用限流，则使用默认值（Byte）

   • defaultIopsRLimit uint64 = 1 << 16
   • defaultIopsWLimit uint64 = 1 << 16
   • defaultFlowWLimit uint64 = 1 << 35
   • defaultFlowRLimit uint64 = 1 << 35

Client 和 Master通信

1. Client 长时间收不到 Master 的流量控制，日志会 warn 出来
2. Client 和 Master 无法不通讯，会维持原有流量限制，也会 warn 出来
3. 流量长时间为 0 则不会主动请求 Master 流量，不上报给 Master，减少通信请求。Master 会清理长时间不上报客户端信息。

冷卷

1. 读一级缓存不算作流量
2. cache 写不计入写流量控制
3. 其他都算作流量