此操作用來初始化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 | 設置基礎存儲池的故障域級別（僅集群版支持）。初始化時設置的集群拓撲中，包含的數據目錄節點都加入到基礎存儲池中。 取值：
默認值為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 | 集群網絡（僅集群版支持），用于集群間的數據通信。
取值：如果指定地址范圍，IP地址后加掩碼表示，如192.163.1.5/24。 | 否 |
| publicNetwork | String | 業務網絡，用于客戶端和HBlock之間的數據傳輸式。
取值：如果指定地址范圍，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表示禁止寫入。默認不限制寫入。 注意 如果相同的數據目錄出現多次，以第一次出現的數據目錄的容量配額為準。 | 否 |
表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 | 元數據服務的數據目錄（僅集群版支持），用于存儲元數據服務的相關數據信息。 說明 為了提升讀寫性能，建議元數據服務的數據目錄與安裝目錄、存儲數據的數據目錄分開。 取值：只能包含字母、數字、漢字和特殊字符(~ ! @ $ ( ) _ + - ; . :)。默認目錄為安裝目錄。 | 否 |
表5 請求參數ls說明（僅集群版支持）
| 參數 | 類型 | 描述 | 是否必須 |
|---|---|---|---|
| ip | String | 日志服務的地址（僅集群版支持）。 如果指定日志服務的地址，必須同時指定集群中的3個IP地址。 取值：IPv4或[IPv6]地址。 | 否 |
| metaDir | String | 日志服務的數據目錄（僅集群版支持），用于存儲日志服務的相關數據信息。 說明 為了提升讀寫性能，建議日志服務的數據目錄與安裝目錄、存儲數據的數據目錄分開。 取值：只能包含字母、數字、漢字和特殊字符(~ ! @ $ ( ) _ + - ; . :)。默認目錄為安裝目錄。 | 否 |
表6 請求參數cs說明（僅集群版支持）
| 參數 | 類型 | 描述 | 是否必須 |
|---|---|---|---|
| ip | 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
