Apache IoTDB 部署全指南：AINode 独立部署与 Kubernetes 集群部署
IoTDB（Internet of Things Database）作为一款专为时间序列数据设计的数据库，在工业物联网、智能监控等领域应用广泛。随着业务需求的不断发展，仅依靠 ConfigNode 和 DataNode 已难以满足复杂的时序数据机器学习分析需求，AINode 应运而生，为 IoTDB 扩展了机器学习分析能力。同时，在大规模部署场景下，Kubernetes 凭借其强大的容器编排和管理能力，成为 IoTDB 集群部署的理想选择。
一、引言
IoTDB 是一款专为时间序列数据设计的数据库。AINode 作为 IoTDB 的第三种内生节点，通过与 IoTDB 集群的 DataNode、ConfigNode 交互，扩展了对时间序列进行机器学习分析的能力。本文详细介绍 IoTDB 的 AINode 独立部署和 Kubernetes 集群部署方案。
二、AINode 独立部署
2.1 AINode 简介
AINode 是 IoTDB 在 ConfigNode、DataNode 之后提供的第三种内生节点，支持从外部引入已有机器学习模型进行注册，使用注册的模型在指定时序数据上通过简单 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。
- Python 环境：Python 版本需在 3.9~3.12 之间，且必须带有 pip 和 venv 工具。
可通过以下命令查看 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 集群 |
| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 | 需根据实际 ConfigNode 地址修改 |
| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 | 需填写实际 DataNode 的 rpc 地址 |
| ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 | 需与 DataNode 的配置保持一致 |
| ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root | 需具有相应的数据访问权限 |
| 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 | 建议使用绝对路径 |
| ain_models_dir | AINode 存储模型文件的路径 | String | data/AINode/models | 建议使用绝对路径 |
| ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制 | Boolean | 0 | 0 表示不启动，1 表示启动 |
根据实际的 IoTDB 集群配置和运行需求，修改上述参数。
2.3.3 导入权重文件
该步骤仅适用于离线环境。在离线环境中，需要联系官方工作人员获取模型权重文件，然后将其放置到 /IOTDB_AINODE_HOME/data/ainode/models/weights/目录下。模型权重文件是机器学习模型正常运行的关键。
2.3.4 启动 AINode
在完成 Seed-ConfigNode 的部署和 AINode 配置项修改后，即可启动 AINode。
Linux 和 MacOS 系统
后台启动命令（长期运行推荐）：
nohup bash sbin/start-ainode.sh > myout.file 2>&1 &
普通启动命令：
bash sbin/start-ainode.sh
Windows 系统
后台启动命令（长期运行推荐）：
nohup bash sbin\start-ainode.bat > myout.file 2>&1 &
普通启动命令：
sbin\start-ainode.bat
2.3.5 检测 AINode 节点状态
AINode 启动后会自动加入 IoTDB 集群，可通过在命令行中输入 SQL 语句查询集群状态：
show cluster
如果查询结果中出现 AINode 节点，且其运行状态为 Running，则表示 AINode 成功加入集群。
2.3.6 停止 AINode
当需要停止正在运行的 AINode 节点时，可执行相应的关闭脚本：
Windows 系统：
sbin\stop-ainode.bat
Linux / MacOS 系统：
bash sbin/stop-ainode.sh
2.4 常见问题及解决方案
2.4.1 启动 AINode 时出现找不到 venv 模块的报错
问题原因：部分系统自带的 Python 环境可能缺少 venv 模块。
解决方案：
- 在运行启动脚本时，通过
-i参数指定已有的 Python 解释器路径。bash sbin/start-ainode.sh -i /usr/bin/python3.10 - 在本地安装 venv 模块。以 Ubuntu 系统为例：
apt-get install python3.10-venv
2.4.2 Python 中的 SSL 模块未正确安装和配置
报错信息：WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
解决方案：安装 OpenSSL 后重新构建 Python。
- 编译并安装 Python：
make && sudo make install - 配置 Python 编译选项，指定使用 SSL：
sudo -E ./configure --with-ssl - 安装相关依赖包：
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
2.4.3 pip 版本较低导致 Windows 下出现编译问题
报错信息：error：Microsoft Visual C++ 14.0 or greater is required…
解决方案：升级 pip 和 setuptools 版本。
./python -m pip install --upgrade pip
./python -m pip install --upgrade setuptools
2.4.4 安装编译 Python
如果系统中没有合适版本的 Python，或者需要重新编译 Python 以解决某些依赖问题，可按照以下步骤进行：
- 验证 Python 是否安装成功：
python3 --version - 解压下载的安装包：
tar -Jxf Python-3.10.0.tar.xz - 进入解压后的目录，配置编译选项并指定安装路径：
cd Python-3.10.0 ./configure prefix=/usr/local/python3 - 编译并安装 Python：
make && sudo make install
三、Kubernetes 集群部署 IoTDB
3.1 环境准备
3.1.1 准备 Kubernetes 集群
首先需要确保拥有一个可用的 Kubernetes 集群，建议最低版本为 Kubernetes 1.24。IoTDB 版本要求不能低于 v1.3.3.2。
3.1.2 安装 Helm
Helm 是 Kubernetes 的包管理工具。安装完成后，可通过以下命令验证 Helm 是否安装成功：
helm version
3.2 创建命名空间
3.2.1 创建命名空间
执行以下命令创建名为 iotdb-ns 的命名空间：
kubectl create ns iotdb-ns
3.2.2 查看命名空间
kubectl get ns
3.3 创建 PersistentVolume (PV)
每个 ConfigNode 或 DataNode 都需要一个对应的 PV。
3.3.1 创建 PV 配置文件
以创建 3 个 ConfigNode 和 3 个 DataNode 为例，需要创建 6 个 PV。pv.yaml 文件的示例内容如下：
# pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
name: iotdb-pv-01
spec:
capacity:
storage: 10Gi
accessModes:
- ReadWriteOnce
persistentVolumeReclaimPolicy: Retain
storageClassName: local-storage
hostPath:
path: /data/k8s-data/iotdb-pv-01
type: DirectoryOrCreate
修改每个 PV 配置文件中的 name 和 path 字段，确保唯一性。
3.3.2 应用 PV 配置
kubectl apply -f pv01.yaml
kubectl apply -f pv02.yaml
# ... 依次执行 pv03.yaml 到 pv06.yaml
kubectl apply -f pv06.yaml
3.3.3 查看 PV
kubectl get pv
3.3.4 手动创建文件夹
如果未配置 type: DirectoryOrCreate 参数，则需要在所有 Kubernetes 节点上手动创建对应的存储文件夹。
mkdir -p /data/k8s-data/iotdb-pv-01
mkdir -p /data/k8s-data/iotdb-pv-02
# ... 依次创建
3.4 配置 IoTDB 的 Helm Chart
3.4.1 克隆 IoTDB Kubernetes 部署代码
git clone https://gitlab.timecho.com/r-d/db/iotdb-cluster-k8s.git/
如果遇到代理问题，取消代理设置：
unset HTTPS_PROXY
3.4.2 修改 YAML 文件
找到 values.yaml 文件，修改各项参数。示例内容如下：
nameOverride: "iotdb"
fullnameOverride: "iotdb"
image:
repository: nexus.infra.timecho.com:8143/timecho/iotdb-enterprise
pullPolicy: IfNotPresent
tag: 1.3.3.2-standalone
storage:
className: local-storage
datanode:
name: datanode
nodeCount: 3
enableRestService: true
storageCapacity: 10Gi
resources:
requests:
memory: 2Gi
cpu: 1000m
limits:
memory: 4Gi
cpu: 1000m
confignode:
name: confignode
nodeCount: 3
storageCapacity: 10Gi
resources:
requests:
memory: 512Mi
cpu: 1000m
limits:
memory: 1024Mi
cpu: 2000m
configNodeConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus
schemaReplicationFactor: 3
schemaRegionConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus
dataReplicationFactor: 2
dataRegionConsensusProtocolClass: org.apache.iotdb.consensus.iot.IoTConsensus
3.5 配置私库信息或预先拉取镜像
3.5.1 方案一：从私有仓库拉取镜像
3.5.1.1 创建 secret
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
3.5.1.2 将 secret 作为 patch 加载到命名空间
kubectl patch serviceaccount default -n iotdb-ns -p '{"imagePullSecrets": [{"name": "timecho-nexus"}]}'
3.5.2 方案二：导入镜像
3.5.2.1 拉取并导出镜像
ctr images pull --user xxxxxxxx nexus.infra.timecho.com:8143/timecho/iotdb-enterprise:1.3.3.2-standalone
ctr images export iotdb-enterprise:1.3.3.2-standalone.tar nexus.infra.timecho.com:8143/timecho/iotdb-enterprise:1.3.3.2-standalone
3.5.2.2 导入镜像到 Kubernetes 集群
ctr -n k8s.io images import iotdb-enterprise:1.3.3.2-standalone.tar
3.6 安装 IoTDB
3.6.1 执行安装命令
cd iotdb-cluster-k8s/helm
helm install iotdb ./ -n iotdb-ns
3.6.2 查看 Helm 安装列表
helm list -n iotdb-ns
3.6.3 查看 Pods 状态
kubectl get pods -n iotdb-ns -o wide
3.6.4 故障排除
查看 Pod 的日志：
kubectl logs -n iotdb-ns confignode-0 -f
获取异常 Pod 的详细信息：
kubectl describe pod confignode-0 -n iotdb-ns
kubectl describe pod datanode-0 -n iotdb-ns
查看 Kubernetes 集群的事件日志：
kubectl get events -n iotdb-ns
3.7 激活 IoTDB
3.7.1 方案一：直接在 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
3.7.2 方案二：进入 ConfigNode 的容器中激活
kubectl exec -it -n iotdb-ns confignode-0 -- /bin/bash
cd /iotdb/sbin
/bin/bash start-activate.sh
exit
3.7.3 方案三：手动激活
- 登录到 ConfigNode 所在的 Kubernetes 节点，找到 system-info 文件。
- 在同一目录下新建 license 文件，将获取到的激活码写入该文件。
查看对应 PV 的详细信息，确定物理目录的位置：
kubectl describe pv iotdb-pv-04 | grep "Path:"
查看 PVC：
kubectl get pvc -n iotdb-ns | grep "confignode-0"
查看 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
3.8 验证 IoTDB
3.8.1 查看 Pods 状态
kubectl get pods -n iotdb-ns -o wide
3.8.2 查看端口映射情况
kubectl get svc -n iotdb-ns
3.8.3 使用 CLI 验证集群状态
start-cli.sh -h 172.20.31.86 -p 31895
连接成功后，可在 CLI 中执行 SQL 命令：
-- 查看所有时间序列
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;
3.9 扩容 IoTDB 集群
3.9.1 新增 PV
创建新的 PV 配置文件，应用 PV 配置文件。
3.9.2 扩容 ConfigNode
修改 values.yaml 文件，将 confignode.nodeCount 的值从 3 改为 4，然后执行 helm upgrade。
helm upgrade iotdb . -n iotdb-ns
3.9.3 扩容 DataNode
修改 values.yaml 文件，将 datanode.nodeCount 的值从 3 改为 4，然后执行 helm upgrade。
3.9.4 验证扩容后的 IoTDB 状态
kubectl get pods -n iotdb-ns -o wide
四、总结
本文详细介绍了 IoTDB 的两种部署方案：AINode 独立部署和 Kubernetes 集群部署。AINode 独立部署适用于对时序数据进行机器学习分析的场景，部署过程相对简单。Kubernetes 集群部署则适用于大规模、高可用的 IoTDB 集群部署场景，通过 Kubernetes 的容器编排和管理能力，实现 IoTDB 集群的自动化部署、运维和扩容。
在实际部署过程中，需根据具体的业务需求、数据量大小、可用资源等因素，选择合适的部署方案。同时，要注意环境准备、配置参数修改、故障排查等关键环节，确保部署过程顺利进行。
附：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 |