Apache IoTDB 部署全指南：AINode 独立部署与 Kubernetes 集群部署

IoTDB（Internet of Things Database）作为一款专为时间序列数据设计的数据库，在工业物联网、智能监控等领域应用广泛。随着业务需求的不断发展，仅依靠 ConfigNode 和 DataNode 已难以满足复杂的时序数据机器学习分析需求，AINode 应运而生，为 IoTDB 扩展了机器学习分析能力。同时，在大规模部署场景下，Kubernetes 凭借其强大的容器编排和管理能力，成为 IoTDB 集群部署的理想选择。本文将详细介绍 IoTDB 的 AINode 独立部署和 Kubernetes 集群部署方案，帮助读者轻松完成 IoTDB 相关部署工作。

一、引言

IoTDB（Internet of Things Database）作为一款专为时间序列数据设计的数据库，在工业物联网、智能监控等领域应用广泛。随着业务需求的不断发展，仅依靠 ConfigNode 和 DataNode 已难以满足复杂的时序数据机器学习分析需求，AINode 应运而生，为 IoTDB 扩展了机器学习分析能力。同时，在大规模部署场景下，Kubernetes 凭借其强大的容器编排和管理能力，成为 IoTDB 集群部署的理想选择。本文将详细介绍 IoTDB 的 AINode 独立部署和 Kubernetes 集群部署方案，帮助读者轻松完成 IoTDB 相关部署工作。

二、AINode 独立部署

2.1 AINode 简介

AINode 是 IoTDB 在 ConfigNode、DataNode 之后提供的第三种内生节点，通过与 IoTDB 集群的 DataNode、ConfigNode 交互，扩展了对时间序列进行机器学习分析的能力。它支持从外部引入已有机器学习模型进行注册，使用注册的模型在指定时序数据上通过简单 SQL 语句完成时序分析任务，将模型的创建、管理及推理融合在数据库引擎中，目前已提供预测、异常检测等常见时序分析场景的机器学习算法或自研模型。AINode 以独立安装包的形式交付，是 IoTDB 集群外的额外套件。

2.2 安装准备

2.2.1 安装包获取

首先需要获取 AINode 安装包，其文件名格式为 apache-iotdb--ainode-bin.zip。解压该安装包后，会得到以下目录结构：

目录/文件	类型	说明
lib	文件夹	存放 AINode 的 python 包文件，这些包文件是 AINode 运行的基础依赖
sbin	文件夹	包含 AINode 的运行脚本，可实现 AINode 的启动、停止和移除等操作
conf	文件夹	存储 AINode 的配置文件和运行环境设置脚本，通过修改配置文件可自定义 AINode 运行参数
LICENSE	文件	证书文件，规定了 AINode 的使用许可条款
NOTICE	文件	提示文件，包含一些重要的声明和提示信息
README_ZH.md	文件	中文版的说明文档，详细介绍了 AINode 的功能、安装和使用方法
README.md	文件	英文版的使用说明，内容与中文版类似，供英文用户参考

2.2.2 环境准备

• 操作系统：建议使用 Ubuntu 或 MacOS，这两种操作系统对 AINode 的兼容性较好，能减少部署过程中的兼容性问题。
• IoTDB 版本：要求 IoTDB 版本不低于 V2.0.5.1，较低版本的 IoTDB 可能不支持 AINode 的部分功能。
• Python 环境：Python 版本需在 3.9~3.12 之间，且必须带有 pip 和 venv 工具。pip 用于安装 Python 依赖包，venv 用于创建独立的 Python 虚拟环境，避免与系统其他 Python 环境产生冲突。

可通过以下命令查看 Python 版本，确认是否满足要求：

python --version
# 或
python3 --version

2.3 安装部署步骤

2.3.1 安装 AINode

首先，选择一个合适的目录作为 AINode 的专用文件夹，将下载的 AINode 安装包导入该文件夹，然后执行以下命令解压安装包：

unzip apache-iotdb-<version>-ainode-bin.zip

解压完成后，AINode 的安装目录结构便搭建完成。

2.3.2 配置项修改

AINode 支持修改一些必要的参数，以适应不同的运行环境和需求。这些参数位于 conf/iotdb-ainode.properties 文件中，可进行持久化修改，各主要参数说明如下：

参数名称	描述	类型	默认值	说明
cluster_name	AINode 要加入集群的标识	string	defaultCluster	用于区分不同的 IoTDB 集群，确保 AINode 加入正确的集群
ain_seed_config_node	AINode 启动时注册的 ConfigNode 地址	String	127.0.0.1:10710	AINode 启动时会向该地址的 ConfigNode 进行注册，需根据实际 ConfigNode 地址修改
ain_cluster_ingress_address	AINode 拉取数据的 DataNode 的 rpc 地址	String	127.0.0.1	指定 AINode 从哪个 DataNode 拉取时序数据，需填写实际 DataNode 的 rpc 地址
ain_cluster_ingress_port	AINode 拉取数据的 DataNode 的 rpc 端口	Integer	6667	与上述 DataNode 地址对应的 rpc 端口，需与 DataNode 的配置保持一致
ain_cluster_ingress_username	AINode 拉取数据的 DataNode 的客户端用户名	String	root	用于访问 DataNode 的用户名，需具有相应的数据访问权限
ain_cluster_ingress_password	AINode 拉取数据的 DataNode 的客户端密码	String	root	与上述用户名对应的密码，确保 AINode 能正常登录 DataNode
ain_cluster_ingress_time_zone	AINode 拉取数据的 DataNode 的客户端时区	String	UTC+8	设定数据处理时的时区，避免因时区差异导致数据时间戳错误
ain_inference_rpc_address	AINode 提供服务与通信的地址，内部服务通讯接口	String	127.0.0.1	其他节点或服务与 AINode 进行通信的地址
ain_inference_rpc_port	AINode 提供服务与通信的端口	String	10810	与上述通信地址对应的端口，需确保该端口未被其他服务占用
ain_system_dir	AINode 元数据存储路径	String	data/AINode/system	存储 AINode 运行过程中的元数据，建议使用绝对路径，避免路径混乱
ain_models_dir	AINode 存储模型文件的路径	String	data/AINode/models	存放注册的机器学习模型文件，同样建议使用绝对路径
ain_thrift_compression_enabled	AINode 是否启用 thrift 的压缩机制	Boolean	0	0 表示不启动压缩机制，1 表示启动压缩机制，启用压缩可减少数据传输量，但会增加一定的 CPU 开销

根据实际的 IoTDB 集群配置和运行需求，修改上述参数。例如，如果 ConfigNode 地址为 192.168.1.100:10710，那么需要将 ain_seed_config_node 参数修改为 192.168.1.100:10710。

2.3.3 导入权重文件

该步骤仅适用于离线环境，在线环境可忽略。在离线环境中，需要联系天谋工作人员获取模型权重文件，然后将其放置到/IOTDB_AINODE_HOME/data/ainode/models/weights/目录下。模型权重文件是机器学习模型正常运行的关键，缺少权重文件会导致模型无法进行推理分析。

2.3.4 启动 AINode

在完成 Seed-ConfigNode 的部署和 AINode 配置项修改后，即可启动 AINode，使其加入 IoTDB 集群。不同操作系统和运行需求对应不同的启动命令：

• Linux 和 MacOS 系统

  • 普通启动命令：

    bash sbin/start-ainode.sh  
    

    该命令会在当前终端启动 AINode，终端关闭后 AINode 也会停止运行，适用于测试和短期使用。
  • 后台启动命令（长期运行推荐）：

    nohup bash sbin/start-ainode.sh  > myout.file 2>& 1 &
    

    nohup 命令用于忽略挂起信号，使 AINode 在后台持续运行；> myout.file 表示将标准输出重定向到 myout.file 文件；2>& 1 表示将标准错误输出也重定向到标准输出，最终都写入 myout.file 文件；最后的 & 表示将命令放入后台执行。使用该命令启动 AINode 后，即使关闭终端，AINode 仍会继续运行。

• Windows 系统

  • 普通启动命令：

    sbin\start-ainode.bat  
    

  • 后台启动命令（长期运行推荐）：

    nohup bash sbin\start-ainode.bat  > myout.file 2>& 1 &
    

    Windows 系统下的启动命令与 Linux 和 MacOS 系统类似，只是脚本文件的路径分隔符不同，Windows 系统使用 \，而 Linux 和 MacOS 系统使用 /。

2.3.5 检测 AINode 节点状态

AINode 启动后会自动加入 IoTDB 集群，可通过在命令行中输入 SQL 语句查询集群状态，确认 AINode 是否成功加入。在 IoTDB 命令行界面输入以下命令：

show cluster

如果查询结果中出现 AINode 节点，且其运行状态为 Running，如下所示，则表示 AINode 成功加入集群：

+------+----------+-------+---------------+------------+-------+-----------+
|NodeID|  NodeType| Status|InternalAddress|InternalPort|Version|  BuildInfo|
+------+----------+-------+---------------+------------+-------+-----------+
|     0|ConfigNode|Running|      127.0.0.1|       10710|UNKNOWN|190e303-dev|
|     1|  DataNode|Running|      127.0.0.1|       10730|UNKNOWN|190e303-dev|
|     2|    AINode|Running|      127.0.0.1|       10810|UNKNOWN|190e303-dev|
+------+----------+-------+---------------+------------+-------+-----------+

2.3.6 停止 AINode

当需要停止正在运行的 AINode 节点时，可执行相应的关闭脚本：

• Linux / MacOS 系统：

  bash sbin/stop-ainode.sh
  

• Windows 系统：

  sbin\stop-ainode.bat
  

停止 AINode 后，再次查询集群状态，会发现 AINode 节点的运行状态变为 UNKNOWN，此时无法使用 AINode 的功能。如果需要重新启动 AINode，需重新执行启动脚本。

2.4 常见问题及解决方案

2.4.1 启动 AINode 时出现找不到 venv 模块的报错

问题原因：使用默认方式启动 AINode 时，会在安装包目录下创建一个 Python 虚拟环境并安装依赖，因此要求系统中安装 venv 模块。虽然 Python 3.10 及以上版本通常会自带 venv 模块，但部分系统自带的 Python 环境可能缺少该模块。

解决方案（二选一）：

1. 在本地安装 venv 模块。以 Ubuntu 系统为例，可通过以下命令安装 Python 3.10 对应的 venv 模块：

   apt-get install python3.10-venv
   

   也可以从 Python 官网下载并安装一个自带 venv 模块的 Python 版本。
2. 在运行启动脚本时，通过 -i 参数指定已有的 Python 解释器路径作为 AINode 的运行环境，这样就无需创建新的虚拟环境。例如：

   bash sbin/start-ainode.sh -i /usr/bin/python3.10
   

   其中 /usr/bin/python3.10 为已有的 Python 解释器路径，需根据实际情况修改。

2.4.2 Python 中的 SSL 模块未正确安装和配置，无法处理 HTTPS 资源

报错信息：WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.

问题原因：Python 处理 HTTPS 资源需要依赖 SSL 模块，当 SSL 模块未正确安装或配置时，会出现该报错。

解决方案：安装 OpenSSL 后重新构建 Python。具体步骤如下：

1. 安装相关依赖包：

   sudo apt-get install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev uuid-dev lzma-dev liblzma-dev
   

   这些依赖包是编译和安装 Python 以及 OpenSSL 所必需的。
2. 配置 Python 编译选项，指定使用 SSL：

   sudo -E ./configure --with-ssl
   

   -E 参数用于保留当前环境变量，确保配置过程中能正确找到相关依赖。
3. 编译并安装 Python：

   make
   sudo make install
   

   编译过程可能需要一定时间，编译完成后执行 sudo make install 命令将 Python 安装到系统中。

需要注意的是，不同 Python 版本对 OpenSSL 版本的兼容性不同，目前 Python 3.6 到 3.9 版本兼容 OpenSSL 1.0.2、1.1.0 和 1.1.1 版本。

2.4.3 pip 版本较低导致 Windows 下出现编译问题

报错信息：error：Microsoft Visual C++ 14.0 or greater is required…

问题原因：该报错通常是由于 pip 版本较低，或者 setuptools 版本不足，导致在安装某些依赖包时需要编译 C++ 代码，但系统中缺少相应的编译环境或工具版本不满足要求。

解决方案：升级 pip 和 setuptools 版本。在 Windows 系统的命令提示符或 PowerShell 中执行以下命令：

./python -m pip install --upgrade pip
./python -m pip install --upgrade setuptools

其中 ./python 为 Python 解释器的路径，需根据实际情况修改。升级完成后，再尝试安装相关依赖包，通常能解决该编译问题。

2.4.4 安装编译 Python

如果系统中没有合适版本的 Python，或者需要重新编译 Python 以解决某些依赖问题，可按照以下步骤进行：

1. 从 Python 官网下载指定版本的 Python 安装包，以 Python 3.10.0 为例：

   wget https://www.python.org/ftp/python/3.10.0/Python-3.10.0.tar.xz
   

   如果系统中没有 wget 工具，可使用 curl 工具或直接在浏览器中下载该安装包。
2. 解压下载的安装包：

   tar Jxf Python-3.10.0.tar.xz
   

   tar Jxf 命令用于解压 .tar.xz 格式的压缩文件。
3. 进入解压后的目录，配置编译选项并指定安装路径：

   cd Python-3.10.0
   ./configure prefix=/usr/local/python3
   

   prefix=/usr/local/python3 指定将 Python 安装到 /usr/local/python3 目录下，可根据实际需求修改安装路径。
4. 编译并安装 Python：

   make
   sudo make install
   

5. 验证 Python 是否安装成功：

   python3 --version
   

   如果输出 Python 3.10.0 等类似版本信息，则表示 Python 安装编译成功。

三、Kubernetes 集群部署 IoTDB

3.1 环境准备

3.1.1 准备 Kubernetes 集群

首先需要确保拥有一个可用的 Kubernetes 集群，建议最低版本为 Kubernetes 1.24。Kubernetes 集群是部署 IoTDB 集群的基础，它提供了容器编排、服务发现、负载均衡、自动扩缩容等功能，能确保 IoTDB 集群的稳定运行和高效管理。如果还没有 Kubernetes 集群，可参考 Kubernetes 官方文档搭建集群。

同时，IoTDB 版本要求不能低于 v1.3.3.2，较低版本的 IoTDB 可能不支持在 Kubernetes 集群中的某些部署和管理功能。

3.1.2 安装 Helm

Helm 是 Kubernetes 的包管理工具，用于简化 Kubernetes 应用的部署和管理。安装 Helm 的步骤请参考 Helm 官网（https://helm.sh/），根据不同的操作系统选择相应的安装方法。安装完成后，可通过以下命令验证 Helm 是否安装成功：

helm version

如果输出 Helm 的版本信息，则表示 Helm 安装成功。

3.2 创建命名空间

命名空间（Namespace）用于在 Kubernetes 集群中隔离不同的应用或环境，避免资源命名冲突。在部署 IoTDB 集群前，建议创建一个专门的命名空间。

3.2.1 创建命名空间

执行以下命令创建名为 iotdb-ns 的命名空间：

kubectl create ns iotdb-ns

注意：在执行该命令之前，需验证 iotdb-ns 命名空间在 Kubernetes 集群中尚未被使用。如果命名空间已存在，创建命令将无法执行，可能导致部署过程中的错误。可通过以下命令查看集群中已有的命名空间：

kubectl get ns

3.2.2 查看命名空间

创建命名空间后，再次执行以下命令查看命名空间列表，确认 iotdb-ns 命名空间已成功创建：

kubectl get ns

在输出结果中，若能看到 iotdb-ns 命名空间，且 STATUS 为 Active，则表示命名空间创建成功。

3.3 创建 PersistentVolume (PV)

PersistentVolume (PV) 是 Kubernetes 集群中的一块持久化存储区域，用于持久化存储 IoTDB 的 ConfigNode 和 DataNode 的数据。每个 ConfigNode 或 DataNode 都需要一个对应的 PV，即有几个节点就要创建几个 PV。例如，1 个 ConfigNode 和 1 个 DataNode 算 2 个节点，需要创建 2 个 PV。

3.3.1 创建 PV 配置文件

以创建 3 个 ConfigNode 和 3 个 DataNode 为例，需要创建 6 个 PV。首先创建一个 pv.yaml 文件，作为 PV 配置的模板，命令如下：

touch pv.yaml

然后将该文件复制六份，分别重命名为 pv01.yaml ～ pv06.yaml，可新建一个文件夹专门存放这些 YAML 文件，以便管理。

pv.yaml 文件的示例内容如下：

# pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: iotdb-pv-01  # PV 的名称，每个 PV 需有唯一的名称，如 pv01.yaml 中为 iotdb-pv-01，pv02.yaml 中为 iotdb-pv-02 等
spec:
  capacity:
    storage: 10Gi  # 存储容量，可根据实际数据存储需求调整，如 20Gi、50Gi 等
  accessModes:  # 访问模式，ReadWriteOnce 表示该 PV 只能被一个节点以读写方式挂载
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain  # 回收策略，Retain 表示当 PV 不再被使用时，保留 PV 及其数据，需要手动清理
  # 存储类名称，如果使用本地静态存储，storageClassName 不用配置；如果使用动态存储，必需设置此项，指定对应的存储类
  storageClassName: local-storage 
  # 根据存储类型添加相应的配置，此处以本地路径存储为例
  hostPath:  # 使用本地路径作为存储后端
    path: /data/k8s-data/iotdb-pv-01  # 本地存储的路径，每个 PV 需对应不同的路径，如 pv01.yaml 中为 /data/k8s-data/iotdb-pv-01，pv02.yaml 中为 /data/k8s-data/iotdb-pv-02 等
    type: DirectoryOrCreate  # 该参数表示如果指定的路径不存在，Kubernetes 会自动创建该目录；如果不配置该参数，则需要手动创建对应的文件夹

修改每个 PV 配置文件（pv01.yaml ～ pv06.yaml）中的 name 和 path 字段，确保每个 PV 的名称和存储路径都是唯一的。

3.3.2 应用 PV 配置

执行以下命令，依次应用每个 PV 配置文件，创建 PV：

kubectl apply -f pv01.yaml
kubectl apply -f pv02.yaml
# ... 依次执行 pv03.yaml 到 pv06.yaml 的应用命令
kubectl apply -f pv06.yaml

每个命令执行成功后，会输出类似 persistentvolume/iotdb-pv-01 created 的信息，表示对应的 PV 创建成功。

3.3.3 查看 PV

应用所有 PV 配置文件后，执行以下命令查看 PV 的创建情况和状态：

kubectl get pv

在输出结果中，会显示每个 PV 的名称、容量、访问模式、回收策略、状态等信息。如果 PV 的 STATUS 为 Available，则表示 PV 已成功创建且处于可用状态，可被后续的 PersistentVolumeClaim (PVC) 绑定。

3.3.4 手动创建文件夹

如果在 PV 配置文件的 hostPath 部分未配置 type: DirectoryOrCreate 参数，则需要在所有 Kubernetes 节点上手动创建对应的存储文件夹。以 pv01.yaml 到 pv06.yaml 对应的路径为例，执行以下命令创建文件夹：

mkdir -p /data/k8s-data/iotdb-pv-01
mkdir -p /data/k8s-data/iotdb-pv-02
# ... 依次创建 pv03.yaml 到 pv06.yaml 对应的文件夹
mkdir -p /data/k8s-data/iotdb-pv-06

mkdir -p 命令用于创建多级目录，如果父目录不存在，会自动创建父目录。

3.4 配置 IoTDB 的 Helm Chart

3.4.1 克隆 IoTDB Kubernetes 部署代码

首先需要获取 IoTDB 的 Helm Chart，可联系天谋工作人员获取相关代码仓库地址。然后使用 git clone 命令克隆代码仓库，例如：

git clone https://gitlab.timecho.com/r-d/db/iotdb-cluster-k8s.git/

如果在克隆过程中遇到类似以下代理问题：

fatal: unable to access 'https://gitlab.timecho.com/r-d/db/iotdb-cluster-k8s.git/': gnutls_handshake() failed: The TLS connection was non-properly terminated.

说明系统配置了代理，需要取消代理设置，执行以下命令：

unset HTTPS_PROXY

取消代理后，重新执行 git clone 命令克隆代码仓库。

3.4.2 修改 YAML 文件

进入克隆下来的代码仓库目录，找到 Helm Chart 相关的配置文件，主要是 values.yaml 文件。该文件用于配置 IoTDB 集群的各项参数，确保使用的 IoTDB 版本不低于 1.3.3.2。

values.yaml 文件的示例内容及说明如下：

nameOverride: "iotdb"  # 覆盖 Chart 中的名称，用于自定义应用的名称前缀
fullnameOverride: "iotdb"  # 完全覆盖应用的名称，软件安装后的名称为该值
image:
  repository: nexus.infra.timecho.com:8143/timecho/iotdb-enterprise  # IoTDB 镜像的仓库地址，需根据实际的镜像仓库修改
  pullPolicy: IfNotPresent  # 镜像拉取策略，IfNotPresent 表示如果节点上已存在该镜像，则不再拉取；Always 表示每次都拉取最新的镜像
  tag: 1.3.3.2-standalone  # 镜像的标签，即 IoTDB 的版本，需确保版本不低于 1.3.3.2
storage:
  # 存储类名称，如果使用本地静态存储，storageClassName 不用配置；如果使用动态存储，必需设置此项，指定对应的存储类
  className: local-storage
datanode:
  name: datanode  # DataNode 的名称前缀
  nodeCount: 3  # DataNode 的节点数量，可根据业务需求调整，如 2、4 等
  enableRestService: true  # 是否启用 Rest 服务，true 表示启用，false 表示禁用
  storageCapacity: 10Gi  # DataNode 的可用存储空间大小，需与前面创建的 PV 容量匹配
  resources:  # DataNode 的资源限制和请求，用于控制 DataNode 对 CPU 和内存的使用
    requests:  # 资源请求，即 DataNode 启动时至少需要的资源
      memory: 2Gi  # 内存请求大小，可根据实际需求调整
      cpu: 1000m  # CPU 请求大小，1000m 表示 1 个 CPU 核心
    limits:  # 资源限制，即 DataNode 最多可使用的资源
      memory: 4Gi  # 内存限制大小，防止 DataNode 过度使用内存导致集群不稳定
      cpu: 1000m  # CPU 限制大小
confignode:
  name: confignode  # ConfigNode 的名称前缀
  nodeCount: 3  # ConfigNode 的节点数量，通常建议配置 3 个或更多节点，以实现高可用
  storageCapacity: 10Gi  # ConfigNode 的可用存储空间大小，需与前面创建的 PV 容量匹配
  resources:  # ConfigNode 的资源限制和请求
    requests:
      memory: 512Mi  # ConfigNode 的内存请求大小，通常比 DataNode 小
      cpu: 1000m  # ConfigNode 的 CPU 请求大小
    limits:
      memory: 1024Mi  # ConfigNode 的内存限制大小
      cpu: 2000m  # ConfigNode 的 CPU 限制大小
  configNodeConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus  # ConfigNode 使用的共识协议类，此处为 Ratis 共识协议
  schemaReplicationFactor: 3  #  schema 的副本数，即 schema 数据在 ConfigNode 集群中的复制份数，通常与 ConfigNode 节点数量一致
  schemaRegionConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus  # schema 区域使用的共识协议类
  dataReplicationFactor: 2  # 数据的副本数，即数据在 DataNode 集群中的复制份数，可根据数据可靠性需求调整
  dataRegionConsensusProtocolClass: org.apache.iotdb.consensus.iot.IoTConsensus  # 数据区域使用的共识协议类

根据实际的 Kubernetes 集群环境、存储需求和资源情况，修改上述 values.yaml 文件中的参数。例如，如果需要增加 DataNode 的节点数量，可将 datanode.nodeCount 修改为 4；如果集群资源充足，可适当增加 resources.requests 和 resources.limits 的值，以提高 IoTDB 集群的性能。

3.5 配置私库信息或预先拉取镜像

在 Kubernetes 上部署 IoTDB 集群前，需要确保集群能够获取到 IoTDB 镜像。有两种方案可供选择：从私有仓库拉取镜像，或提前将镜像导入到 containerd 中。

3.5.1 方案一：从私有仓库拉取镜像

如果 IoTDB 镜像存储在私有仓库中，需要在 Kubernetes 集群中创建一个 secret，用于存储私有仓库的账号、密码等认证信息，使 Kubernetes 能够访问私有仓库并拉取镜像。

3.5.1.1 创建 secret

执行以下命令创建 secret，其中“xxxxxx”需要替换为实际的 IoTDB 私有仓库的账号、密码和邮箱：

kubectl create secret docker-registry timecho-nexus \
  --docker-server='nexus.infra.timecho.com:8143' \
  --docker-username='xxxxxx' \
  --docker-password='xxxxxx' \
  --docker-email='xxxxxx' \
  -n iotdb-ns

• docker-registry：表示创建的是用于 Docker 仓库认证的 secret。
• timecho-nexus：是 secret 的名称，可根据实际情况修改。
• --docker-server：指定私有仓库的地址。
• --docker-username：私有仓库的账号。
• --docker-password：私有仓库的密码。
• --docker-email：用户的邮箱地址。
• -n iotdb-ns：指定将 secret 创建在 iotdb-ns 命名空间下，与 IoTDB 集群的部署命名空间保持一致。

创建 secret 后，可通过以下命令查看 secret：

kubectl get secret timecho-nexus -n iotdb-ns

也可将 secret 输出为 YAML 格式查看详细信息：

kubectl get secret timecho-nexus --output=yaml -n iotdb-ns

还可以解密 secret 中的 dockerconfigjson 字段，查看实际的认证信息（注意：解密后的信息包含敏感数据，需妥善保管）：

kubectl get secret timecho-nexus --output="jsonpath={.data.\.dockerconfigjson}" -n iotdb-ns | base64 --decode

3.5.1.2 将 secret 作为 patch 加载到命名空间

创建 secret 后，需要将其关联到 iotdb-ns 命名空间的默认服务账号（serviceaccount）上，使该命名空间下的 Pod 能够使用该 secret 拉取私有仓库的镜像。执行以下命令：

kubectl patch serviceaccount default -n iotdb-ns -p '{"imagePullSecrets": [{"name": "timecho-nexus"}]}'

该命令通过 patch 操作，为 iotdb-ns 命名空间下的 default 服务账号添加了 imagePullSecrets 配置，指定使用名为 timecho-nexus 的 secret 进行镜像拉取认证。

执行以下命令查看命名空间的服务账号信息，确认 patch 操作是否成功：

kubectl get serviceaccounts -n iotdb-ns -o yaml

在输出结果中，如果 default 服务账号的 imagePullSecrets 字段包含 timecho-nexus，则表示 patch 操作成功。

3.5.2 方案二：导入镜像

该方案适用于客户无法连接私有仓库的场景，需要提前将 IoTDB 镜像下载到本地，然后导入到 Kubernetes 集群的 containerd 中。该步骤通常需要联系公司实施同事辅助准备镜像文件。

3.5.2.1 拉取并导出镜像

首先，在能够访问私有仓库的机器上，使用 ctr 命令拉取 IoTDB 镜像（需替换“xxxxxxx”为实际的私有仓库账号和密码）：

ctr images pull --user xxxxxxxx nexus.infra.timecho.com:8143/timecho/iotdb-enterprise:1.3.3.2-standalone

拉取成功后，执行以下命令查看已拉取的镜像：

ctr images ls 

然后，将该镜像导出为 tar 包文件，以便传输到 Kubernetes 集群节点：

ctr images export iotdb-enterprise:1.3.3.2-standalone.tar nexus.infra.timecho.com:8143/timecho/iotdb-enterprise:1.3.3.2-standalone

iotdb-enterprise:1.3.3.2-standalone.tar 是导出的 tar 包文件名，可根据实际情况修改。

3.5.2.2 导入镜像到 Kubernetes 集群

将导出的镜像 tar 包文件传输到 Kubernetes 集群的所有节点上，然后在每个节点上执行以下命令，将镜像导入到 containerd 的 k8s.io 命名空间下（注意：k8s.io 是示例环境中 Kubernetes 使用的 containerd 命名空间，导入到其他命名空间可能无法被 Kubernetes 识别和使用）：

ctr -n k8s.io images import iotdb-enterprise:1.3.3.2-standalone.tar

导入完成后，执行以下命令查看镜像是否导入成功：

ctr --namespace k8s.io images list | grep 1.3.3.2

如果输出包含 IoTDB 镜像的相关信息，则表示镜像导入成功。

3.6 安装 IoTDB

3.6.1 执行安装命令

进入克隆下来的 IoTDB Kubernetes 部署代码仓库的 helm 目录：

cd iotdb-cluster-k8s/helm

然后执行以下命令安装 IoTDB 集群：

helm install iotdb ./ -n iotdb-ns

• iotdb：是安装后的 release 名称，可根据实际情况修改。
• ./：指定 Helm Chart 的目录为当前目录。
• -n iotdb-ns：指定在 iotdb-ns 命名空间下安装 IoTDB 集群。

安装命令执行成功后，会输出类似以下的信息，提示安装成功以及后续的操作建议：

NAME: iotdb
LAST DEPLOYED: [部署时间]
NAMESPACE: iotdb-ns
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
...（后续操作建议信息）

3.6.2 查看 Helm 安装列表

执行以下命令查看在 iotdb-ns 命名空间下通过 Helm 安装的应用列表，确认 IoTDB 是否安装成功：

helm list -n iotdb-ns

在输出结果中，如果能看到名称为 iotdb 的 release，且 STATUS 为 deployed，则表示 IoTDB 安装成功。

3.6.3 查看 Pods 状态

执行以下命令查看 iotdb-ns 命名空间下的 Pods 状态，了解 IoTDB 集群的部署情况：

kubectl get pods -n iotdb-ns -o wide

执行该命令后，如果输出结果中包含带有 confignode 和 datanode 标识的各 3 个 Pods（总共 6 个 Pods），则表明安装基本成功。需要注意的是，在安装初期，并非所有 Pods 都能立即处于 Running 状态，未激活的 DataNode 可能会持续重启，但在后续的激活步骤完成后，这些 DataNode 将恢复正常运行状态。

3.6.4 故障排除

如果在安装过程中出现 Pods 状态异常（如 Error、CrashLoopBackOff 等），可通过以下命令排查故障：

1. 查看 Kubernetes 集群的事件日志，了解部署过程中发生的事件和可能的错误信息：

   kubectl get events -n iotdb-ns 
   # 或实时查看事件日志
   watch kubectl get events -n iotdb-ns
   

2. 获取异常 Pod 的详细信息，包括 Pod 的配置、事件、容器状态等，有助于定位故障原因：

   kubectl describe pod confignode-0 -n iotdb-ns
   kubectl describe pod datanode-0 -n iotdb-ns
   

   将 confignode-0 和 datanode-0 替换为实际状态异常的 Pod 名称。
3. 查看 Pod 的日志，了解应用在运行过程中输出的错误信息：

   kubectl logs -n iotdb-ns confignode-0 -f
   

   -f 参数表示实时跟踪日志输出，便于观察应用的运行状态和错误信息。

3.7 激活 IoTDB

安装 IoTDB 集群后，需要对其进行激活才能正常使用。以下提供三种激活方案，可根据实际情况选择。

3.7.1 方案一：直接在 Pod 中激活（最快捷）

执行以下命令，直接在每个 ConfigNode Pod 中执行激活脚本：

kubectl exec -it -n iotdb-ns confignode-0 -- /iotdb/sbin/start-activate.sh
kubectl exec -it -n iotdb-ns confignode-1 -- /iotdb/sbin/start-activate.sh
kubectl exec -it -n iotdb-ns confignode-2 -- /iotdb/sbin/start-activate.sh

• kubectl exec -it：用于在运行的 Pod 中执行交互式命令。
• -n iotdb-ns：指定命名空间为 iotdb-ns。
• confignode-0、confignode-1、confignode-2：是 ConfigNode 的 Pod 名称。
• -- /iotdb/sbin/start-activate.sh：表示在 Pod 中执行 /iotdb/sbin/start-activate.sh 激活脚本。

执行激活脚本后，会在终端输出机器码，将该机器码提供给相关人员获取激活码，然后按照提示输入激活码完成激活。

3.7.2 方案二：进入 ConfigNode 的容器中激活

首先，进入 ConfigNode 的容器内部：

kubectl exec -it -n iotdb-ns confignode-0 -- /bin/bash

然后，切换到激活脚本所在的目录：

cd /iotdb/sbin

执行激活脚本：

/bin/bash start-activate.sh

同样，会输出机器码，获取激活码后输入完成激活。激活完成后，执行以下命令退出容器：

exit

按照上述步骤，依次对 confignode-1 和 confignode-2 进行激活。

3.7.3 方案三：手动激活

1. 查看 ConfigNode 的详细信息，确定其所在节点和相关路径：

   kubectl describe pod confignode-0 -n iotdb-ns | grep -e "Node:" -e "Path:"
   

   输出结果示例：

   Node:          a87/172.20.31.87
   Path:          /data/k8s-data/env/confignode/.env
   

   其中，Node 字段表示 ConfigNode 所在的 Kubernetes 节点名称和 IP 地址，Path 字段表示相关配置文件的路径。

   如果需要查看多个 ConfigNode 的信息，可执行以下循环命令：

   for i in {0..2}; do echo confignode-$i;kubectl describe pod confignode-${i} -n iotdb-ns | grep -e "Node:" -e "Path:"; echo "----"; done
   

2. 查看 PVC（PersistentVolumeClaim），找到 ConfigNode 对应的 Volume，确定存储路径：

   kubectl get pvc -n iotdb-ns | grep "confignode-0"
   

   输出结果示例：

   map-confignode-confignode-0   Bound    iotdb-pv-04   10Gi       RWO            local-storage   <unset>                 8h
   

   其中，iotdb-pv-04 是与 confignode-0 绑定的 PV 名称。

3. 查看对应 PV 的详细信息，确定物理目录的位置：

   kubectl describe pv iotdb-pv-04 | grep "Path:"
   

   输出结果示例：

   Path:          /data/k8s-data/iotdb-pv-04
   

   该路径是 PV 在 Kubernetes 节点上的实际物理存储路径。

4. 登录到 ConfigNode 所在的 Kubernetes 节点，进入上述物理目录，找到 system-info 文件。该文件包含了机器码信息，将其提供给相关人员获取激活码。

5. 在同一目录下新建 license 文件，将获取到的激活码写入该文件，完成激活。

按照上述步骤，依次对 confignode-1 和 confignode-2 进行手动激活。

3.8 验证 IoTDB

激活 IoTDB 集群后，需要对其进行验证，确保集群能够正常运行和提供服务。

3.8.1 查看 Pods 状态

执行以下命令查看 iotdb-ns 命名空间内所有 Pods 的状态、IP 地址、所在节点等信息：

kubectl get pods -n iotdb-ns -o wide

输出结果示例：

NAME           READY   STATUS    RESTARTS         AGE   IP             NODE   NOMINATED NODE   READINESS GATES
confignode-0   1/1     Running   0                75m   10.20.187.14   a87    <none>           <none>
confignode-1   1/1     Running   0                75m   10.20.191.75   a88    <none>           <none>
confignode-2   1/1     Running   0                75m   10.20.187.16   a87    <none>           <none>
datanode-0     1/1     Running   10 (5m54s ago)   75m   10.20.191.74   a88    <none>           <none>
datanode-1     1/1     Running   10 (5m42s ago)   75m   10.20.187.15   a87    <none>           <none>
datanode-2     1/1     Running   10 (5m55s ago)   75m   10.20.191.76   a88    <none>           <none>

如果所有 Pods 的 STATUS 都为 Running，且 READY 为 1/1，则表示 IoTDB 集群的 Pods 运行正常。

3.8.2 查看端口映射情况

执行以下命令查看 iotdb-ns 命名空间内的服务（Service）及其端口映射情况：

kubectl get svc -n iotdb-ns

输出结果示例：

NAME             TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
confignode-svc   NodePort       10.10.226.151   <none>        80:31026/TCP     7d8h
datanode-svc     NodePort       10.10.194.225   <none>        6667:31563/TCP   7d8h
jdbc-balancer    LoadBalancer   10.10.191.209   <pending>     6667:31895/TCP   7d8h

• confignode-svc：是 ConfigNode 的服务，类型为 NodePort，将 ConfigNode 的 80 端口映射到集群节点的 31026 端口。
• datanode-svc：是 DataNode 的服务，类型为 NodePort，将 DataNode 的 6667 端口映射到集群节点的 31563 端口。
• jdbc-balancer：是用于 JDBC 连接的负载均衡服务，类型为 LoadBalancer，将 6667 端口映射到集群节点的 31895 端口。在某些环境中，EXTERNAL-IP 可能会显示为 ，这通常不影响集群内部的访问。

3.8.3 使用 CLI 验证集群状态

在任意能够访问 Kubernetes 集群节点的服务器上，使用 IoTDB 提供的 CLI（命令行界面）脚本连接 IoTDB 集群，验证集群状态。CLI 脚本通常包含在 IoTDB 的安装包中，或可从相关渠道获取。

执行以下命令启动 CLI 并连接到 IoTDB 集群（端口为 jdbc-balancer 服务映射的端口，服务器为 Kubernetes 任意节点的 IP 地址）：

start-cli.sh -h 172.20.31.86 -p 31895
start-cli.sh -h 172.20.31.87 -p 31895
start-cli.sh -h 172.20.31.88 -p 31895

其中，172.20.31.86、172.20.31.87、172.20.31.88 是 Kubernetes 集群节点的 IP 地址，31895 是 jdbc-balancer 服务映射的端口。

连接成功后，可在 CLI 中执行一些简单的 SQL 命令，如查看数据库中的时间序列、插入测试数据、查询数据等，验证 IoTDB 集群是否能够正常提供数据存储和查询服务。例如：

-- 查看所有时间序列
show timeseries;
-- 创建时间序列
create timeseries root.sg1.d1.s1 with datatype=FLOAT, encoding=RLE;
-- 插入数据
insert into root.sg1.d1(timestamp, s1) values(1620000000000, 10.5);
-- 查询数据
select s1 from root.sg1.d1 where time >= 1620000000000 and time <= 1620000000000;

如果能够正常执行这些命令并得到预期的结果，则表示 IoTDB 集群验证通过，能够正常运行。

3.9 扩容 IoTDB 集群

随着业务数据量的增长，可能需要对 IoTDB 集群进行扩容，增加 ConfigNode 或 DataNode 的节点数量，以提高集群的存储容量和处理能力。

3.9.1 新增 PV

在扩容 ConfigNode 或 DataNode 之前，需要先新增相应数量的 PV，确保有足够的持久化存储资源。新增 PV 的步骤与前面创建 PV 的步骤类似：

1. 创建新的 PV 配置文件（如 pv07.yaml、pv08.yaml 等），修改 name 和 path 字段，确保与已有的 PV 不冲突。
2. 应用 PV 配置文件，创建 PV：

   kubectl apply -f pv07.yaml
   kubectl apply -f pv08.yaml
   # ... 新增其他 PV 的应用命令
   

3. 如果未配置 type: DirectoryOrCreate 参数，需手动在所有 Kubernetes 节点上创建对应的存储文件夹。

注意：DataNode 重启后可能无法加入集群，其原因可能是配置了静态存储的 hostPath 模式，并通过脚本修改了 iotdb-system.properties 文件，将 dn_data_dirs 设为 /iotdb6/iotdb_data,/iotdb7/iotdb_data，但未将默认存储路径 /iotdb/data 进行外挂，导致重启时数据丢失。解决方案是将 /iotdb/data 目录也进行外挂操作，且 ConfigNode 和 DataNode 均需如此设置，以确保数据完整性和集群稳定性。

3.9.2 扩容 ConfigNode

以将 3 个 ConfigNode 扩容为 4 个 ConfigNode 为例，扩容步骤如下：

1. 进入 IoTDB Kubernetes 部署代码仓库的 helm 目录：

   cd iotdb-cluster-k8s/helm
   

2. 修改 values.yaml 文件，将 confignode.nodeCount 的值从 3 改为 4：

   confignode:
     nodeCount: 4  # 将节点数量从 3 改为 4
     # 其他参数保持不变
   

3. 执行以下命令，使用 helm upgrade 命令更新 IoTDB 集群的配置，实现 ConfigNode 的扩容：

   helm upgrade iotdb . -n iotdb-ns
   

   iotdb 是之前安装 IoTDB 时的 release 名称，. 表示使用当前目录下的 Helm Chart，-n iotdb-ns 表示在 iotdb-ns 命名空间下执行升级操作。

3.9.3 扩容 DataNode

以将 3 个 DataNode 扩容为 4 个 DataNode 为例，扩容步骤与 ConfigNode 类似：

1. 进入 helm 目录：

   cd iotdb-cluster-k8s/helm
   

2. 修改 values.yaml 文件，将 datanode.nodeCount 的值从 3 改为 4：

   datanode:
     nodeCount: 4  # 将节点数量从 3 改为 4
     # 其他参数保持不变
   

3. 执行 helm upgrade 命令更新集群配置，实现 DataNode 的扩容：

   helm upgrade iotdb . -n iotdb-ns
   

3.9.4 验证扩容后的 IoTDB 状态

扩容完成后，执行以下命令查看 iotdb-ns 命名空间下的 Pods 状态，确认新增的 ConfigNode 或 DataNode 是否成功创建并正常运行：

kubectl get pods -n iotdb-ns -o wide

输出结果示例（新增了 datanode-3）：

NAME           READY   STATUS    RESTARTS         AGE   IP             NODE   NOMINATED NODE   READINESS GATES
confignode-0   1/1     Running   0                75m   10.20.187.14   a87    <none>           <none>
confignode-1   1/1     Running   0                75m   10.20.191.75   a88    <none>           <none>
confignode-2   1/1     Running   0                75m   10.20.187.16   a87    <none>           <none>
confignode-3   1/1     Running   0                10m   10.20.191.77   a88    <none>           <none>  # 新增的 ConfigNode
datanode-0     1/1     Running   10 (5m54s ago)   75m   10.20.191.74   a88    <none>           <none>
datanode-1     1/1     Running   10 (5m42s ago)   75m   10.20.187.15   a87    <none>           <none>
datanode-2     1/1     Running   10 (5m55s ago)   75m   10.20.191.76   a88    <none>           <none>
datanode-3     1/1     Running   0                10m   10.20.187.17   a87    <none>           <none>  # 新增的 DataNode

如果新增的 ConfigNode 和 DataNode 的 STATUS 为 Running，且 READY 为 1/1，则表示扩容成功。同时，可再次使用 CLI 连接到 IoTDB 集群，执行一些数据操作命令，验证扩容后的集群是否能够正常提供服务。

四、总结

本文详细介绍了 IoTDB 的两种部署方案：AINode 独立部署和 Kubernetes 集群部署。AINode 独立部署适用于对时序数据进行机器学习分析的场景，部署过程相对简单，只需准备好相应的环境和安装包，按照步骤进行安装、配置和启动即可。Kubernetes 集群部署则适用于大规模、高可用的 IoTDB 集群部署场景，通过 Kubernetes 的容器编排和管理能力，实现 IoTDB 集群的自动化部署、运维和扩容，确保集群的稳定运行和高效管理。

在实际部署过程中，需根据具体的业务需求、数据量大小、可用资源等因素，选择合适的部署方案。同时，要注意环境准备、配置参数修改、故障排查等关键环节，确保部署过程顺利进行，以及部署后的 IoTDB 集群能够正常提供服务。希望本文能够为读者提供详细、实用的 IoTDB 部署指导，帮助读者成功部署 IoTDB 相关组件和集群。

🌐 附：IoTDB的各大版本

📄 Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析 ，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。

版本	IoTDB 二进制包	IoTDB 源代码	发布说明
2.0.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
1.3.5	- All-in-one - AINode - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes
0.13.4	- All-in-one - Grafana 连接器 - Grafana 插件 - SHA512 - ASC	- 源代码 - SHA512 - ASC	release notes

✨ 去获取：https://archive.apache.org/dist/iotdb/

联系博主

    xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为 xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。

    亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。

     愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。

    至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。

---

     💞 关注博主 🌀 带你实现畅游前后端！

     🏰 大屏可视化 🌀 带你体验酷炫大屏！

     💯 神秘个人简介 🌀 带你体验不一样得介绍！

     🥇 从零到一学习Python 🌀 带你玩转Python技术流！

     🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！

     💦 注：本文撰写于CSDN平台,作者：xcLeigh（所有权归作者所有） ，https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。

---

     📣 亲，码字不易，动动小手，欢迎 点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌