此操作用来初始化HBlock，如果服务端返回202响应码，则表示开始执行初始化操作。

说明

安装完所有服务器后，需要初始化HBlock。

注意

使用API初始化时，需要使用默认用户名和初始密码进行签名，默认用户名为storuser，初始密码为123456。初始化时必须重新设置密码，后续使用其他接口时使用新设置的密码进行签名。
请确保Linux用户具有所需要端口的权限。Linux系统默认小于1024的端口不对没有root权限的Linux普通用户开放。
设置端口范围（portRange）时，请避免和Linux系统的本地临时端口（ip_local_port_range）范围重合，否则可能会导致HBlock服务所用的端口被占用。使用命令行cat /proc/sys/net/ipv4/ip_local_port_range可以查看本地临时端口范围。

请求语法

单机版


POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization

{
    "storName": storName,
    "userName": userName,
    "newPassword": newPassword,
    "iSCSIPort": iSCSIPort,
    "portRange": port1-port2,
    "ports": {
        "managementPort1": managementPort1,
        "managementPort2": managementPort2,
        "managementPort3": managementPort3,
        "managementPort4": managementPort4,
        "managementPort6": managementPort6
    },
    "servers": [
        {
            "ip": ip,
            "apiPort": apiPort,
            "diskPaths": [
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
……
            ]
        }
    ],
    "publicNetwork": publicNetwork
}

集群版（服务器IP导入）

POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization

{
    "storName": storName,
    "userName": userName,
    "newPassword": newPassword,
    "iSCSIPort": iSCSIPort,
    "portRange": port1-port2,
    "faultDomain": "faultDomain",
    "ports": {
        "dataPort1": dataPort1,
        "managementPort1": managementPort1,
        "managementPort2": managementPort2,
        "managementPort3": managementPort3,
        "managementPort4": managementPort4,
        "managementPort5": managementPort5,
        "managementPort6": managementPort6,
        "metadataPort1": metadataPort1,
        "metadataPort2": metadataPort2,
        "metadataPort3": metadataPort3,
        "metadataPort4": metadataPort4,
        "metadataPort5": metadataPort5,
        "metadataPort6": metadataPort6,
        "metadataPort7": metadataPort7,
        "metadataPort8": metadataPort8
    },
    "servers": [
        {
            "nodeName": servername,
            "ip": ip,
            "apiPort": apiPort,
            "diskPaths": [
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
……
            ]
        },
……
{
            "nodeName": servername,
            "ip": ip,
            "apiPort": apiPort,
            "diskPaths": [
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
……
            ]
        }
    ],
    "services": {
        "mdm": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ],
        "ls": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ],
        "cs": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ]
    },
    "clusterNetwork": clusterNetwork,
    "publicNetwork": publicNetwork
}

集群版（导入拓扑文件）

POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization

{
    "storName": storName,
    "userName": userName,
    "newPassword": newPassword,
    "iSCSIPort": iSCSIPort,
    "portRange": port1-port2,
    "faultDomain": faultDomain,
    "topology": topologyString,
    "ports": {
        "dataPort1": dataPort1,
        "managementPort1": managementPort1,
        "managementPort2": managementPort2,
        "managementPort3": managementPort3,
        "managementPort4": managementPort4,
        "managementPort5": managementPort5,
        "managementPort6": managementPort6,
        "metadataPort1": metadataPort1,
        "metadataPort2": metadataPort2,
        "metadataPort3": metadataPort3,
        "metadataPort4": metadataPort4,
        "metadataPort5": metadataPort5,
        "metadataPort6": metadataPort6,
        "metadataPort7": metadataPort7,
        "metadataPort8": metadataPort8
    },
    "services": {
        "mdm": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ],
        "ls": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ],
        "cs": [
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            },
            {
                "ip": ip,
                "metaDir": path
            }
        ]
    },
    "clusterNetwork": clusterNetwork,
    "publicNetwork": publicNetwork
}

请求参数

参数	类型	描述	是否必须
storName	String	HBlock名称。取值：长度范围是1~64，可以包含字母、数字、下划线（_）和短横线（-），字母区分大小写，且仅支持以字母或数字开头。	是
userName	String	HBlock的管理员用户名。取值：长度范围是5~16，只能由数字和字母组成，字母区分大小。默认值为storuser。	否
newPassword	String	设置的新密码。初始化时必须修改密码。取值：长度范围8~16，至少包含以下字符中的3种：大写字母、小写字母、数字、特殊字符 (~ ! @ # $ % ^ & * ( ) _ + [ ] { } \| ; : , . / < > ?)，区分大小写。不能包含：3个连续重复的字符，3个连续或反序的数字、或字母（不区分大小写），3个连续或反序的键盘序列（不区分大小写）。	是
iSCSIPort	Integer	iSCSI端口。取值：[1, 65535]，默认值为3260。	否
portRange	String	指定端口范围。存储服务以及未指定端口的服务将从此范围中自动取值。取值：[1, 65535]，port1为端口范围最小值，port2为端口范围最大值，且port1 < port2。port1默认取值为20000，port2默认取值为20500。说明建议指定的端口范围至少包含500个端口。	否
faultDomain	String	设置基础存储池的故障域级别（仅集群版支持）。初始化时设置的集群拓扑中，包含的数据目录节点都加入到基础存储池中。取值： room：机房级别。 rack:机架级别。 path：数据目录级别。 server：服务器级别。默认值为server。注意如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。	否
ports.dataPort1	Integer	数据端口1（仅集群版支持）。取值：[1, 65535]。	否
ports.managementPort1	Integer	管理服务端口1。取值：[1, 65535]。	否
ports.managementPort2	Integer	管理服务端口2。取值：[1, 65535]。	否
ports.managementPort3	Integer	管理服务端口3。取值：[1, 65535]。	否
ports.managementPort4	Integer	管理服务端口4。取值：[1, 65535]。	否
ports.managementPort5	Integer	管理服务端口5（仅集群版支持）。取值：[1, 65535]。	否
ports.managementPort6	Integer	管理服务端口6。取值：[1, 65535]。	否
ports.metadataPort1	Integer	元数据端口1（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort2	Integer	元数据端口2（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort3	Integer	元数据端口3（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort4	Integer	元数据端口4（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort5	Integer	元数据端口5（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort6	Integer	元数据端口6（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort7	Integer	元数据端口7（仅集群版支持）。取值：[1, 65535]。	否
ports.metadataPort8	Integer	元数据端口8（仅集群版支持）。取值：[1, 65535]。	否
topology	String	导入集群拓扑文件内容（仅集群版支持）。取值：拓扑文件需要采用UTF-8编码，且为JSON文件格式，然后转换成字符串格式复制给该参数。拓扑文件的构成详见集群拓扑文件。注意 “topology”与“servers”必须选一种，且只能选一种。如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。	否
servers	Array of server	HBlock服务器的属性集合，详见“表1 请求参数server说明（仅集群版支持）”。注意 “topology”与“servers”必须选一种，且只能选一种。如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。	否
services	Array of server	服务地址的集合（仅集群版支持），详见“表3 请求参数service说明（仅集群版支持）”。	否
clusterNetwork	String	集群网络（仅集群版支持），用于集群间的数据通信。如果指定集群网络，为了保证HBlock的各个服务器之间能够正常通信，请确保每个服务器上都有与指定网段相符的IP，系统会自动选取该IP进行通信。如果未指定集群网络，默认使用服务器列表中HBlock服务器IP，此时HBlock的服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。取值：如果指定地址范围，IP地址后加掩码表示，如192.163.1.5/24。	否
publicNetwork	String	业务网络，用于客户端和HBlock之间的数据传输式。如果指定业务网络，请确保每个服务器上都有与指定网段相符的IP，系统会自动选取该IP和客户端进行通信。如果未指定业务网络，或指定了业务网络，但指定的网段与服务器所有IP均不相符，默认使用服务器列表中HBlock服务器IP，此时HBlock服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。取值：如果指定地址范围，IP地址后加掩码表示，如192.163.1.5/24列表。	否

表1 请求参数servers说明

参数	类型	描述	是否必须
nodeName	String	拓扑节点名称。取值：字符串形式，长度范围1~63，只能由字母、数字、句点(.)、下划线（_）和短横线(-)组成，字母区分大小写，且仅支持以字母或数字开头。	否
ip	String	HBlock的服务器IP。取值：IPv4或[IPv6]地址。	是
apiPort	Integer	管理API端口。取值：[1, 65535]，默认值为1443。需要和该服务器安装HBlock时设置的API端口号保持一致。	否
diskPaths	Array of server	数据目录属性集合，详见“表2 请求参数diskPaths说明”。	否

表2 请求参数diskPath说明

参数	类型	描述	是否必须
path	String	指定数据目录。数据目录用于存储数据，建议不要与操作系统共用磁盘或文件系统。数据目录中不能有逗号（,）。说明对于单机版，第一个数据目录为默认数据目录。对于集群版，需要至少有一个数据目录。注意如果故障域是server和path级别，此项必填。	否
capacityQuota	Long	指定数据目录的容量配额，即针对加入到服务器中的每个数据目录，HBlock可写入的数据总量。当HBlock的使用空间一旦达到配额，就立刻阻止数据写入，不允许再使用超出配额的空间。取值：小于数据目录所在磁盘的总容量，单位是字节。负整数表示无限制写入，0表示禁止写入。默认不限制写入。注意如果相同的数据目录出现多次，以第一次出现的数据目录的容量配额为准。	否

参数

类型

描述

是否必须

path

String

指定数据目录。数据目录用于存储数据，建议不要与操作系统共用磁盘或文件系统。数据目录中不能有逗号（,）。

说明

对于单机版，第一个数据目录为默认数据目录。对于集群版，需要至少有一个数据目录。

注意

如果故障域是server和path级别，此项必填。

否

capacityQuota

Long

指定数据目录的容量配额，即针对加入到服务器中的每个数据目录，HBlock可写入的数据总量。当HBlock的使用空间一旦达到配额，就立刻阻止数据写入，不允许再使用超出配额的空间。

取值：小于数据目录所在磁盘的总容量，单位是字节。负整数表示无限制写入，0表示禁止写入。默认不限制写入。

注意

如果相同的数据目录出现多次，以第一次出现的数据目录的容量配额为准。

否

表3 请求参数services说明（仅集群版支持）

参数	类型	描述	是否必须
mdm	Array of mdm	元数据管理服务（仅集群版支持），详见“表4 请求参数mdm说明（仅集群版支持）”。	否
ls	Array of ls	日志服务（仅集群版支持），详见“表5 请求参数ls说明（仅集群版支持）”。	否
cs	Array of cs	协调服务（仅集群版支持），详见“表6 请求参数cs说明（仅集群版支持）”。	否

表4 请求参数mdm说明（仅集群版支持）

参数	类型	描述	是否必须
ip	String	元数据管理服务的地址（仅集群版支持）。如果指定元数据管理服务的地址，必须同时指定集群中的2个IP地址。取值：IPv4或[IPv6]地址。	否
metaDir	String	元数据服务的数据目录（仅集群版支持），用于存储元数据服务的相关数据信息。说明为了提升读写性能，建议元数据服务的数据目录与安装目录、存储数据的数据目录分开。取值：数据目录名不能含逗号。默认目录为安装目录。	否

参数

类型

描述

是否必须

String

元数据管理服务的地址（仅集群版支持）。

如果指定元数据管理服务的地址，必须同时指定集群中的2个IP地址。

取值：IPv4或[IPv6]地址。

否

metaDir

String

元数据服务的数据目录（仅集群版支持），用于存储元数据服务的相关数据信息。

说明

为了提升读写性能，建议元数据服务的数据目录与安装目录、存储数据的数据目录分开。

取值：数据目录名不能含逗号。默认目录为安装目录。

否

表5 请求参数ls说明（仅集群版支持）

参数	类型	描述	是否必须
ip	String	日志服务的地址（仅集群版支持）。如果指定日志服务的地址，必须同时指定集群中的3个IP地址。取值：IPv4或[IPv6]地址。	否
metaDir	String	日志服务的数据目录（仅集群版支持），用于存储日志服务的相关数据信息。说明为了提升读写性能，建议日志服务的数据目录与安装目录、存储数据的数据目录分开。取值：数据目录名不能含逗号。默认目录为安装目录。	否

参数

类型

描述

是否必须

String

日志服务的地址（仅集群版支持）。

如果指定日志服务的地址，必须同时指定集群中的3个IP地址。

取值：IPv4或[IPv6]地址。

否

metaDir

String

日志服务的数据目录（仅集群版支持），用于存储日志服务的相关数据信息。

说明

为了提升读写性能，建议日志服务的数据目录与安装目录、存储数据的数据目录分开。

取值：数据目录名不能含逗号。默认目录为安装目录。

否

表6 请求参数cs说明（仅集群版支持）

参数	类型	描述	是否必须
ip	String	协调服务的地址（仅集群版支持）。如果指定协调服务的地址，必须同时指定集群中的3个IP地址。取值：IPv4或[IPv6]地址。	否
metaDir	String	协调服务的数据目录（仅集群版支持），用于存储协调服务的相关数据信息。说明为了提升读写性能，建议协调服务的数据目录与安装目录、存储数据的数据目录分开。取值：数据目录名不能含逗号。默认目录为安装目录。	否

参数

类型

描述

是否必须

String

协调服务的地址（仅集群版支持）。

如果指定协调服务的地址，必须同时指定集群中的3个IP地址。

取值：IPv4或[IPv6]地址。

否

metaDir

String

协调服务的数据目录（仅集群版支持），用于存储协调服务的相关数据信息。

说明

为了提升读写性能，建议协调服务的数据目录与安装目录、存储数据的数据目录分开。

取值：数据目录名不能含逗号。默认目录为安装目录。

否

请求示例1

单机版：初始化。

POST /rest/v1/system/setup HTTP/1.1
Date: Mon, 11 Dec 2023 06: 06: 47 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 543
Host: 192.168.0.32: 1443 
Authorization: HBlock storuser:signature

{
    "storName": "stor1",
    "newPassword": "*********",
    "portRange": "20000-20500",
    "iSCSIPort": 3260,
    "servers": [
        {
            "ip": "192.168.0.32",
            "apiPort": 1443,
            "diskPaths": [
                {
                    "path": "/mnt/storage01",
                    "capacityQuota": 96636764160
                },
                {
                    "path": "/mnt/dskb",
                    "capacityQuota": 96636764160
                }
            ]
        }
    ]
}

响应示例1

HTTP/1.1 202 Accepted 
x-hblock-request-id: 6589a0abcbde4bc5a4db3a6b9315008f
Connection: keep-alive
Date: Mon, 11 Dec 2023 06:06:47 GMT
Content-Length: 0
Server: HBlockqi

请求示例2

集群版：输入服务器IP，初始化。

POST /rest/v1/system/setup HTTP/1.1
Date: Wed, 24 Jan 2024 06: 59: 48 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1344
Host: 192.168.0.110: 1443 
Authorization: HBlock storuser:signature

{
    "storName": "stor1",
    "userName": "storuser1",
    "newPassword": "********",
    "iSCSIPort": 3260,
    "portRange": "20000-20500",
    "faultDomain": "path",
    "servers": [
        {
            "ip": "192.168.0.110",
            "apiPort": 1443,
            "diskPaths": [
                {
                    "path": "/mnt/storage01",
                    "capacityQuota": 96636764160
                }
            ]
        },
        {
            "ip": "192.168.0.192",
            "apiPort": 1443,
            "diskPaths": [
                {
                    "path": "/mnt/stor",
                    "capacityQuota": 96636764160
                }
            ]
        },
        {
            "ip": "192.168.0.102",
            "apiPort": 1443,
            "diskPaths": [
                {
                    "path": "/mnt/stor",
                    "capacityQuota": 96636764160
                }
            ]
        }
    ],
    "services": {
        "mdm": [
            "192.168.0.110",
            "192.168.0.192"
        ],
        "ls": [
            "192.168.0.110",
            "192.168.0.192",
            "192.168.0.102"
        ],
        "cs": [
            "192.168.0.110",
            "192.168.0.192",
            "192.168.0.102"
        ]
    }
}

响应示例2

HTTP/1.1 202 Accepted 
x-hblock-request-id: 096e457a5c26465590ff8f312a493f2c
Connection: keep-alive
Date: Wed, 24 Jan 2024 06: 59: 48 GMT
Content-Length: 0
Server: HBlock

请求示例3

集群版：导入拓扑文件进行初始化。

POST /rest/v1/system/setup HTTP/1.1
Date: Wed, 3 Jul 2024 09: 47: 16 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2302
Host: 192.168.0.110: 1443 
Authorization: HBlock storuser:signature

{
    "storName": "stor1",
    "UserName": "storuser",
    "newPassword": "hblock12@",
    "iSCSIPort": 3260,
    "portRange": "20000-20500",
    "faultDomain": "room",
    "topology": "{\r\n    \"name\": \"default\",\r\n    \"childNodes\": [\r\n        {\r\n            \"name\": \"room1\",\r\n            \"type\": \"room\",\r\n            \"childNodes\": [\r\n                {\r\n                    \"type\": \"server\",\r\n                    \"name\": \"server1\",\r\n                    \"ip\": \"192.168.0.192\",\r\n                    \"apiPort\": 1443,\r\n                    \"childNodes\": [\r\n                        {\r\n                            \"name\": \"/mnt/stor\",\r\n                            \"type\": \"path\"\r\n                        },\r\n                        {\r\n                            \"name\": \"/mnt/storage01\",\r\n                            \"type\": \"path\"\r\n                        }\r\n                    ]\r\n                },\r\n                {\r\n                    \"type\": \"server\",\r\n                    \"name\": \"server2\",\r\n                    \"ip\": \"192.168.0.110\",\r\n                    \"apiPort\": 1443,\r\n                    \"childNodes\": [\r\n                        {\r\n                            \"name\": \"/mnt/stor\",\r\n                            \"type\": \"path\"\r\n                        }\r\n                    ]\r\n                },\r\n                {\r\n                    \"type\": \"server\",\r\n                    \"name\": \"server3\",\r\n                    \"ip\": \"192.168.0.102\",\r\n                    \"apiPort\": 1443,\r\n                    \"childNodes\": [\r\n                        {\r\n                            \"name\": \"/mnt/stor\",\r\n                            \"type\": \"path\"\r\n                        }\r\n                    ]\r\n                }\r\n            ]\r\n        }\r\n    ]\r\n}",
    "services": {
        "mdm": [
            "192.168.0.110",
            "192.168.0.192"
        ],
        "ls": [
            "192.168.0.110",
            "192.168.0.192",
            "192.168.0.102"
        ],
        "cs": [
            "192.168.0.110",
            "192.168.0.192",
            "192.168.0.102"
        ]
    }
}

说明

拓扑文件内容为转换为字符串后的符合UTF-8编码格式的JSON文件。拓扑文件的源码如下。

{
    "name": "default",
    "childNodes": [
        {
            "name": "room1",
            "type": "room",
            "childNodes": [
                {
                    "type": "server",
                    "name": "server1",
                    "ip": "192.168.0.192",
                    "apiPort": 1443,
                    "childNodes": [
                        {
                            "name": "/mnt/stor",
                            "type": "path"
                        },
                        {
                            "name": "/mnt/storage01",
                            "type": "path"
                        }
                    ]
                },
                {
                    "type": "server",
                    "name": "server2",
                    "ip": "192.168.0.110",
                    "apiPort": 1443,
                    "childNodes": [
                        {
                            "name": "/mnt/stor",
                            "type": "path"
                        }
                    ]
                },
                {
                    "type": "server",
                    "name": "server3",
                    "ip": "192.168.0.102",
                    "apiPort": 1443,
                    "childNodes": [
                        {
                            "name": "/mnt/stor",
                            "type": "path"
                        }
                    ]
                }
            ]
        }
    ]
}

响应示例3

HTTP/1.1 202 Accepted 
x-hblock-request-id: 068e0a8e16884bf28104b0e84fdbc50e
Connection: keep-alive
Date: Wed, 3 Jul 2024 09: 47: 16 GMT
Content-Length: 0
Server: HBlock

智算服务

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

存储资源盘活系统

存储资源盘活系统

请求语法

请求参数

请求示例1

响应示例1

请求示例2

响应示例2

请求示例3

响应示例3

活动

智算服务

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

存储资源盘活系统

存储资源盘活系统

请求语法

请求参数

请求示例1

响应示例1

请求示例2

响应示例2

请求示例3

响应示例3