集群管理工具

1. 集群管理工具

IoTDB 集群管理工具是一款易用的運維工具（企業版工具）。旨在解決 IoTDB 分布式系統多節點的運維難題，主要包括集群部署、集群啟停、彈性擴容、配置更新、數據導出等功能，從而實現對復雜數據庫集群的一鍵式指令下發，極大降低管理難度。本文檔將說明如何用集群管理工具遠程部署、配置、啟動和停止 IoTDB 集群實例。

1.1 環境準備

本工具為 TimechoDB（基于IoTDB的企業版數據庫）配套工具，您可以聯系您的銷售獲取工具下載方式。

IoTDB 要部署的機器需要依賴jdk 8及以上版本、lsof、netstat、unzip功能如果沒有請自行安裝，可以參考文檔最后的一節環境所需安裝命令。

提示:IoTDB集群管理工具需要使用有root權限的賬號

1.2 部署方法

下載安裝

本工具為TimechoDB（基于IoTDB的企業版數據庫）配套工具，您可以聯系您的銷售獲取工具下載方式。

注意：由于二進制包僅支持GLIBC2.17 及以上版本，因此最低適配Centos7版本

• 在iotd目錄內輸入以下指令后：

bash install-iotdbctl.sh

即可在之后的 shell 內激活 iotdbctl 關鍵詞，如檢查部署前所需的環境指令如下所示：

iotdbctl cluster check example

• 也可以不激活iotd直接使用 <iotdbctl absolute path>/sbin/iotdbctl 來執行命令，如檢查部署前所需的環境：

<iotdbctl absolute path>/sbin/iotdbctl cluster check example

1.3 系統結構

IoTDB集群管理工具主要由config、logs、doc、sbin目錄組成。

• config存放要部署的集群配置文件如果要使用集群部署工具需要修改里面的yaml文件。
• logs 存放部署工具日志，如果想要查看部署工具執行日志請查看logs/iotd_yyyy_mm_dd.log。
• sbin 存放集群部署工具所需的二進制包。
• doc 存放用戶手冊、開發手冊和推薦部署手冊。

1.4 集群配置文件介紹

• 在iotdbctl/config 目錄下有集群配置的yaml文件，yaml文件名字就是集群名字yaml 文件可以有多個，為了方便用戶配置yaml文件在iotd/config目錄下面提供了default_cluster.yaml示例。
• yaml 文件配置由global、confignode_servers、datanode_servers、grafana_server、prometheus_server四大部分組成
• global 是通用配置主要配置機器用戶名密碼、IoTDB本地安裝文件、Jdk配置等。在iotdbctl/config目錄中提供了一個default_cluster.yaml樣例數據，
  用戶可以復制修改成自己集群名字并參考里面的說明進行配置IoTDB集群，在default_cluster.yaml樣例中沒有注釋的均為必填項，已經注釋的為非必填項。

例如要執行default_cluster.yaml檢查命令則需要執行命令iotdbctl cluster check default_cluster即可，
更多詳細命令請參考下面命令列表。

參數	說明	是否必填
iotdb_zip_dir	IoTDB 部署分發目錄，如果值為空則從iotdb_download_url指定地址下載	非必填
iotdb_download_url	IoTDB 下載地址，如果iotdb_zip_dir 沒有值則從指定地址下載	非必填
jdk_tar_dir	jdk 本地目錄，可使用該 jdk 路徑進行上傳部署至目標節點。	非必填
jdk_deploy_dir	jdk 遠程機器部署目錄，會將 jdk 部署到該目錄下面，與下面的jdk_dir_name參數構成完整的jdk部署目錄即 <jdk_deploy_dir>/<jdk_dir_name>	非必填
jdk_dir_name	jdk 解壓后的目錄名稱默認是jdk_iotdb	非必填
iotdb_lib_dir	IoTDB lib 目錄或者IoTDB 的lib 壓縮包僅支持.zip格式 ，僅用于IoTDB升級，默認處于注釋狀態，如需升級請打開注釋修改路徑即可。如果使用zip文件請使用zip 命令壓縮iotdb/lib目錄例如 zip -r lib.zip apache-iotdb-1.2.0/lib/*	非必填
user	ssh登陸部署機器的用戶名	必填
password	ssh登錄的密碼, 如果password未指定使用pkey登陸, 請確保已配置節點之間ssh登錄免密鑰	非必填
pkey	密鑰登陸如果password有值優先使用password否則使用pkey登陸	非必填
ssh_port	ssh登錄端口	必填
iotdb_admin_user	iotdb服務用戶名默認root	非必填
iotdb_admin_password	iotdb服務密碼默認root	非必填
deploy_dir	IoTDB 部署目錄，會把 IoTDB 部署到該目錄下面與下面的iotdb_dir_name參數構成完整的IoTDB 部署目錄即 <deploy_dir>/<iotdb_dir_name>	必填
iotdb_dir_name	IoTDB 解壓后的目錄名稱默認是iotdb	非必填
datanode-env.sh	對應iotdb/config/datanode-env.sh ,在global與confignode_servers同時配置值時優先使用confignode_servers中的值	非必填
confignode-env.sh	對應iotdb/config/confignode-env.sh,在global與datanode_servers同時配置值時優先使用datanode_servers中的值	非必填
iotdb-common.properties	對應iotdb/config/iotdb-common.properties	非必填
cn_seed_config_node	集群配置地址指向存活的ConfigNode,默認指向confignode_x，在global與confignode_servers同時配置值時優先使用confignode_servers中的值，對應iotdb/config/iotdb-system.properties中的cn_seed_config_node	必填
dn_seed_config_node	集群配置地址指向存活的ConfigNode,默認指向confignode_x，在global與datanode_servers同時配置值時優先使用datanode_servers中的值，對應iotdb/config/iotdb-system.properties中的dn_seed_config_node	必填

其中datanode-env.sh 和confignode-env.sh 可以配置額外參數extra_opts，當該參數配置后會在datanode-env.sh 和confignode-env.sh 后面追加對應的值，可參考default_cluster.yaml，配置示例如下:
datanode-env.sh:
extra_opts: |
IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:+UseG1GC" IOTDB_JMX_OPTS="$IOTDB_JMX_OPTS -XX:MaxGCPauseMillis=200"

• confignode_servers 是部署IoTDB Confignodes配置，里面可以配置多個Confignode
  默認將第一個啟動的ConfigNode節點node1當作Seed-ConfigNode

參數	說明	是否必填
name	Confignode 名稱	必填
deploy_dir	IoTDB config node 部署目錄	必填｜
cn_internal_address	對應iotdb/內部通信地址，對應iotdb/config/iotdb-system.properties中的cn_internal_address	必填
cn_seed_config_node	集群配置地址指向存活的ConfigNode,默認指向confignode_x，在global與confignode_servers同時配置值時優先使用confignode_servers中的值，對應iotdb/config/iotdb-confignode.properties中的cn_seed_config_node	必填
cn_internal_port	內部通信端口，對應iotdb/config/iotdb-system.properties中的cn_internal_port	必填
cn_consensus_port	對應iotdb/config/iotdb-system.properties中的cn_consensus_port	非必填
cn_data_dir	對應iotdb/config/iotdb-system.properties中的cn_data_dir	必填
iotdb-system.properties	對應iotdb/config/iotdb-system.properties在global與confignode_servers同時配置值優先使用confignode_servers中的值	非必填

• datanode_servers 是部署IoTDB Datanodes配置，里面可以配置多個Datanode

參數	說明	是否必填
name	Datanode 名稱	必填
deploy_dir	IoTDB data node 部署目錄，注:該目錄不能與下面的IoTDB config node部署目錄相同	必填
dn_rpc_address	datanode rpc 地址對應iotdb/config/iotdb-system.properties中的dn_rpc_address	必填
dn_internal_address	內部通信地址，對應iotdb/config/iotdb-system.properties中的dn_internal_address	必填
dn_seed_config_node	集群配置地址指向存活的ConfigNode,默認指向confignode_x，在global與datanode_servers同時配置值時優先使用datanode_servers中的值，對應iotdb/config/iotdb-datanode.properties中的dn_seed_config_node，推薦使用 SeedConfigNode	必填
dn_rpc_port	datanode rpc端口地址，對應iotdb/config/iotdb-system.properties中的dn_rpc_port	必填
dn_internal_port	內部通信端口，對應iotdb/config/iotdb-system.properties中的dn_internal_port	必填
iotdb-system.properties	對應iotdb/config/iotdb-system.properties在global與datanode_servers同時配置值優先使用datanode_servers中的值	非必填

參數	說明	是否必填
name	Datanode 名稱	必填
deploy_dir	IoTDB data node 部署目錄	必填
dn_rpc_address	datanode rpc 地址對應iotdb/config/iotdb-system.properties中的dn_rpc_address	必填
dn_internal_address	內部通信地址，對應iotdb/config/iotdb-system.properties中的dn_internal_address	必填
dn_seed_config_node	集群配置地址指向存活的ConfigNode,默認指向confignode_x，在global與datanode_servers同時配置值時優先使用datanode_servers中的值，對應iotdb/config/iotdb-system.properties中的dn_seed_config_node	必填
dn_rpc_port	datanode rpc端口地址，對應iotdb/config/iotdb-system.properties中的dn_rpc_port	必填
dn_internal_port	內部通信端口，對應iotdb/config/iotdb-system.properties中的dn_internal_port	必填
iotdb-system.properties	對應iotdb/config/iotdb-common.properties在global與datanode_servers同時配置值優先使用datanode_servers中的值	非必填

• grafana_server 是部署Grafana 相關配置

參數	說明	是否必填
grafana_dir_name	grafana 解壓目錄名稱	非必填默認grafana_iotdb
host	grafana 部署的服務器ip	必填
grafana_port	grafana 部署機器的端口	非必填，默認3000
deploy_dir	grafana 部署服務器目錄	必填
grafana_tar_dir	grafana 壓縮包位置	必填
dashboards	dashboards 所在的位置	非必填,多個用逗號隔開

• prometheus_server 是部署Prometheus 相關配置

參數	說明	是否必填
prometheus_dir_name	prometheus 解壓目錄名稱	非必填默認prometheus_iotdb
host	prometheus 部署的服務器ip	必填
prometheus_port	prometheus 部署機器的端口	非必填，默認9090
deploy_dir	prometheus 部署服務器目錄	必填
prometheus_tar_dir	prometheus 壓縮包位置	必填
storage_tsdb_retention_time	默認保存數據天數 默認15天	非必填
storage_tsdb_retention_size	指定block可以保存的數據大小默認512M ，注意單位KB, MB, GB, TB, PB, EB	非必填

如果在config/xxx.yaml的iotdb-system.properties和iotdb-system.properties中配置了metrics,則會自動把配置放入到promethues無需手動修改

注意:如何配置yaml key對應的值包含特殊字符如:等建議整個value使用雙引號，對應的文件路徑中不要使用包含空格的路徑，防止出現識別出現異常問題。

1.5 使用場景

清理數據場景

• 清理集群數據場景會刪除IoTDB集群中的data目錄以及yaml文件中配置的cn_system_dir、cn_consensus_dir、
  dn_data_dirs、dn_consensus_dir、dn_system_dir、logs和ext目錄。
• 首先執行停止集群命令、然后在執行集群清理命令。

iotdbctl cluster stop default_cluster
iotdbctl cluster clean default_cluster

集群銷毀場景

• 集群銷毀場景會刪除IoTDB集群中的data、cn_system_dir、cn_consensus_dir、
  dn_data_dirs、dn_consensus_dir、dn_system_dir、logs、ext、IoTDB部署目錄、
  grafana部署目錄和prometheus部署目錄。
• 首先執行停止集群命令、然后在執行集群銷毀命令。

iotdbctl cluster stop default_cluster
iotdbctl cluster destroy default_cluster

集群升級場景

• 集群升級首先需要在config/xxx.yaml中配置iotdb_lib_dir為要上傳到服務器的jar所在目錄路徑（例如iotdb/lib）。
• 如果使用zip文件上傳請使用zip 命令壓縮iotdb/lib目錄例如 zip -r lib.zip apache-iotdb-1.2.0/lib/*
• 執行上傳命令、然后執行重啟IoTDB集群命令即可完成集群升級

iotdbctl cluster dist-lib default_cluster
iotdbctl cluster restart default_cluster

集群配置文件的熱部署場景

• 首先修改在config/xxx.yaml中配置。
• 執行分發命令、然后執行熱部署命令即可完成集群配置的熱部署

iotdbctl cluster dist-conf default_cluster
iotdbctl cluster reload default_cluster

集群擴容場景

• 首先修改在config/xxx.yaml中添加一個datanode 或者confignode 節點。
• 執行集群擴容命令

iotdbctl cluster scaleout default_cluster

集群縮容場景

• 首先在config/xxx.yaml中找到要縮容的節點名字或者ip+port（其中confignode port 是cn_internal_port、datanode port 是rpc_port）
• 執行集群縮容命令

iotdbctl cluster scalein default_cluster

已有IoTDB集群，使用集群部署工具場景

• 配置服務器的user、passwod或pkey、ssh_port
• 修改config/xxx.yaml中IoTDB 部署路徑，deploy_dir（IoTDB 部署目錄）、iotdb_dir_name(IoTDB解壓目錄名稱,默認是iotdb)
  例如IoTDB 部署完整路徑是/home/data/apache-iotdb-1.1.1則需要修改yaml文件deploy_dir:/home/data/、iotdb_dir_name:apache-iotdb-1.1.1
• 如果服務器不是使用的java_home則修改jdk_deploy_dir(jdk 部署目錄)、jdk_dir_name(jdk解壓后的目錄名稱,默認是jdk_iotdb)，如果使用的是java_home 則不需要修改配置
  例如jdk部署完整路徑是/home/data/jdk_1.8.2則需要修改yaml文件jdk_deploy_dir:/home/data/、jdk_dir_name:jdk_1.8.2
• 配置cn_seed_config_node、dn_seed_config_node
• 配置confignode_servers中iotdb-system.properties里面的cn_internal_address、cn_internal_port、cn_consensus_port、cn_system_dir、
  cn_consensus_dir里面的值不是IoTDB默認的則需要配置否則可不必配置
• 配置datanode_servers中iotdb-system.properties里面的dn_rpc_address、dn_internal_address、dn_data_dirs、dn_consensus_dir、dn_system_dir等
• 執行初始化命令

iotdbctl cluster init default_cluster

一鍵部署IoTDB、Grafana和Prometheus 場景

• 配置iotdb-system.properties 打開metrics接口
• 配置Grafana 配置，如果dashboards 有多個就用逗號隔開，名字不能重復否則會被覆蓋。
• 配置Prometheus配置，IoTDB 集群配置了metrics 則無需手動修改Prometheus 配置會根據哪個節點配置了metrics，自動修改Prometheus 配置。
• 啟動集群

iotdbctl cluster start default_cluster

更加詳細參數請參考上方的 集群配置文件介紹

1.6 命令格式

本工具的基本用法為：

iotdbctl cluster <key> <cluster name> [params (Optional)]

• key 表示了具體的命令。

• cluster name 表示集群名稱(即iotdbctl/config 文件中yaml文件名字)。

• params 表示了命令的所需參數(選填)。

• 例如部署default_cluster集群的命令格式為：

iotdbctl cluster deploy default_cluster

• 集群的功能及參數列表如下：

命令	功能	參數
check	檢測集群是否可以部署	集群名稱列表
clean	清理集群	集群名稱
deploy/dist-all	部署集群	集群名稱 ,-N,模塊名稱(iotdb、grafana、prometheus可選),-op force(可選)
list	打印集群及狀態列表	無
start	啟動集群	集群名稱,-N,節點名稱(nodename、grafana、prometheus可選)
stop	關閉集群	集群名稱,-N,節點名稱(nodename、grafana、prometheus可選) ,-op force(nodename、grafana、prometheus可選)
restart	重啟集群	集群名稱,-N,節點名稱(nodename、grafana、prometheus可選),-op force(強制停止)/rolling(滾動重啟)
show	查看集群信息，details字段表示展示集群信息細節	集群名稱, details(可選)
destroy	銷毀集群	集群名稱,-N,模塊名稱(iotdb、grafana、prometheus可選)
scaleout	集群擴容	集群名稱
scalein	集群縮容	集群名稱，-N，集群節點名字或集群節點ip+port
reload	集群熱加載	集群名稱
dist-conf	集群配置文件分發	集群名稱
dumplog	備份指定集群日志	集群名稱,-N,集群節點名字 -h 備份至目標機器ip -pw 備份至目標機器密碼 -p 備份至目標機器端口 -path 備份的目錄 -startdate 起始時間 -enddate 結束時間 -loglevel 日志類型 -l 傳輸速度
dumpdata	備份指定集群數據	集群名稱, -h 備份至目標機器ip -pw 備份至目標機器密碼 -p 備份至目標機器端口 -path 備份的目錄 -startdate 起始時間 -enddate 結束時間 -l 傳輸速度
dist-lib	lib 包升級	集群名字(升級完后請重啟)
init	已有集群使用集群部署工具時，初始化集群配置	集群名字，初始化集群配置
status	查看進程狀態	集群名字
acitvate	激活集群	集群名字
dist-plugin	上傳plugin(udf,trigger,pipe)到集群	集群名字,-type 類型 U(udf)/T(trigger)/P(pipe) -file /xxxx/trigger.jar,上傳完成后需手動執行創建udf、pipe、trigger命令
upgrade	滾動升級	集群名字
health_check	健康檢查	集群名字,-N,節點名稱(可選)
backup	停機備份	集群名字,-N,節點名稱(可選)
importschema	元數據導入	集群名字,-N,節點名稱(必填) -param 參數
exportschema	元數據導出	集群名字,-N,節點名稱(必填) -param 參數

1.7 細命令執行過程

下面的命令都是以default_cluster.yaml 為示例執行的，用戶可以修改成自己的集群文件來執行

檢查集群部署環境命令

iotdbctl cluster check default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 驗證目標節點是否能夠通過 SSH 登錄

• 驗證對應節點上的 JDK 版本是否滿足IoTDB jdk1.8及以上版本、服務器是否按照unzip、是否安裝lsof 或者netstat

• 如果看到下面提示Info:example check successfully! 證明服務器已經具備安裝的要求，
  如果輸出Error:example check fail! 證明有部分條件沒有滿足需求可以查看上面的輸出的Error日志(例如:Error:Server (ip:172.20.31.76) iotdb port(10713) is listening)進行修復，
  如果檢查jdk沒有滿足要求，我們可以自己在yaml 文件中配置一個jdk1.8 及以上版本的進行部署不影響后面使用，
  如果檢查lsof、netstat或者unzip 不滿足要求需要在服務器上自行安裝。

部署集群命令

iotdbctl cluster deploy default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 根據confignode_servers 和datanode_servers中的節點信息上傳IoTDB壓縮包和jdk壓縮包(如果yaml中配置jdk_tar_dir和jdk_deploy_dir值)

• 根據yaml文件節點配置信息生成并上傳iotdb-system.properties

iotdbctl cluster deploy default_cluster -op force

注意：該命令會強制執行部署，具體過程會刪除已存在的部署目錄重新部署

部署單個模塊

# 部署grafana模塊
iotdbctl cluster deploy default_cluster -N grafana
# 部署prometheus模塊
iotdbctl cluster deploy default_cluster -N prometheus
# 部署iotdb模塊
iotdbctl cluster deploy default_cluster -N iotdb

啟動集群命令

iotdbctl cluster start default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 啟動confignode，根據yaml配置文件中confignode_servers中的順序依次啟動同時根據進程id檢查confignode是否正常，第一個confignode 為seek config

• 啟動datanode，根據yaml配置文件中datanode_servers中的順序依次啟動同時根據進程id檢查datanode是否正常

• 如果根據進程id檢查進程存在后，通過cli依次檢查集群列表中每個服務是否正常，如果cli鏈接失敗則每隔10s重試一次直到成功最多重試5次

啟動單個節點命令

#按照IoTDB 節點名稱啟動
iotdbctl cluster start default_cluster -N datanode_1
#按照IoTDB 集群ip+port啟動，其中port對應confignode的cn_internal_port、datanode的rpc_port
iotdbctl cluster start default_cluster -N 192.168.1.5:6667
#啟動grafana
iotdbctl cluster start default_cluster -N grafana
#啟動prometheus
iotdbctl cluster start default_cluster -N prometheus

• 根據 cluster-name 找到默認位置的 yaml 文件

• 根據提供的節點名稱或者ip:port找到對于節點位置信息,如果啟動的節點是data_node則ip使用yaml 文件中的dn_rpc_address、port 使用的是yaml文件中datanode_servers 中的dn_rpc_port。
  如果啟動的節點是config_node則ip使用的是yaml文件中confignode_servers 中的cn_internal_address 、port 使用的是cn_internal_port

• 啟動該節點

說明：由于集群部署工具僅是調用了IoTDB集群中的start-confignode.sh和start-datanode.sh 腳本，
在實際輸出結果失敗時有可能是集群還未正常啟動，建議使用status命令進行查看當前集群狀態(iotdbctl cluster status xxx)

查看IoTDB集群狀態命令

iotdbctl cluster show default_cluster
#查看IoTDB集群詳細信息
iotdbctl cluster show default_cluster details

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 依次在datanode通過cli執行show cluster details 如果有一個節點執行成功則不會在后續節點繼續執行cli直接返回結果

停止集群命令

iotdbctl cluster stop default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 根據datanode_servers中datanode節點信息，按照配置先后順序依次停止datanode節點

• 根據confignode_servers中confignode節點信息，按照配置依次停止confignode節點

強制停止集群命令

iotdbctl cluster stop default_cluster -op force

會直接執行kill -9 pid 命令強制停止集群

停止單個節點命令

#按照IoTDB 節點名稱停止
iotdbctl cluster stop default_cluster -N datanode_1
#按照IoTDB 集群ip+port停止(ip+port是按照datanode中的ip+dn_rpc_port獲取唯一節點或confignode中的ip+cn_internal_port獲取唯一節點)
iotdbctl cluster stop default_cluster -N 192.168.1.5:6667
#停止grafana
iotdbctl cluster stop default_cluster -N grafana
#停止prometheus
iotdbctl cluster stop default_cluster -N prometheus

• 根據 cluster-name 找到默認位置的 yaml 文件

• 根據提供的節點名稱或者ip:port找到對應節點位置信息，如果停止的節點是data_node則ip使用yaml 文件中的dn_rpc_address、port 使用的是yaml文件中datanode_servers 中的dn_rpc_port。
  如果停止的節點是config_node則ip使用的是yaml文件中confignode_servers 中的cn_internal_address 、port 使用的是cn_internal_port

• 停止該節點

說明：由于集群部署工具僅是調用了IoTDB集群中的stop-confignode.sh和stop-datanode.sh 腳本，在某些情況下有可能iotdb集群并未停止。

清理集群數據命令

iotdbctl cluster clean default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers、datanode_servers配置信息

• 根據confignode_servers、datanode_servers中的信息，檢查是否還有服務正在運行，
  如果有任何一個服務正在運行則不會執行清理命令

• 刪除IoTDB集群中的data目錄以及yaml文件中配置的cn_system_dir、cn_consensus_dir、
  dn_data_dirs、dn_consensus_dir、dn_system_dir、logs和ext目錄。

重啟集群命令

iotdbctl cluster restart default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers、datanode_servers、grafana、prometheus配置信息

• 執行上述的停止集群命令(stop),然后執行啟動集群命令(start) 具體參考上面的start 和stop 命令

強制重啟集群命令

iotdbctl cluster restart default_cluster -op force

會直接執行kill -9 pid 命令強制停止集群，然后啟動集群

重啟單個節點命令

#按照IoTDB 節點名稱重啟datanode_1
iotdbctl cluster restart default_cluster -N datanode_1
#按照IoTDB 節點名稱重啟confignode_1
iotdbctl cluster restart default_cluster -N confignode_1
#重啟grafana
iotdbctl cluster restart default_cluster -N grafana
#重啟prometheus
iotdbctl cluster restart default_cluster -N prometheus

集群縮容命令

#按照節點名稱縮容
iotdbctl cluster scalein default_cluster -N nodename
#按照ip+port縮容(ip+port按照datanode中的ip+dn_rpc_port獲取唯一節點，confignode中的ip+cn_internal_port獲取唯一節點)
iotdbctl cluster scalein default_cluster -N ip:port

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 判斷要縮容的confignode節點和datanode是否只剩一個，如果只剩一個則不能執行縮容

• 然后根據ip:port或者nodename 獲取要縮容的節點信息，執行縮容命令，然后銷毀該節點目錄，如果縮容的節點是data_node則ip使用yaml 文件中的dn_rpc_address、port 使用的是yaml文件中datanode_servers 中的dn_rpc_port。
  如果縮容的節點是config_node則ip使用的是yaml文件中confignode_servers 中的cn_internal_address 、port 使用的是cn_internal_port

提示：目前一次僅支持一個節點縮容

集群擴容命令

iotdbctl cluster scaleout default_cluster

• 修改config/xxx.yaml 文件添加一個datanode 節點或者confignode節點

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 找到要擴容的節點，執行上傳IoTDB壓縮包和jdb包(如果yaml中配置jdk_tar_dir和jdk_deploy_dir值)并解壓

• 根據yaml文件節點配置信息生成并上傳iotdb-system.properties

• 執行啟動該節點命令并校驗節點是否啟動成功

提示：目前一次僅支持一個節點擴容

銷毀集群命令

iotdbctl cluster destroy default_cluster

• cluster-name 找到默認位置的 yaml 文件

• 根據confignode_servers、datanode_servers、grafana、prometheus中node節點信息，檢查是否節點還在運行，
  如果有任何一個節點正在運行則停止銷毀命令

• 刪除IoTDB集群中的data以及yaml文件配置的cn_system_dir、cn_consensus_dir、
  dn_data_dirs、dn_consensus_dir、dn_system_dir、logs、ext、IoTDB部署目錄、
  grafana部署目錄和prometheus部署目錄

銷毀單個模塊

# 銷毀grafana模塊
iotdbctl cluster destroy default_cluster -N grafana
# 銷毀prometheus模塊
iotdbctl cluster destroy default_cluster -N prometheus
# 銷毀iotdb模塊
iotdbctl cluster destroy default_cluster -N iotdb

分發集群配置命令

iotdbctl cluster dist-conf default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers、datanode_servers、grafana、prometheus配置信息

• 根據yaml文件節點配置信息生成并依次上傳iotdb-system.properties到指定節點

熱加載集群配置命令

iotdbctl cluster reload default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 根據yaml文件節點配置信息依次在cli中執行load configuration

集群節點日志備份

iotdbctl cluster dumplog default_cluster -N datanode_1,confignode_1  -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/logs' -logs '/root/data/db/iotdb/logs'

• 根據 cluster-name 找到默認位置的 yaml 文件

• 該命令會根據yaml文件校驗datanode_1,confignode_1 是否存在，然后根據配置的起止日期(startdate<=logtime<=enddate)備份指定節點datanode_1,confignode_1 的日志數據到指定服務192.168.9.48 端口36000 數據備份路徑是 /iotdb/logs ，IoTDB日志存儲路徑在/root/data/db/iotdb/logs(非必填，如果不填寫-logs xxx 默認從IoTDB安裝路徑/logs下面備份日志)

命令	功能	是否必填
-h	存放備份數據機器ip	否
-u	存放備份數據機器用戶名	否
-pw	存放備份數據機器密碼	否
-p	存放備份數據機器端口(默認22)	否
-path	存放備份數據的路徑(默認當前路徑)	否
-loglevel	日志基本有all、info、error、warn(默認是全部)	否
-l	限速(默認不限速范圍0到104857601 單位Kbit/s)	否
-N	配置文件集群名稱多個用逗號隔開	是
-startdate	起始時間(包含默認1970-01-01)	否
-enddate	截止時間(包含)	否
-logs	IoTDB 日志存放路徑，默認是（{iotdb}/logs）	否

集群節點數據備份

iotdbctl cluster dumpdata default_cluster -granularity partition  -startdate '2023-04-11' -enddate '2023-04-26' -h 192.168.9.48 -p 36000 -u root -pw root -path '/iotdb/datas'

• 該命令會根據yaml文件獲取leader 節點，然后根據起止日期(startdate<=logtime<=enddate)備份數據到192.168.9.48 服務上的/iotdb/datas 目錄下

命令	功能	是否必填
-h	存放備份數據機器ip	否
-u	存放備份數據機器用戶名	否
-pw	存放備份數據機器密碼	否
-p	存放備份數據機器端口(默認22)	否
-path	存放備份數據的路徑(默認當前路徑)	否
-granularity	類型partition	是
-l	限速(默認不限速范圍0到104857601 單位Kbit/s)	否
-startdate	起始時間(包含)	是
-enddate	截止時間(包含)	是

集群lib包上傳(升級)

iotdbctl cluster dist-lib default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 上傳lib包

注意執行完升級后請重啟IoTDB 才能生效

集群初始化

iotdbctl cluster init default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers、datanode_servers、grafana、prometheus配置信息
• 初始化集群配置

查看集群進程狀態

iotdbctl cluster status default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers、datanode_servers、grafana、prometheus配置信息
• 展示集群的存活狀態

集群授權激活

集群激活默認是通過輸入激活碼激活，也可以通過-op license_path 通過license路徑激活

• 默認激活方式

iotdbctl cluster activate default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers配置信息
• 讀取里面的機器碼
• 等待輸入激活碼

Machine code:
Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ==
JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u==
Please enter the activation code: 
JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws=
Activation successful

• 激活單個節點

iotdbctl cluster activate default_cluster -N confignode1

• 通過license路徑方式激活

iotdbctl cluster activate default_cluster -op license_path

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers配置信息
• 讀取里面的機器碼
• 等待輸入激活碼

Machine code:
Kt8NfGP73FbM8g4Vty+V9qU5lgLvwqHEF3KbLN/SGWYCJ61eFRKtqy7RS/jw03lHXt4MwdidrZJ==
JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKgGXEGzMms25+u==
Please enter the activation code: 
JHQpXu97IKwv3rzbaDwoPLUuzNCm5aEeC9ZEBW8ndKg=，lTF1Dur1AElXIi/5jPV9h0XCm8ziPd9/R+tMYLsze1oAPxE87+Nwws=
Activation successful

• 激活單個節點

iotdbctl cluster activate default_cluster -N confignode1 -op license_path

• 通過license路徑方式激活

iotdbctl cluster activate default_cluster -op license_path

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers配置信息
• 讀取里面的機器碼
• 等待輸入激活碼

1.8 集群plugin分發

#分發udf
iotdbctl cluster dist-plugin default_cluster -type U -file /xxxx/udf.jar
#分發trigger
iotdbctl cluster dist-plugin default_cluster -type T -file /xxxx/trigger.jar
#分發pipe
iotdbctl cluster dist-plugin default_cluster -type P -file /xxxx/pipe.jar

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取 datanode_servers配置信息

• 上傳udf/trigger/pipe jar包

上傳完成后需要手動執行創建udf/trigger/pipe命令

1.9 集群滾動升級

iotdbctl cluster upgrade default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 上傳lib包

• confignode 執行停止、替換lib包、啟動，然后datanode執行停止、替換lib包、啟動

1.10 集群健康檢查

iotdbctl cluster health_check default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 每個節點執行health_check.sh

• 單個節點健康檢查

iotdbctl cluster health_check default_cluster -N datanode_1

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取datanode_servers配置信息
• datanode1 執行health_check.sh

1.11 集群停機備份

iotdbctl cluster backup default_cluster

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取confignode_servers和datanode_servers配置信息

• 每個節點執行backup.sh

• 單個節點健康檢查

iotdbctl cluster backup default_cluster -N datanode_1

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取datanode_servers配置信息
• datanode1 執行backup.sh

說明：多個節點部署到單臺機器，只支持 quick 模式

1.12 集群元數據導入

iotdbctl cluster importschema default_cluster -N datanode1 -param "-s ./dump0.csv -fd ./failed/ -lpf 10000"

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取datanode_servers配置信息
• datanode1 執行元數據導入import-schema.sh

其中 -param的參數如下:

命令	功能	是否必填
-s	指定想要導入的數據文件，這里可以指定文件或者文件夾。如果指定的是文件夾，將會把文件夾中所有的后綴為csv的文件進行批量導入。	是
-fd	指定一個目錄來存放導入失敗的文件，如果沒有指定這個參數，失敗的文件將會被保存到源數據的目錄中，文件名為是源文件名加上.failed的后綴。	否
-lpf	用于指定每個導入失敗文件寫入數據的行數，默認值為10000	否

1.13 集群元數據導出

iotdbctl cluster exportschema default_cluster -N datanode1 -param "-t ./ -pf ./pattern.txt -lpf 10 -t 10000"

• 根據 cluster-name 找到默認位置的 yaml 文件，獲取datanode_servers配置信息
• datanode1 執行元數據導入export-schema.sh

其中 -param的參數如下:

命令	功能	是否必填
-t	為導出的CSV文件指定輸出路徑	是
-path	指定導出元數據的path pattern,指定該參數后會忽略-s參數例如：root.stock.**	否
-pf	如果未指定-path，則需指定該參數，指定查詢元數據路徑所在文件路徑，支持 txt 文件格式，每個待導出的路徑為一行。	否
-lpf	指定導出的dump文件最大行數，默認值為10000。	否
-timeout	指定session查詢時的超時時間，單位為ms	否

1.14 集群部署工具樣例介紹

在集群部署工具安裝目錄中config/example 下面有3個yaml樣例，如果需要可以復制到config 中進行修改即可

名稱	說明
default_1c1d.yaml	1個confignode和1個datanode 配置樣例
default_3c3d.yaml	3個confignode和3個datanode 配置樣例
default_3c3d_grafa_prome	3個confignode和3個datanode、Grafana、Prometheus配置樣例

2. 數據文件夾概覽工具

IoTDB數據文件夾概覽工具用于打印出數據文件夾的結構概覽信息，工具位置為 tools/tsfile/print-iotdb-data-dir。

2.1 用法

• Windows:

.\print-iotdb-data-dir.bat <IoTDB數據文件夾路徑，如果是多個文件夾用逗號分隔> (<輸出結果的存儲路徑>)

• Linux or MacOs:

./print-iotdb-data-dir.sh <IoTDB數據文件夾路徑，如果是多個文件夾用逗號分隔> (<輸出結果的存儲路徑>)

注意：如果沒有設置輸出結果的存儲路徑, 將使用相對路徑"IoTDB_data_dir_overview.txt"作為默認值。

2.2 示例

以Windows系統為例：

.\print-iotdb-data-dir.bat D:\github\master\iotdb\data\datanode\data
````````````````````````
Starting Printing the IoTDB Data Directory Overview
````````````````````````
output save path:IoTDB_data_dir_overview.txt
data dir num:1
143  [main] WARN  o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs.
|==============================================================
|D:\github\master\iotdb\data\datanode\data
|--sequence
|  |--root.redirect0
|  |  |--1
|  |  |  |--0
|  |--root.redirect1
|  |  |--2
|  |  |  |--0
|  |--root.redirect2
|  |  |--3
|  |  |  |--0
|  |--root.redirect3
|  |  |--4
|  |  |  |--0
|  |--root.redirect4
|  |  |--5
|  |  |  |--0
|  |--root.redirect5
|  |  |--6
|  |  |  |--0
|  |--root.sg1
|  |  |--0
|  |  |  |--0
|  |  |  |--2760
|--unsequence
|==============================================================

3. TsFile概覽工具

TsFile概覽工具用于以概要模式打印出一個TsFile的內容，工具位置為 tools/tsfile/print-tsfile。

3.1 用法

• Windows:

.\print-tsfile-sketch.bat <TsFile文件路徑> (<輸出結果的存儲路徑>)

• Linux or MacOs:

./print-tsfile-sketch.sh <TsFile文件路徑> (<輸出結果的存儲路徑>)

注意：如果沒有設置輸出結果的存儲路徑, 將使用相對路徑"TsFile_sketch_view.txt"作為默認值。

3.2 示例

以Windows系統為例：

.\print-tsfile.bat D:\github\master\1669359533965-1-0-0.tsfile D:\github\master\sketch.txt
````````````````````````
Starting Printing the TsFile Sketch
````````````````````````
TsFile path:D:\github\master\1669359533965-1-0-0.tsfile
Sketch save path:D:\github\master\sketch.txt
148  [main] WARN  o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs.
-------------------------------- TsFile Sketch --------------------------------
file path: D:\github\master\1669359533965-1-0-0.tsfile
file length: 2974

            POSITION|   CONTENT
            --------    -------
                   0|   [magic head] TsFile
                   6|   [version number] 3
||||||||||||||||||||| [Chunk Group] of root.sg1.d1, num of Chunks:3
                   7|   [Chunk Group Header]
                    |           [marker] 0
                    |           [deviceID] root.sg1.d1
                  20|   [Chunk] of root.sg1.d1.s1, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19]
                    |           [chunk header] marker=5, measurementID=s1, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE
                    |           [page]  UncompressedSize:862, CompressedSize:860
                 893|   [Chunk] of root.sg1.d1.s2, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18]
                    |           [chunk header] marker=5, measurementID=s2, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE
                    |           [page]  UncompressedSize:862, CompressedSize:860
                1766|   [Chunk] of root.sg1.d1.s3, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19]
                    |           [chunk header] marker=5, measurementID=s3, dataSize=864, dataType=INT64, compressionType=SNAPPY, encodingType=RLE
                    |           [page]  UncompressedSize:862, CompressedSize:860
||||||||||||||||||||| [Chunk Group] of root.sg1.d1 ends
                2656|   [marker] 2
                2657|   [TimeseriesIndex] of root.sg1.d1.s1, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9032452783138882770,maxValue:9117677033041335123,firstValue:7068645577795875906,lastValue:-5833792328174747265,sumValue:5.795959009889246E19]
                    |           [ChunkIndex] offset=20
                2728|   [TimeseriesIndex] of root.sg1.d1.s2, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-8806861312244965718,maxValue:9192550740609853234,firstValue:1150295375739457693,lastValue:-2839553973758938646,sumValue:8.2822564314572677E18]
                    |           [ChunkIndex] offset=893
                2799|   [TimeseriesIndex] of root.sg1.d1.s3, tsDataType:INT64, startTime: 1669359533948 endTime: 1669359534047 count: 100 [minValue:-9076669333460323191,maxValue:9175278522960949594,firstValue:2537897870994797700,lastValue:7194625271253769397,sumValue:-2.126008424849926E19]
                    |           [ChunkIndex] offset=1766
                2870|   [IndexOfTimerseriesIndex Node] type=LEAF_MEASUREMENT
                    |           <s1, 2657>
                    |           <endOffset, 2870>
||||||||||||||||||||| [TsFileMetadata] begins
                2891|   [IndexOfTimerseriesIndex Node] type=LEAF_DEVICE
                    |           <root.sg1.d1, 2870>
                    |           <endOffset, 2891>
                    |   [meta offset] 2656
                    |   [bloom filter] bit vector byte array length=31, filterSize=256, hashFunctionSize=5
||||||||||||||||||||| [TsFileMetadata] ends
                2964|   [TsFileMetadataSize] 73
                2968|   [magic tail] TsFile
                2974|   END of TsFile
---------------------------- IndexOfTimerseriesIndex Tree -----------------------------
        [MetadataIndex:LEAF_DEVICE]
        └──────[root.sg1.d1,2870]
                        [MetadataIndex:LEAF_MEASUREMENT]
                        └──────[s1,2657]
---------------------------------- TsFile Sketch End ----------------------------------

解釋：

• 以"|"為分隔，左邊是在TsFile文件中的實際位置，右邊是梗概內容。
• "|||||||||||||||||||||"是為增強可讀性而添加的導引信息，不是TsFile中實際存儲的數據。
• 最后打印的"IndexOfTimerseriesIndex Tree"是對TsFile文件末尾的元數據索引樹的重新整理打印，便于直觀理解，不是TsFile中存儲的實際數據。

4. TsFile Resource概覽工具

TsFile resource概覽工具用于打印出TsFile resource文件的內容，工具位置為 tools/tsfile/print-tsfile-resource-files。

4.1 用法

• Windows:

.\print-tsfile-resource-files.bat <TsFile resource文件所在的文件夾路徑，或者單個TsFile resource文件路徑>

• Linux or MacOs:

./print-tsfile-resource-files.sh <TsFile resource文件所在的文件夾路徑，或者單個TsFile resource文件路徑>

4.2 示例

以Windows系統為例：

.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0
````````````````````````
Starting Printing the TsFileResources
````````````````````````
147  [main] WARN  o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs.
230  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration
231  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources.
233  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration
237  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources.
Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ...

Resource plan index range [9223372036854775807, -9223372036854775808]
device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00])

Analyzing the resource file folder D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0 finished.

.\print-tsfile-resource-files.bat D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource
````````````````````````
Starting Printing the TsFileResources
````````````````````````
178  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration
186  [main] WARN  o.a.i.t.c.conf.TSFileDescriptor - not found iotdb-system.properties, use the default configs.
187  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources.
188  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Cannot find IOTDB_HOME or IOTDB_CONF environment variable when loading config file iotdb-system.properties, use default configuration
192  [main] WARN  o.a.iotdb.db.conf.IoTDBDescriptor - Couldn't load the configuration iotdb-system.properties from any of the known sources.
Analyzing D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile ...

Resource plan index range [9223372036854775807, -9223372036854775808]
device root.sg1.d1, start time 0 (1970-01-01T08:00+08:00[GMT+08:00]), end time 99 (1970-01-01T08:00:00.099+08:00[GMT+08:00])

Analyzing the resource file D:\github\master\iotdb\data\datanode\data\sequence\root.sg1\0\0\1669359533489-1-0-0.tsfile.resource finished.