集群版部署指導
集群版部署指導
本小節描述如何手動部署包括3個ConfigNode和3個DataNode的實例，即通常所說的3C3D集群。
1. 注意事項
安裝前請確認系統已參照系統配置準備完成。
部署時推薦優先使用
hostname進行IP配置，可避免后期修改主機ip導致數據庫無法啟動的問題。設置hostname需要在目標服務器上配置/etc/hosts，如本機ip是192.168.1.3，hostname是iotdb-1，則可以使用以下命令設置服務器的 hostname，并使用hostname配置IoTDB的cn_internal_address、dn_internal_address。dn_internal_address。echo "192.168.1.3 iotdb-1" >> /etc/hosts有些參數首次啟動后不能修改，請參考下方的"參數配置"章節來進行設置。
無論是在linux還是windows中，請確保IoTDB的安裝路徑中不含空格和中文，避免軟件運行異常。
請注意，安裝部署（包括激活和使用軟件）IoTDB時需要保持使用同一個用戶進行操作，您可以：
- 使用 root 用戶（推薦）：使用 root 用戶可以避免權限等問題。
- 使用固定的非 root 用戶：
- 使用同一用戶操作：確保在啟動、激活、停止等操作均保持使用同一用戶，不要切換用戶。
- 避免使用 sudo：盡量避免使用 sudo 命令，因為它會以 root 用戶權限執行命令，可能會引起權限混淆或安全問題。
推薦部署監控面板，可以對重要運行指標進行監控，隨時掌握數據庫運行狀態，監控面板可以聯系商務獲取，部署監控面板步驟可以參考：監控面板部署
在安裝部署數據庫前，可以使用健康檢查工具檢測 IoTDB 節點運行環境，并獲取詳細的檢查結果。 IoTDB 健康檢查工具使用方法可以參考：健康檢查工具。
2. 準備步驟
2.1 前置檢查
為確保您獲取的IoTDB企業版安裝包完整且正確，在執行安裝部署前建議您進行SHA512校驗。
準備工作：
- 獲取官方發布的 SHA512 校驗碼：發布歷史文檔中各版本對應的"SHA512校驗碼"
校驗步驟（以 linux 為例）：
- 打開終端，進入安裝包所在目錄（如
/data/iotdb）：cd /data/iotdb - 執行以下命令計算哈希值：
sha512sum timechodb-{version}-bin.zip - 終端輸出結果（左側為SHA512 校驗碼，右側為文件名）：
- 對比輸出結果與官方 SHA512 校驗碼，確認一致后，即可按照下方流程執行IoTDB企業版的安裝部署操作。
注意事項：
- 若校驗結果不一致，請聯系天謀工作人員重新獲取安裝包
- 校驗過程中若出現"文件不存在"提示，需檢查文件路徑是否正確或安裝包是否完整下載
3. 安裝步驟
假設現在有3臺linux服務器，IP地址和服務角色分配如下：
| 節點ip | 主機名 | 服務 |
|---|---|---|
| 192.168.1.3 | iotdb-1 | ConfigNode、DataNode |
| 192.168.1.4 | iotdb-2 | ConfigNode、DataNode |
| 192.168.1.5 | iotdb-3 | ConfigNode、DataNode |
3.1 設置主機名
在3臺機器上分別配置主機名，設置主機名需要在目標服務器上配置/etc/hosts，使用如下命令：
echo "192.168.1.3 iotdb-1" >> /etc/hosts
echo "192.168.1.4 iotdb-2" >> /etc/hosts
echo "192.168.1.5 iotdb-3" >> /etc/hosts3.2 參數配置
解壓安裝包并進入安裝目錄
unzip iotdb-enterprise-{version}-bin.zip
cd iotdb-enterprise-{version}-bin環境腳本配置
./conf/confignode-env.sh配置配置項 說明 默認值 推薦值 備注 MEMORY_SIZE IoTDB ConfigNode節點可以使用的內存總量 空 可按需填寫，填寫后系統會根據填寫的數值來分配內存 修改后保存即可，無需執行；重啟服務后生效 ./conf/datanode-env.sh配置配置項 說明 默認值 推薦值 備注 MEMORY_SIZE IoTDB DataNode節點可以使用的內存總量 空 可按需填寫，填寫后系統會根據填寫的數值來分配內存 修改后保存即可，無需執行；重啟服務后生效
通用配置
打開通用配置文件./conf/iotdb-system.properties，可根據部署方式設置以下參數：
| 配置項 | 說明 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 |
|---|---|---|---|---|
| cluster_name | 集群名稱 | defaultCluster | defaultCluster | defaultCluster |
| schema_replication_factor | 元數據副本數，DataNode數量不應少于此數目 | 3 | 3 | 3 |
| data_replication_factor | 數據副本數，DataNode數量不應少于此數目 | 2 | 2 | 2 |
ConfigNode 配置
打開ConfigNode配置文件./conf/iotdb-system.properties，設置以下參數
| 配置項 | 說明 | 默認 | 推薦值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 備注 |
|---|---|---|---|---|---|---|---|
| cn_internal_address | ConfigNode在集群內部通訊使用的地址 | 127.0.0.1 | 所在服務器的IPV4地址或hostname，推薦使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次啟動后不能修改 |
| cn_internal_port | ConfigNode在集群內部通訊使用的端口 | 10710 | 10710 | 10710 | 10710 | 10710 | 首次啟動后不能修改 |
| cn_consensus_port | ConfigNode副本組共識協議通信使用的端口 | 10720 | 10720 | 10720 | 10720 | 10720 | 首次啟動后不能修改 |
| cn_seed_config_node | 節點注冊加入集群時連接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一個CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次啟動后不能修改 |
DataNode 配置
打開DataNode配置文件 ./conf/iotdb-system.properties，設置以下參數：
| 配置項 | 說明 | 默認 | 推薦值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 備注 |
|---|---|---|---|---|---|---|---|
| dn_rpc_address | 客戶端 RPC 服務的地址 | 127.0.0.1 | 默認本機可直接訪問。非本機訪問，請修改此配置項為所在服務器的IPV4地址或hostname，推薦使用所在服務器的IPV4地址。 | iotdb-1 | iotdb-2 | iotdb-3 | 重啟服務生效 |
| dn_rpc_port | 客戶端 RPC 服務的端口 | 6667 | 6667 | 6667 | 6667 | 6667 | 重啟服務生效 |
| dn_internal_address | DataNode在集群內部通訊使用的地址 | 127.0.0.1 | 所在服務器的IPV4地址或hostname，推薦使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次啟動后不能修改 |
| dn_internal_port | DataNode在集群內部通信使用的端口 | 10730 | 10730 | 10730 | 10730 | 10730 | 首次啟動后不能修改 |
| dn_mpp_data_exchange_port | DataNode用于接收數據流使用的端口 | 10740 | 10740 | 10740 | 10740 | 10740 | 首次啟動后不能修改 |
| dn_data_region_consensus_port | DataNode用于數據副本共識協議通信使用的端口 | 10750 | 10750 | 10750 | 10750 | 10750 | 首次啟動后不能修改 |
| dn_schema_region_consensus_port | DataNode用于元數據副本共識協議通信使用的端口 | 10760 | 10760 | 10760 | 10760 | 10760 | 首次啟動后不能修改 |
| dn_seed_config_node | 節點注冊加入集群時連接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一個CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次啟動后不能修改 |
??注意：VSCode Remote等編輯器無自動保存配置功能，請確保修改的文件被持久化保存，否則配置項無法生效
3.3 啟動ConfigNode節點
先啟動第一個iotdb-1的confignode, 保證種子confignode節點先啟動，然后依次啟動第2和第3個confignode節點
cd sbin
./start-confignode.sh -d #“-d”參數將在后臺進行啟動如果啟動失敗，請參考下常見問題
3.4 啟動DataNode 節點
分別進入iotdb的sbin目錄下，依次啟動3個datanode節點：
cd sbin
./start-datanode.sh -d #-d參數將在后臺進行啟動3.5 激活數據庫
方式一：通過 CLI 激活
- 進入集群任一節點 CLI，執行獲取機器碼的語句
# Linux 系統與 MacOS 系統啟動命令如下：
# V2.0.6.x 版本之前
Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root
# V2.0.6.x 版本及之后
Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021
# Windows 系統啟動命令如下：
# V2.0.4.x 版本之前
Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root
# V2.0.4.x 版本及之后, V2.0.6.x 版本之前
Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root
# V2.0.6.x 版本及之后
Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021執行以下內容獲取激活所需機器碼：
show system info系統將自動返回集群所有節點的機器碼
```Bash +--------------------------------------------------------------+ | SystemInfo| +--------------------------------------------------------------+ |01-TE5NLES4-UDDWCMYE,01-GG5NLES4-XXDWCMYE,01-FF5NLES4-WWWWCMYE| +--------------------------------------------------------------+ Total line number = 1 It costs 0.030s ```將獲取的機器碼復制給天謀工作人員
工作人員會返回激活碼，正常是與提供的機器碼的順序對應的，請將整串激活碼粘貼到CLI中進行激活，此激活操作只需在集群中的任意一臺機器上執行一次即可。
- 注：激活碼前后需要用
'符號進行標注，如下所示
IoTDB> activate '01-D4EYQGPZ-EAUJJODW-NUKRDR6F-TUQS3B75-EDZFLK3A-6BOKJFFZ-ALDHOMN7-NB2E4BHI-7ZKGFVK6-GCIFXA4T-UG3XJTTD-SHJV6F2P-Q27B4OMJ-R47ZDIM3-UUASUXG2-OQXGVZCO-MMYKICZU-TWFQYYAO-ZOAGOKJA-NYHQTA5U-EWAR4EP5-MRC6R2CI-PKUTKRCT-7UDGRH3F-7BYV4P5D-6KKIA===,01-D4EYQGPZ-EAUJJODW-NUKRDR6F-TUQS3B75-EDZFLK3A-6BOKJFFZ-ALDHOMN7-NB2E4BHI-7ZKGFVK6-GCIFXA4T-UG3XJTTD-SHJV6F2P-Q27B4OMJ-R47ZDIM3-UUASUXG2-OQXGVZCO-MMYKICZU-TWFQYYAO-ZOAGOKJA-NYHQTA5U-EWAR4EP5-MRC6R2CI-PKUTKRCT-7UDGRH3F-7BYV4P5D-6KKIA===,01-D4EYQGPZ-EAUJJODW-NUKRDR6F-TUQS3B75-EDZFLK3A-6BOKJFFZ-ALDHOMN7-NB2E4BHI-7ZKGFVK6-GCIFXA4T-UG3XJTTD-SHJV6F2P-Q27B4OMJ-R47ZDIM3-UUASUXG2-OQXGVZCO-MMYKICZU-TWFQYYAO-ZOAGOKJA-NYHQTA5U-EWAR4EP5-MRC6R2CI-PKUTKRCT-7UDGRH3F-7BYV4P5D-6KKIA==='- 注：激活碼前后需要用
方式二：激活文件拷貝激活
- 依次啟動3個Confignode、Datanode節點后，每臺機器各自的activation文件夾, 分別拷貝每臺機器的system_info文件給天謀工作人員;
- 工作人員將返回每個ConfigNode、Datanode節點的license文件，這里會返回3個license文件；
- 將3個license文件分別放入對應的ConfigNode節點的activation文件夾下；
3.6 驗證激活
可在 CLI 中通過執行 show activation 命令查看激活狀態，示例如下，狀態顯示為 ACTIVATED 表示激活成功
IoTDB> show activation
+---------------+---------+-----------------------------+
| LicenseInfo| Usage| Limit|
+---------------+---------+-----------------------------+
| Status|ACTIVATED| -|
| ExpiredTime| -|2026-04-30T00:00:00.000+08:00|
| DataNodeLimit| 1| Unlimited|
| CpuLimit| 16| Unlimited|
| DeviceLimit| 30| Unlimited|
|TimeSeriesLimit| 72| 1,000,000,000|
+---------------+---------+-----------------------------+3.7 一鍵啟停集群
3.7.1 概述
在 IoTDB 的根目錄中，sbin 子目錄包含的 start-all.sh 和 stop-all.sh 腳本，與 conf 子目錄中的 iotdb-cluster.properties 配置文件協同工作，可通過單一節點實現一鍵啟動或停止集群所有節點的功能。通過這種方式，可以高效地管理 IoTDB 集群的生命周期，簡化了部署和運維流程。
下文將介紹iotdb-cluster.properties 文件中的具體配置項。
3.7.2 配置項
注意：
- 當集群變更時，需要手動更新此配置文件。
- 如果在未配置
iotdb-cluster.properties配置文件的情況下執行start-all.sh或者stop-all.sh腳本，則默認會啟停當前腳本所在 IOTDB_HOME 目錄下的 ConfigNode 與 DataNode 節點。- 推薦配置 ssh 免密登錄：如果未配置，啟動腳本后會提示輸入服務器密碼以便于后續啟動/停止/銷毀操作。如果已配置，則無需在執行腳本過程中輸入服務器密碼。
- confignode_address_list
| 名字 | confignode_address_list |
|---|---|
| 描述 | 待啟動/停止的 ConfigNode 節點所在主機的 IP 列表，如果有多個需要用“,”分隔。 |
| 類型 | String |
| 默認值 | 無 |
| 改后生效方式 | 重啟服務生效 |
- datanode_address_list
| 名字 | datanode_address_list |
|---|---|
| 描述 | 待啟動/停止的 DataNode 節點所在主機的 IP 列表，如果有多個需要用“,”分隔。 |
| 類型 | String |
| 默認值 | 無 |
| 改后生效方式 | 重啟服務生效 |
- ssh_account
| 名字 | ssh_account |
|---|---|
| 描述 | 通過 SSH 登陸目標主機的用戶名，需要所有的主機的用戶名都相同 |
| 類型 | String |
| 默認值 | root |
| 改后生效方式 | 重啟服務生效 |
- ssh_port
| 名字 | ssh_port |
|---|---|
| 描述 | 目標主機對外暴露的 SSH 端口，需要所有的主機的端口都相同 |
| 類型 | int |
| 默認值 | 22 |
| 改后生效方式 | 重啟服務生效 |
- confignode_deploy_path
| 名字 | confignode_deploy_path |
|---|---|
| 描述 | 待啟動/停止的所有 ConfigNode 所在目標主機的路徑，需要所有待啟動/停止的 ConfigNode 節點在目標主機的相同目錄下。 |
| 類型 | String |
| 默認值 | 無 |
| 改后生效方式 | 重啟服務生效 |
- datanode_deploy_path
| 名字 | datanode_deploy_path |
|---|---|
| 描述 | 待啟動/停止的所有 DataNode 所在目標主機的路徑，需要所有待啟動/停止的 DataNode 節點在目標主機的相同目錄下。 |
| 類型 | String |
| 默認值 | 無 |
| 改后生效方式 | 重啟服務生效 |
4. 節點維護步驟
4.1 ConfigNode節點維護
ConfigNode節點維護分為ConfigNode添加和移除兩種操作，有兩個常見使用場景：
- 集群擴展：如集群中只有1個ConfigNode時，希望增加ConfigNode以提升ConfigNode節點高可用性，則可以添加2個ConfigNode，使得集群中有3個ConfigNode。
- 集群故障恢復：1個ConfigNode所在機器發生故障，使得該ConfigNode無法正常運行，此時可以移除該ConfigNode，然后添加一個新的ConfigNode進入集群。
??注意，在完成ConfigNode節點維護后，需要保證集群中有1或者3個正常運行的ConfigNode。2個ConfigNode不具備高可用性，超過3個ConfigNode會導致性能損失。
添加ConfigNode節點
腳本命令：
# Linux / MacOS
# 首先切換到IoTDB根目錄
sbin/start-confignode.sh
# Windows
# 首先切換到IoTDB根目錄
# V2.0.4.x 版本之前
sbin\start-confignode.bat
# V2.0.4.x 版本及之后
sbin\windows\start-confignode.bat參數介紹：
| 參數 | 描述 | 是否為必填項 |
|---|---|---|
| -v | 顯示版本信息 | 否 |
| -f | 在前臺運行腳本，不將其放到后臺 | 否 |
| -d | 以守護進程模式啟動，即在后臺運行 | 否 |
| -p | 指定一個文件來存放進程ID，用于進程管理 | 否 |
| -c | 指定配置文件夾的路徑，腳本會從這里加載配置文件 | 否 |
| -g | 打印垃圾回收（GC）的詳細信息 | 否 |
| -H | 指定Java堆轉儲文件的路徑，當JVM內存溢出時使用 | 否 |
| -E | 指定JVM錯誤日志文件的路徑 | 否 |
| -D | 定義系統屬性，格式為 key=value | 否 |
| -X | 直接傳遞 -XX 參數給 JVM | 否 |
| -h | 幫助指令 | 否 |
移除ConfigNode節點
首先通過CLI連接集群，通過show confignodes確認想要移除ConfigNode的NodeID：
IoTDB> show confignodes
+------+-------+---------------+------------+--------+
|NodeID| Status|InternalAddress|InternalPort| Role|
+------+-------+---------------+------------+--------+
| 0|Running| 127.0.0.1| 10710| Leader|
| 1|Running| 127.0.0.1| 10711|Follower|
| 2|Running| 127.0.0.1| 10712|Follower|
+------+-------+---------------+------------+--------+
Total line number = 3
It costs 0.030s然后使用SQL將ConfigNode移除，SQL命令：
remove confignode [confignode_id]4.2 DataNode節點維護
DataNode節點維護有兩個常見場景：
- 集群擴容：出于集群能力擴容等目的，添加新的DataNode進入集群
- 集群故障恢復：一個DataNode所在機器出現故障，使得該DataNode無法正常運行，此時可以移除該DataNode，并添加新的DataNode進入集群
??注意，為了使集群能正常工作，在DataNode節點維護過程中以及維護完成后，正常運行的DataNode總數不得少于數據副本數（通常為2），也不得少于元數據副本數（通常為3）。
添加DataNode節點
腳本命令：
# Linux / MacOS
# 首先切換到IoTDB根目錄
sbin/start-datanode.sh
# Windows
# 首先切換到IoTDB根目錄
# V2.0.4.x 版本之前
sbin\start-datanode.bat
# V2.0.4.x 版本及之后
tools\windows\start-datanode.bat參數介紹：
| 縮寫 | 描述 | 是否為必填項 |
|---|---|---|
| -v | 顯示版本信息 | 否 |
| -f | 在前臺運行腳本，不將其放到后臺 | 否 |
| -d | 以守護進程模式啟動，即在后臺運行 | 否 |
| -p | 指定一個文件來存放進程ID，用于進程管理 | 否 |
| -c | 指定配置文件夾的路徑，腳本會從這里加載配置文件 | 否 |
| -g | 打印垃圾回收（GC）的詳細信息 | 否 |
| -H | 指定Java堆轉儲文件的路徑，當JVM內存溢出時使用 | 否 |
| -E | 指定JVM錯誤日志文件的路徑 | 否 |
| -D | 定義系統屬性，格式為 key=value | 否 |
| -X | 直接傳遞 -XX 參數給 JVM | 否 |
| -h | 幫助指令 | 否 |
說明：在添加DataNode后，隨著新的寫入到來（以及舊數據過期，如果設置了TTL），集群負載會逐漸向新的DataNode均衡，最終在所有節點上達到存算資源的均衡。
移除DataNode節點
首先通過CLI連接集群，通過show datanodes確認想要移除的DataNode的NodeID：
IoTDB> show datanodes
+------+-------+----------+-------+-------------+---------------+
|NodeID| Status|RpcAddress|RpcPort|DataRegionNum|SchemaRegionNum|
+------+-------+----------+-------+-------------+---------------+
| 1|Running| 0.0.0.0| 6667| 0| 0|
| 2|Running| 0.0.0.0| 6668| 1| 1|
| 3|Running| 0.0.0.0| 6669| 1| 0|
+------+-------+----------+-------+-------------+---------------+
Total line number = 3
It costs 0.110s然后使用SQL將DataNode移除，SQL命令：
remove datanode [datanode_id]4.3 集群維護
更多關于集群維護的介紹可參考：集群維護
5. 常見問題
部署過程中多次提示激活失敗
- 使用
ls -al命令：使用ls -al命令檢查安裝包根目錄的所有者信息是否為當前用戶。 - 檢查激活目錄：檢查
./activation目錄下的所有文件，所有者信息是否為當前用戶。
- 使用
Confignode節點啟動失敗
步驟 1: 請查看啟動日志，檢查是否修改了某些首次啟動后不可改的參數。
步驟 2: 請查看啟動日志，檢查是否出現其他異常。日志中若存在異常現象，請聯系天謀技術支持人員咨詢解決方案。
步驟 3: 如果是首次部署或者數據可刪除，也可按下述步驟清理環境，重新部署后，再次啟動。
步驟 4: 清理環境：
a. 結束所有 ConfigNode 和 DataNode 進程。
# 1. 停止 ConfigNode 和 DataNode 服務 sbin/stop-standalone.sh # 2. 檢查是否還有進程殘留 jps # 或者 ps -ef|grep iotdb # 3. 如果有進程殘留，則手動kill kill -9 <pid> # 如果確定機器上僅有1個iotdb，可以使用下面命令清理殘留進程 ps -ef|grep iotdb|grep -v grep|tr -s ' ' ' ' |cut -d ' ' -f2|xargs kill -9b. 刪除 data 和 logs 目錄。
說明：刪除 data 目錄是必要的，刪除 logs 目錄是為了純凈日志，非必需。
cd /data/iotdb rm -rf data logs