此操作用来初始化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,
    "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],
        "ls": [ip,ip,ip],
        "cs": [ip,ip,ip]
    },
    "clusterNetwork": clusterNetwork,
    "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],
        "ls": [ip,ip,ip],
        "cs": [ip,ip,ip]
    },
    "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",
    "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,
                    " path ": capacityvalue
                },
                {
                    "path": path,
                    "capacityQuota": capacityvalue
                },
……
            ]
        }
    ],
    "services": {
        "mdm": [ip,ip],
        "ls": [ip,ip,ip],
        "cs": [ip,ip,ip]
    },
    "clusterNetwork": clusterNetwork,
    "publicNetwork": publicNetwork
}

请求参数

参数
描述
是否必须
storName
HBlock名称。
类型：字符串
取值：长度范围是1~64，可以包含字母、数字、下划线（_）和短横线（-），字母区分大小写，且仅支持以字母或数字开头。
是
userName
HBlock的管理员用户名。
类型：字符串
取值：长度范围是5~16，只能由数字和字母组成，字母区分大小。默认值为storuser。
否
newPassword
设置的新密码。初始化时必须修改密码。
类型：字符串
取值：长度范围8~16，至少包含以下字符中的3种：大写字母、小写字母、数字、特殊字符 (~ ! @ # $ % ^ & * ( ) _ + [ ] { } | ; : , . / < > ?)，区分大小写。不能包含：3个连续重复的字符，3个连续或反序的数字、或字母（不区分大小写），3个连续或反序的键盘序列（不区分大小写）。
是
iSCSIPort
iSCSI端口。
类型：整型
取值：[1, 65535]，默认值为3260。
否
portRange
指定端口范围。存储服务以及未指定端口的服务将从此范围中自动取值。
类型：整型
取值：[1, 65535]，port1为端口范围最小值，port2为端口范围最大值，且port1 < port2。port1默认取值为20000，port2默认取值为20500。
说明
建议指定的端口范围至少包含500个端口。
否
faultDomain	
设置基础存储池的故障域级别（仅集群版支持）。初始化时设置的集群拓扑中，包含的数据目录节点都加入到基础存储池中。
类型：枚举
取值：
room：机房级别。
rack:机架级别。
path：数据目录级别。
server：服务器级别。
默认值为server。
注意
如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。
否
ports.dataPort1
数据端口1（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.managementPort1
管理服务端口1。
类型：整型
取值：[1, 65535]。
否
ports.managementPort2
管理服务端口2。
类型：整型
取值：[1, 65535]。
否
ports.managementPort3
管理服务端口3。
类型：整型
取值：[1, 65535]。
否
ports.managementPort4
管理服务端口4。
类型：整型
取值：[1, 65535]。
否
ports.managementPort5
管理服务端口5（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.managementPort6
管理服务端口6。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort1
元数据端口1（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort2
元数据端口2（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort3
元数据端口3（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort4
元数据端口4（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort5
元数据端口5（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort6
元数据端口6（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort7
元数据端口7（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
ports.metadataPort8
元数据端口8（仅集群版支持）。
类型：整型
取值：[1, 65535]。
否
topology
导入集群拓扑文件内容（仅集群版支持）。
类型：字符串
取值：拓扑文件需要采用UTF-8编码，且为JSON文件格式，然后转换成字符串格式复制给该参数。拓扑文件的构成详见集群拓扑文件。
注意
“topology”与“servers”必须选一种，且只能选一种。如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。
否
servers
HBlock服务器的属性集合，包含：nodeName（仅集群版支持）、ip、apiPort、diskPaths。
注意
“topology”与“servers”必须选一种，且只能选一种。如果故障域级别为room或者rack，则必须使用拓扑文件导入方式进行初始化。
类型：数组
否
nodeName
拓扑节点名称。
类型：字符串
取值：字符串形式，长度范围1~63，只能由字母、数字、句点(.)、下划线（_）和短横线(-)组成，字母区分大小写，且仅支持以字母或数字开头。
否
ip
HBlock的服务器IP。
取值：IPv4或[IPv6]地址。
是
apiPort
管理API端口。
类型：整型
取值：[1, 65535]，默认值为1443。需要和该服务器安装HBlock时设置的API端口号保持一致。
否
diskPaths
数据目录属性集合。包括path、capacityQuota。
类型：数组
否
path	
指定数据目录。数据目录用于存储数据，建议不要与操作系统共用磁盘或文件系统。数据目录中不能有逗号（,）。
说明
对于单机版，第一个数据目录为默认数据目录。对于集群版，需要至少有一个数据目录。
注意
如果故障域是server和path级别，此项必填。
类型：字符串列表
否
capacityQuota
指定数据目录的容量配额，即针对加入到服务器中的每个数据目录，HBlock可写入的数据总量。当HBlock的使用空间一旦达到配额，就立刻阻止数据写入，不允许再使用超出配额的空间。
类型：长整型
取值：小于数据目录所在磁盘的总容量，单位是字节。负整数表示无限制写入，0表示禁止写入。默认不限制写入。
注意
如果相同的数据目录出现多次，以第一次出现的数据目录的容量配额为准。
否
services
服务地址的集合（仅集群版支持）。包括mdm、ls、cs。
类型：数组
否
mdm
元数据管理服务的地址（仅集群版支持）。如果填写，必须填写集群中的2个IP地址。如果不填写，元数据管理服务的地址默认为集群中的前2个IP地址。
取值：IPv4或[IPv6]地址。
否
ls
日志服务的地址（仅集群版支持）。如果填写，必须填写集群中的3个IP地址。日志服务的地址默认为集群中的前3个IP地址。
取值：IPv4或[IPv6]地址。
否
cs
协调服务的地址（仅集群版支持）。如果填写，必须填写集群中的3个IP地址。协调服务的地址默认为集群中的前3个IP地址。
取值：IPv4或[IPv6]地址。
否
clusterNetwork
集群网络（仅集群版支持），用于集群间的数据通信。
如果指定集群网络，为了保证HBlock的各个服务器之间能够正常通信，请确保每个服务器上都有与指定网段相符的IP，系统会自动选取该IP进行通信。
如果未指定集群网络，默认使用服务器列表中HBlock服务器IP，此时HBlock的服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。
类型：CIDR格式
取值：如果指定地址范围，IP地址后加掩码表示，如192.163.1.5/24。
否
publicNetwork
业务网络，用于客户端和HBlock之间的数据传输式。
如果指定业务网络，请确保每个服务器上都有与指定网段相符的IP，系统会自动选取该IP和客户端进行通信。
如果未指定业务网络，或指定了业务网络，但指定的网段与服务器所有IP均不相符，默认使用服务器列表中HBlock服务器IP，此时HBlock服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。
类型：CIDR格式
取值：如果指定地址范围，IP地址后加掩码表示，如192.163.1.5/24列表。
否

请求示例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