部署指导

IoTDB 提供单机版、集群版和双活版共 3 种部署形态。本章节将详细介绍每一种部署形态的具体部署步骤。

预备知识

在开始部署前，您需要充分了解下面的预备知识。

安装包结构

首先，需要获取安装包，名字为 apache-iotdb-{version}-all-bin 的安装包包含 ConfigNode 和 DataNode 的可执行程序，请将安装包部署于目标集群的所有机器上，推荐将安装包部署于所有服务器的相同目录下。

之后，需要对 IoTDB 安装包的结构有了解。IoTDB 安装包目录结构如下：

目录	说明
conf	配置文件目录，包含 ConfigNode、DataNode、JMX 和 logback 等配置文件
data	数据文件目录，包含 ConfigNode 和 DataNode 的数据文件
lib	库文件目录
licenses	证书文件目录
logs	日志文件目录，包含 ConfigNode 和 DataNode 的日志文件
sbin	脚本目录，包含 ConfigNode 和 DataNode 的启停移除脚本，以及 Cli 的启动脚本等
tools	系统工具目录

配置文件

必要情况下，您需要根据业务需求，修改每个服务器上的配置文件。登录服务器，并将工作路径切换至 apache-iotdb-{version}-all-bin，配置文件在 ./conf 目录内。

• 对于所有部署 ConfigNode 的服务器，需要修改 通用配置 和 ConfigNode 配置 。
• 对于所有部署 DataNode 的服务器，需要修改 通用配置 和 DataNode 配置 。

通用配置

打开通用配置文件 ./conf/iotdb-common.properties，可根据 部署推荐设置以下参数：

配置项	说明	默认
cluster_name	节点希望加入的集群的名称	defaultCluster
config_node_consensus_protocol_class	ConfigNode 使用的共识协议	org.apache.iotdb.consensus.ratis.RatisConsensus
schema_replication_factor	元数据副本数，DataNode 数量不应少于此数目	1
schema_region_consensus_protocol_class	元数据副本组的共识协议	org.apache.iotdb.consensus.ratis.RatisConsensus
data_replication_factor	数据副本数，DataNode 数量不应少于此数目	1
data_region_consensus_protocol_class	数据副本组的共识协议。注：RatisConsensus 目前不支持多数据目录	org.apache.iotdb.consensus.iot.IoTConsensus

注意：上述配置项在集群启动后即不可更改，且务必保证所有节点的通用配置完全一致，否则节点无法启动。

ConfigNode 配置

打开 ConfigNode 配置文件 ./conf/iotdb-confignode.properties，根据服务器/虚拟机的 IP 地址和可用端口，设置以下参数：

配置项	说明	默认	用法
cn_internal_address	ConfigNode 在集群内部通讯使用的地址	127.0.0.1	设置为服务器的 IPV4 地址或域名
cn_internal_port	ConfigNode 在集群内部通讯使用的端口	10710	设置为任意未占用端口
cn_consensus_port	ConfigNode 副本组共识协议通信使用的端口	10720	设置为任意未占用端口
cn_target_config_node_list	节点注册加入集群时连接的 ConfigNode 的地址。注：只能配置一个	127.0.0.1:10710	对于 Seed-ConfigNode，设置为自己的 cn_internal_address:cn_internal_port；对于其它 ConfigNode，设置为另一个正在运行的 ConfigNode 的 cn_internal_address:cn_internal_port

注意：上述配置项在节点启动后即不可更改，且务必保证所有端口均未被占用，否则节点无法启动。

DataNode 配置

打开 DataNode 配置文件 ./conf/iotdb-datanode.properties，根据服务器/虚拟机的 IP 地址和可用端口，设置以下参数：

配置项	说明	默认	用法
dn_rpc_address	客户端 RPC 服务的地址	127.0.0.1	设置为服务器的 IPV4 地址或域名
dn_rpc_port	客户端 RPC 服务的端口	6667	设置为任意未占用端口
dn_internal_address	DataNode 在集群内部接收控制流使用的地址	127.0.0.1	设置为服务器的 IPV4 地址或域名
dn_internal_port	DataNode 在集群内部接收控制流使用的端口	10730	设置为任意未占用端口
dn_mpp_data_exchange_port	DataNode 在集群内部接收数据流使用的端口	10740	设置为任意未占用端口
dn_data_region_consensus_port	DataNode 的数据副本间共识协议通信的端口	10750	设置为任意未占用端口
dn_schema_region_consensus_port	DataNode 的元数据副本间共识协议通信的端口	10760	设置为任意未占用端口
dn_target_config_node_list	集群中正在运行的 ConfigNode 地址	127.0.0.1:10710	设置为任意正在运行的 ConfigNode 的 cn_internal_address:cn_internal_port，可设置多个，用逗号（“,”）隔开

注意：上述配置项在节点启动后即不可更改，且务必保证所有端口均未被占用，否则节点无法启动。

环境检查

最后，在正式部署前，还需要对下列项目进行检查：

1. JDK>=1.8 的运行环境，并配置好 JAVA_HOME 环境变量。
2. 设置最大文件打开数为 65535。
3. 关闭交换内存。
4. 首次启动 ConfigNode 节点时，确保已清空 ConfigNode 节点的 data/confignode 目录；首次启动 DataNode 节点时，确保已清空 DataNode 节点的 data/datanode 目录。
5. 如果整个集群处在可信环境下，可以关闭机器上的防火墙选项。
6. 在集群默认配置中，ConfigNode 会占用端口 10710 和 10720，DataNode 会占用端口 6667、10730、10740、10750 和 10760，请确保这些端口未被占用，或者手动修改配置文件中的端口配置。

FAQ

在部署集群过程中有任何问题，请参考 分布式部署FAQ。

单机版部署

本小节描述如何启动包括 1 个 ConfigNode 和 1 个 DataNode 的实例。

启动流程

在完成配置文件的修改后（一般仅需要修改 IP 等信息） ，用户可以使用 sbin 文件夹下的 start-standalone 脚本启动 IoTDB。

Linux 系统与 MacOS 系统启动命令如下：

> bash sbin/start-standalone.sh

Windows 系统启动命令如下：

> sbin\start-standalone.bat

注意：目前，要使用单机模式，你需要保证所有的地址设置为 127.0.0.1，如果需要从非 IoTDB 所在的机器访问此IoTDB，请将配置项 dn_rpc_address 修改为 IoTDB 所在的机器 IP。

验证部署

若搭建的集群仅用于本地调试，可直接执行 ./sbin 目录下的 Cli 启动脚本：

# Linux
./sbin/start-cli.sh

# Windows
.\sbin\start-cli.bat

若希望通过 Cli 连接生产环境的集群， 请阅读 Cli 使用手册。

成功启动集群后，在 Cli 执行 show cluster details：

• 若所有节点的状态均为 Running，则说明集群部署成功；
• 否则，请阅读启动失败节点的运行日志，并检查对应的配置参数。

停止流程

Linux 系统与 MacOS 系统停止命令如下：

> bash sbin/stop-standalone.sh

Windows 系统停止命令如下：

> sbin\stop-standalone.bat

集群版部署（使用集群管理工具）

IoTDB 集群管理工具是一款易用的运维工具（企业版工具）。旨在解决 IoTDB 分布式系统多节点的运维难题，主要包括集群部署、集群启停、弹性扩容、配置更新、数据导出等功能，从而实现对复杂数据库集群的一键式指令下发， 极大降低管理难度。本文档将说明如何用集群管理工具远程部署、配置、启动和停止 IoTDB 集群实例。

环境准备

本工具为 TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。

IoTDB 要部署的机器需要依赖jdk 8及以上版本、lsof、netstat、unzip功能如果没有请自行安装，可以参考文档最后的一节环境所需安装命令。

提示:IoTDB集群管理工具需要使用有root权限的账号

部署方法

下载安装

本工具为TimechoDB（基于IoTDB的企业版数据库）配套工具，您可以联系您的销售获取工具下载方式。

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

• 在iotd目录内输入以下指令后：

bash install-iotd.sh

即可在之后的 shell 内激活 iotd 关键词，如检查部署前所需的环境指令如下所示：

iotd cluster check example

• 也可以不激活iotd直接使用 <iotd absolute path>/sbin/iotd 来执行命令，如检查部署前所需的环境：

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

系统结构

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

• config存放要部署的集群配置文件如果要使用集群部署工具需要修改里面的yaml文件。

• logs 存放部署工具日志，如果想要查看部署工具执行日志请查看logs/iotd_yyyy_mm_dd.log。

• sbin 存放集群部署工具所需的二进制包。

• doc 存放用户手册、开发手册和推荐部署手册。

集群配置文件介绍

• 在iotd/config 目录下有集群配置的yaml文件，yaml文件名字就是集群名字yaml 文件可以有多个，为了方便用户配置yaml文件在iotd/config目录下面提供了default_cluster.yaml示例。
• yaml 文件配置由global、confignode_servers、datanode_servers、grafana_server、prometheus_server四大部分组成
• global 是通用配置主要配置机器用户名密码、IoTDB本地安装文件、Jdk配置等。在iotd/config目录中提供了一个default_cluster.yaml样例数据， 用户可以复制修改成自己集群名字并参考里面的说明进行配置IoTDB集群，在default_cluster.yaml样例中没有注释的均为必填项，已经注释的为非必填项。

例如要执行default_cluster.yaml检查命令则需要执行命令iotd 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登录端口	必填
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_target_config_node_list	集群配置地址指向存活的ConfigNode,默认指向confignode_x，在global与confignode_servers同时配置值时优先使用confignode_servers中的值，对应iotdb/config/iotdb-confignode.properties中的cn_target_config_node_list	必填
dn_target_config_node_list	集群配置地址指向存活的ConfigNode,默认指向confignode_x，在global与datanode_servers同时配置值时优先使用datanode_servers中的值，对应iotdb/config/iotdb-datanode.properties中的dn_target_config_node_list	必填

其中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 部署目录	必填｜
iotdb-confignode.properties	对应iotdb/config/iotdb-confignode.properties更加详细请参看iotdb-confignode.properties文件说明	非必填
cn_internal_address	对应iotdb/内部通信地址，对应iotdb/config/iotdb-confignode.properties中的cn_internal_address	必填
cn_target_config_node_list	集群配置地址指向存活的ConfigNode,默认指向confignode_x，在global与confignode_servers同时配置值时优先使用confignode_servers中的值，对应iotdb/config/iotdb-confignode.properties中的cn_target_config_node_list	必填
cn_internal_port	内部通信端口，对应iotdb/config/iotdb-confignode.properties中的cn_internal_port	必填
cn_consensus_port	对应iotdb/config/iotdb-confignode.properties中的cn_consensus_port	非必填
cn_data_dir	对应iotdb/config/iotdb-confignode.properties中的cn_data_dir	必填
iotdb-common.properties	对应iotdb/config/iotdb-common.properties在global与confignode_servers同时配置值优先使用confignode_servers中的值	非必填

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

参数	说明	是否必填
name	Datanode 名称	必填
deploy_dir	IoTDB data node 部署目录	必填
iotdb-datanode.properties	对应iotdb/config/iotdb-datanode.properties更加详细请参看iotdb-datanode.properties文件说明	非必填
dn_rpc_address	datanode rpc 地址对应iotdb/config/iotdb-datanode.properties中的dn_rpc_address	必填
dn_internal_address	内部通信地址，对应iotdb/config/iotdb-datanode.properties中的dn_internal_address	必填
dn_target_config_node_list	集群配置地址指向存活的ConfigNode,默认指向confignode_x，在global与datanode_servers同时配置值时优先使用datanode_servers中的值，对应iotdb/config/iotdb-datanode.properties中的dn_target_config_node_list	必填
dn_rpc_port	datanode rpc端口地址，对应iotdb/config/iotdb-datanode.properties中的dn_rpc_port	必填
dn_internal_port	内部通信端口，对应iotdb/config/iotdb-datanode.properties中的dn_internal_port	必填
iotdb-common.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-datanode.properties和iotdb-confignode.properties中配置了metrics,则会自动把配置放入到promethues无需手动修改

注意:如何配置yaml key对应的值包含特殊字符如:等建议整个value使用双引号，对应的文件路径中不要使用包含空格的路径，防止出现识别出现异常问题。

使用场景

清理数据场景

• 清理集群数据场景会删除IoTDB集群中的data目录以及yaml文件中配置的cn_system_dir、cn_consensus_dir、 dn_data_dirs、dn_consensus_dir、dn_system_dir、logs和ext目录。
• 首先执行停止集群命令、然后在执行集群清理命令。

iotd cluster stop default_cluster
iotd 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部署目录。
• 首先执行停止集群命令、然后在执行集群销毁命令。

iotd cluster stop default_cluster
iotd 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集群命令即可完成集群升级

iotd cluster upgrade default_cluster
iotd cluster restart default_cluster

集群配置文件的热部署场景

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

iotd cluster distribute default_cluster
iotd cluster reload default_cluster

集群扩容场景

• 首先修改在config/xxx.yaml中添加一个datanode 或者confignode 节点。
• 执行集群扩容命令

iotd cluster scaleout default_cluster

集群缩容场景

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

iotd 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_target_config_node_list、dn_target_config_node_list
• 配置confignode_servers中iotdb-confignode.properties里面的cn_internal_address、cn_internal_port、cn_consensus_port、cn_system_dir、 cn_consensus_dir和iotdb-common.properties里面的值不是IoTDB默认的则需要配置否则可不必配置
• 配置datanode_servers中iotdb-datanode.properties里面的dn_rpc_address、dn_internal_address、dn_data_dirs、dn_consensus_dir、dn_system_dir和iotdb-common.properties等
• 执行初始化命令

iotd cluster init default_cluster

一键部署IoTDB、Grafana和Prometheus 场景

• 配置iotdb-datanode.properties 、iotdb-confignode.properties 打开metrics接口
• 配置Grafana 配置，如果dashboards 有多个就用逗号隔开，名字不能重复否则会被覆盖。
• 配置Prometheus配置，IoTDB 集群配置了metrics 则无需手动修改Prometheus 配置会根据哪个节点配置了metrics，自动修改Prometheus 配置。
• 启动集群

iotd cluster start default_cluster

更加详细参数请参考上方的 集群配置文件介绍

命令格式

本工具的基本用法为：

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

• key 表示了具体的命令。

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

• params 表示了命令的所需参数(选填)。

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

iotd cluster deploy default_cluster

• 集群的功能及参数列表如下：

命令	功能	参数
check	检测集群是否可以部署	集群名称列表
clean	清理集群	集群名称
deploy	部署集群	集群名称 ,-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(nodename、grafana、prometheus可选)
show	查看集群信息，details字段表示展示集群信息细节	集群名称, details(可选)
destroy	销毁集群	集群名称,-N,模块名称(iotdb、grafana、prometheus可选)
scaleout	集群扩容	集群名称
scalein	集群缩容	集群名称，-N，集群节点名字或集群节点ip+port
reload	集群热加载	集群名称
distribute	集群配置文件分发	集群名称
dumplog	备份指定集群日志	集群名称,-N,集群节点名字 -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -loglevel 日志类型 -l 传输速度
dumpdata	备份指定集群数据	集群名称, -h 备份至目标机器ip -pw 备份至目标机器密码 -p 备份至目标机器端口 -path 备份的目录 -startdate 起始时间 -enddate 结束时间 -l 传输速度
upgrade	lib 包升级	集群名字(升级完后请重启)
init	已有集群使用集群部署工具时，初始化集群配置	集群名字，初始化集群配置
status	查看进程状态	集群名字

详细命令执行过程

下面的命令都是以default_cluster.yaml 为示例执行的，用户可以修改成自己的集群文件来执行

检查集群部署环境命令

iotd 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 不满足要求需要在服务器上自行安装。

部署集群命令

iotd 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-common.properties、iotdb-confignode.properties、iotdb-datanode.properties

iotd cluster deploy default_cluster -op force

注意：该命令会强制执行部署，具体过程会删除已存在的部署目录重新部署

部署单个模块

# 部署grafana模块
iotd cluster deploy default_cluster -N grafana
# 部署prometheus模块
iotd cluster deploy default_cluster -N prometheus
# 部署iotdb模块
iotd cluster deploy default_cluster -N iotdb

启动集群命令

iotd 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 节点名称启动
iotd cluster start default_cluster -N datanode_1
#按照IoTDB 集群ip+port启动，其中port对应confignode的cn_internal_port、datanode的rpc_port
iotd cluster start default_cluster -N 192.168.1.5:6667
#启动grafana
iotd cluster start default_cluster -N grafana
#启动prometheus
iotd 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命令进行查看当前集群状态(iotd cluster status xxx)

查看IoTDB集群状态命令

iotd cluster show default_cluster
#查看IoTDB集群详细信息
iotd cluster show default_cluster details

• 根据 cluster-name 找到默认位置的 yaml 文件，获取confignode_servers和datanode_servers配置信息

• 依次在datanode通过cli执行show cluster details 如果有一个节点执行成功则不会在后续节点继续执行cli直接返回结果

停止集群命令

iotd cluster stop default_cluster

• 根据 cluster-name 找到默认位置的 yaml 文件，获取confignode_servers和datanode_servers配置信息

• 根据datanode_servers中datanode节点信息，按照配置先后顺序依次停止datanode节点

• 根据confignode_servers中confignode节点信息，按照配置依次停止confignode节点

强制停止集群命令

iotd cluster stop default_cluster -op force

会直接执行kill -9 pid 命令强制停止集群

停止单个节点命令

#按照IoTDB 节点名称停止
iotd cluster stop default_cluster -N datanode_1
#按照IoTDB 集群ip+port停止(ip+port是按照datanode中的ip+dn_rpc_port获取唯一节点或confignode中的ip+cn_internal_port获取唯一节点)
iotd cluster stop default_cluster -N 192.168.1.5:6667
#停止grafana
iotd cluster stop default_cluster -N grafana
#停止prometheus
iotd 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集群并未停止。

清理集群数据命令

iotd 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目录。

重启集群命令

iotd cluster restart default_cluster

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

• 执行上述的停止集群命令(stop),然后执行启动集群命令(start) 具体参考上面的start 和stop 命令

强制重启集群命令

iotd cluster restart default_cluster -op force

会直接执行kill -9 pid 命令强制停止集群，然后启动集群

重启单个节点命令

#按照IoTDB 节点名称重启datanode_1
iotd cluster restart default_cluster -N datanode_1
#按照IoTDB 节点名称重启confignode_1
iotd cluster restart default_cluster -N confignode_1
#重启grafana
iotd cluster restart default_cluster -N grafana
#重启prometheus
iotd cluster restart default_cluster -N prometheus

集群缩容命令

#按照节点名称缩容
iotd cluster scalein default_cluster -N nodename
#按照ip+port缩容(ip+port按照datanode中的ip+dn_rpc_port获取唯一节点，confignode中的ip+cn_internal_port获取唯一节点)
iotd 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

提示：目前一次仅支持一个节点缩容

集群扩容命令

iotd 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-common.properties、iotdb-confignode.properties或iotdb-datanode.properties

• 执行启动该节点命令并校验节点是否启动成功

提示：目前一次仅支持一个节点扩容

销毁集群命令

iotd 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模块
iotd cluster destroy default_cluster -N grafana
# 销毁prometheus模块
iotd cluster destroy default_cluster -N prometheus
# 销毁iotdb模块
iotd cluster destroy default_cluster -N iotdb

分发集群配置命令

iotd cluster distribute default_cluster

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

• 根据yaml文件节点配置信息生成并依次上传iotdb-common.properties、iotdb-confignode.properties、iotdb-datanode.properties、到指定节点

热加载集群配置命令

iotd cluster reload default_cluster

• 根据 cluster-name 找到默认位置的 yaml 文件，获取confignode_servers和datanode_servers配置信息

• 根据yaml文件节点配置信息依次在cli中执行load configuration

集群节点日志备份

iotd 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）	否

集群节点数据备份

iotd 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	截止时间(包含)	是

集群升级

iotd cluster upgrade default_cluster

• 根据 cluster-name 找到默认位置的 yaml 文件，获取confignode_servers和datanode_servers配置信息

• 上传lib包

注意执行完升级后请重启IoTDB 才能生效

集群初始化

iotd cluster init default_cluster

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

查看集群进程状态

iotd cluster status default_cluster

• 根据 cluster-name 找到默认位置的 yaml 文件，获取confignode_servers、datanode_servers、grafana、prometheus配置信息
• 展示集群的存活状态

集群部署工具样例介绍

在集群部署工具安装目录中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配置样例

集群版部署（手工部署）

启动流程

本小节描述如何启动包括若干 ConfigNode 和 DataNode 的集群。 集群可以提供服务的标准是至少启动一个 ConfigNode 且启动不小于（数据/元数据）副本个数的 DataNode。

总体启动流程分为三步：

1. 启动种子 ConfigNode
2. 增加 ConfigNode（可选）
3. 增加 DataNode

启动 Seed-ConfigNode

集群第一个启动的节点必须是 ConfigNode，第一个启动的 ConfigNode 必须遵循本小节教程。

第一个启动的 ConfigNode 是 Seed-ConfigNode，标志着新集群的创建。 在启动 Seed-ConfigNode 前，请打开通用配置文件 ./conf/iotdb-common.properties，并检查如下参数：

配置项	检查
cluster_name	已设置为期望的集群名称
config_node_consensus_protocol_class	已设置为期望的共识协议
schema_replication_factor	已设置为期望的元数据副本数
schema_region_consensus_protocol_class	已设置为期望的共识协议
data_replication_factor	已设置为期望的数据副本数
data_region_consensus_protocol_class	已设置为期望的共识协议

注意： 请根据部署推荐配置合适的通用参数，这些参数在首次配置后即不可修改。

接着请打开它的配置文件 ./conf/iotdb-confignode.properties，并检查如下参数：

配置项	检查
cn_internal_address	已设置为服务器的 IPV4 地址或域名
cn_internal_port	该端口未被占用
cn_consensus_port	该端口未被占用
cn_target_config_node_list	已设置为自己的内部通讯地址，即 cn_internal_address:cn_internal_port

检查完毕后，即可在服务器上运行启动脚本：

# Linux 前台启动
bash ./sbin/start-confignode.sh

# Linux 后台启动
nohup bash ./sbin/start-confignode.sh >/dev/null 2>&1 &

# Windows
.\sbin\start-confignode.bat

ConfigNode 的其它配置参数可参考 ConfigNode 配置参数。

增加更多 ConfigNode（可选）

只要不是第一个启动的 ConfigNode 就必须遵循本小节教程。

可向集群添加更多 ConfigNode，以保证 ConfigNode 的高可用。常用的配置为额外增加两个 ConfigNode，使集群共有三个 ConfigNode。

新增的 ConfigNode 需要保证 ./conf/iotdb-common.properites 中的所有配置参数与 Seed-ConfigNode 完全一致，否则可能启动失败或产生运行时错误。 因此，请着重检查通用配置文件中的以下参数：

配置项	检查
cluster_name	与 Seed-ConfigNode 保持一致
config_node_consensus_protocol_class	与 Seed-ConfigNode 保持一致
schema_replication_factor	与 Seed-ConfigNode 保持一致
schema_region_consensus_protocol_class	与 Seed-ConfigNode 保持一致
data_replication_factor	与 Seed-ConfigNode 保持一致
data_region_consensus_protocol_class	与 Seed-ConfigNode 保持一致

接着请打开它的配置文件 ./conf/iotdb-confignode.properties，并检查以下参数：

配置项	检查
cn_internal_address	已设置为服务器的 IPV4 地址或域名
cn_internal_port	该端口未被占用
cn_consensus_port	该端口未被占用
cn_target_config_node_list	已设置为另一个正在运行的 ConfigNode 的内部通讯地址，推荐使用 Seed-ConfigNode 的内部通讯地址

检查完毕后，即可在服务器上运行启动脚本：

# Linux 前台启动
bash ./sbin/start-confignode.sh

# Linux 后台启动
nohup bash ./sbin/start-confignode.sh >/dev/null 2>&1 &

# Windows
.\sbin\start-confignode.bat

ConfigNode 的其它配置参数可参考 ConfigNode配置参数

增加 DataNode

确保集群已有正在运行的 ConfigNode 后，才能开始增加 DataNode。

可以向集群中添加任意个 DataNode。 在添加新的 DataNode 前，请先打开通用配置文件 ./conf/iotdb-common.properties 并检查以下参数：

配置项	检查
cluster_name	与 Seed-ConfigNode 保持一致

接着打开它的配置文件 ./conf/iotdb-datanode.properties 并检查以下参数：

配置项	检查
dn_rpc_address	已设置为服务器的 IPV4 地址或域名
dn_rpc_port	该端口未被占用
dn_internal_address	已设置为服务器的 IPV4 地址或域名
dn_internal_port	该端口未被占用
dn_mpp_data_exchange_port	该端口未被占用
dn_data_region_consensus_port	该端口未被占用
dn_schema_region_consensus_port	该端口未被占用
dn_target_config_node_list	已设置为正在运行的 ConfigNode 的内部通讯地址，推荐使用 Seed-ConfigNode 的内部通讯地址

检查完毕后，即可在服务器上运行启动脚本：

# Linux 前台启动
bash ./sbin/start-datanode.sh

# Linux 后台启动
nohup bash ./sbin/start-datanode.sh >/dev/null 2>&1 &

# Windows
.\sbin\start-datanode.bat

DataNode 的其它配置参数可参考 DataNode配置参数。

注意：当且仅当集群拥有不少于副本个数（max{schema_replication_factor, data_replication_factor}）的 DataNode 后，集群才可以提供服务

验证部署

若搭建的集群仅用于本地调试，可直接执行 ./sbin 目录下的 Cli 启动脚本：

# Linux
./sbin/start-cli.sh

# Windows
.\sbin\start-cli.bat

若希望通过 Cli 连接生产环境的集群， 请阅读 Cli 使用手册。

以在6台服务器上启动的3C3D（3个ConfigNode 和 3个DataNode）集群为例， 这里假设3个ConfigNode的IP地址依次为192.168.1.10、192.168.1.11、192.168.1.12，且3个ConfigNode启动时均使用了默认的端口10710与10720； 3个DataNode的IP地址依次为192.168.1.20、192.168.1.21、192.168.1.22，且3个DataNode启动时均使用了默认的端口6667、10730、10740、10750与10760。

成功启动集群后，在 Cli 执行 show cluster details，看到的结果应当如下：

IoTDB> show cluster details
+------+----------+-------+---------------+------------+-------------------+------------+-------+-------+-------------------+-----------------+
|NodeID|  NodeType| Status|InternalAddress|InternalPort|ConfigConsensusPort|  RpcAddress|RpcPort|MppPort|SchemaConsensusPort|DataConsensusPort|
+------+----------+-------+---------------+------------+-------------------+------------+-------+-------+-------------------+-----------------+
|     0|ConfigNode|Running|   192.168.1.10|       10710|              10720|            |       |       |                   |                 |
|     2|ConfigNode|Running|   192.168.1.11|       10710|              10720|            |       |       |                   |                 |
|     3|ConfigNode|Running|   192.168.1.12|       10710|              10720|            |       |       |                   |                 |
|     1|  DataNode|Running|   192.168.1.20|       10730|                   |192.168.1.20|   6667|  10740|              10750|            10760|
|     4|  DataNode|Running|   192.168.1.21|       10730|                   |192.168.1.21|   6667|  10740|              10750|            10760|
|     5|  DataNode|Running|   192.168.1.22|       10730|                   |192.168.1.22|   6667|  10740|              10750|            10760|
+------+----------+-------+---------------+------------+-------------------+------------+-------+-------+-------------------+-----------------+
Total line number = 6
It costs 0.012s

若所有节点的状态均为 Running，则说明集群部署成功； 否则，请阅读启动失败节点的运行日志，并检查对应的配置参数。

停止流程

本小节描述如何手动关闭 IoTDB 的 ConfigNode 或 DataNode 进程。

使用脚本停止 ConfigNode

执行停止 ConfigNode 脚本：

# Linux
./sbin/stop-confignode.sh

# Windows
.\sbin\stop-confignode.bat

使用脚本停止 DataNode

执行停止 DataNode 脚本：

# Linux
./sbin/stop-datanode.sh

# Windows
.\sbin\stop-datanode.bat

停止节点进程

首先获取节点的进程号：

jps

# 或

ps aux | grep iotdb

结束进程：

kill -9 <pid>

注意：有些端口的信息需要 root 权限才能获取，在此情况下请使用 sudo

集群缩容

本小节描述如何将 ConfigNode 或 DataNode 移出集群。

移除 ConfigNode

在移除 ConfigNode 前，请确保移除后集群至少还有一个活跃的 ConfigNode。 在活跃的 ConfigNode 上执行 remove-confignode 脚本：

# Linux
## 根据 confignode_id 移除节点
./sbin/remove-confignode.sh <confignode_id>

## 根据 ConfigNode 内部通讯地址和端口移除节点
./sbin/remove-confignode.sh <cn_internal_address>:<cn_internal_port>


# Windows
## 根据 confignode_id 移除节点
.\sbin\remove-confignode.bat <confignode_id>

## 根据 ConfigNode 内部通讯地址和端口移除节点
.\sbin\remove-confignode.bat <cn_internal_address>:<cn_internal_port>

移除 DataNode

在移除 DataNode 前，请确保移除后集群至少还有不少于（数据/元数据）副本个数的 DataNode。 在活跃的 DataNode 上执行 remove-datanode 脚本：

# Linux
## 根据 datanode_id 移除节点
./sbin/remove-datanode.sh <datanode_id>

## 根据 DataNode RPC 服务地址和端口移除节点
./sbin/remove-datanode.sh <dn_rpc_address>:<dn_rpc_port>


# Windows
## 根据 datanode_id 移除节点
.\sbin\remove-datanode.bat <datanode_id>

## 根据 DataNode RPC 服务地址和端口移除节点
.\sbin\remove-datanode.bat <dn_rpc_address>:<dn_rpc_port>

双活版部署

IoTDB 的双活集群指的是两个独立的集群，它们的配置完全独立，可以同时接收外界的写入，每一个独立的集群都可以将写入到自己数据同步到另一个集群中， 两个集群的数据可达到最终一致。

两个集群可构成一个高可用组：当其中一个集群停止服务时，另一个集群不会受到影响。当停止服务的集群再次启动时，另一个集群会将新写入的数据同步过来。 业务可以绑定两个集群进行读写，从而达到高可用的目的。

双活集群的部署方案允许在物理节点少于 3 的情况下实现高可用，在部署成本上具备一定优势。

请参考 分布式部署FAQ