云原生时代时序数据平台构建实战：从Kubernetes部署Apache IoTDB集群到TimechoDB国产化应用全解析

云原生时代时序数据平台构建实战：从Kubernetes部署Apache IoTDB集群到TimechoDB国产化应用全解析

前言

随着物联网设备规模的指数级增长，传感器产生的海量时序数据对传统数据库的性能、可扩展性与成本控制提出了更高要求。Apache IoTDB 作为专为物联网场景设计的时序数据库，凭借高压缩比、百万级写入能力及毫秒级查询性能，成为物联网数据存储与分析的核心基础。本文将从 IoTDB 的核心特性 出发，深入讲解其在 Kubernetes 环境中的部署实践、CRUD 操作示例，并延伸至 TimechoDB 的国产化增强能力，帮助读者全面掌握从单节点到云原生集群的 IoTDB 实战部署与应用方法，为构建高效、可扩展的时序数据平台提供系统参考。

Apache IoTDB 核心特性与价值

Apache IoTDB 专为物联网场景打造的高性能轻量级时序数据库，以 "设备 - 测点" 原生数据模型贴合物理设备与传感器关系，通过高压缩算法、百万级并发写入能力和毫秒级查询响应优化海量时序数据存储成本与处理效率，同时支持边缘轻量部署、云端集群扩展及边缘 - 云端协同，为工业物联网、智能城市、车联网等场景提供全生命周期的数据存储、查询与分析解决方案

✅物联网原生优化：采用 "设备 - 测点" 数据模型，完美映射物理设备与传感器关系，配合标签机制支持多维度分析，贴合物联网实际业务场景

✅极致性能表现：通过特殊编码算法实现 10:1~20:1 的高压缩率，同时支持每秒数百万条数据的并发写入和毫秒级时序查询响应，平衡存储成本与处理效率

✅全场景部署能力：轻量设计可运行于边缘设备，分布式架构支持云端集群扩展，兼容边缘 - 云端协同存储，适配从边缘到云端的全场景物联网部署需求

IoTDB Kubernetes 部署

1、创建命名空间

kubectl create ns iotdb-ns

2、查看命名空间

kubectl get ns

3、创建 PV 配置文件

#可新建个文件夹放yaml文件
#创建 pv.yaml 文件语句
touch pv.yaml

4、pv.yaml 示例

# pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
name: iotdb-pv-01
spec:
capacity:
storage: 10Gi # 存储容量
accessModes: # 访问模式
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain # 回收策略
  # 存储类名称，如果使用本地静态存储storageClassName 不用配置，如果使用动态存储必需设置此项
  storageClassName: local-storage 
  # 根据你的存储类型添加相应的配置
  hostPath: # 如果是使用本地路径
    path: /data/k8s-data/iotdb-pv-01
    type: DirectoryOrCreate  # 这行不配置就要手动创建文件夹

5、应用 PV 配置

kubectl apply -f pv01.yaml
kubectl apply -f pv-02.yaml
...

6、查看 PV

kubectl get pv

7、手动创建文件夹

mkdir -p /data/k8s-data/iotdb-pv-01
mkdir -p /data/k8s-data/iotdb-pv-02
...

8、克隆 IoTDB Kubernetes 部署代码

unset HTTPS_PROXY

9、修改 YAML 文件

nameOverride: "iotdb"  
fullnameOverride: "iotdb"   #软件安装后的名称

image:
  repository: nexus.infra.timecho.com:8143/timecho/iotdb-enterprise
  pullPolicy: IfNotPresent
  tag: 1.3.3.2-standalone    #软件所用的仓库和版本

storage:
# 存储类名称，如果使用本地静态存储storageClassName 不用配置，如果使用动态存储必需设置此项
  className: local-storage

datanode:
  name: datanode
  nodeCount: 3        #datanode的节点数量
  enableRestService: true
  storageCapacity: 10Gi       #datanode的可用空间大小
  resources:
    requests:
      memory: 2Gi    #datanode的内存初始化大小
      cpu: 1000m     #datanode的CPU初始化大小
    limits:
      memory: 4Gi    #datanode的最大内存大小
      cpu: 1000m     #datanode的最大CPU大小

confignode:
  name: confignode
  nodeCount: 3      #confignode的节点数量
  storageCapacity: 10Gi      #confignode的可用空间大小
  resources:
    requests:
      memory: 512Mi    #confignode的内存初始化大小
      cpu: 1000m      #confignode的CPU初始化大小
    limits:
      memory: 1024Mi   #confignode的最大内存大小
      cpu: 2000m     #confignode的最大CPU大小
  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

10、从私有仓库拉取镜像，创建secret 使k8s可访问iotdb-helm的私有仓库

# 注意 单引号
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

# 查看secret
kubectl get secret timecho-nexus -n iotdb-ns
# 查看并输出为yaml
kubectl get secret timecho-nexus --output=yaml -n iotdb-ns
# 查看并解密
kubectl get secret timecho-nexus --output="jsonpath={.data.\.dockerconfigjson}" -n iotdb-ns | base64 --decode

11、安装 IoTDB

# 进入文件夹
cd iotdb-cluster-k8s/helm

# 安装iotdb
helm install iotdb ./ -n iotdb-ns

12、查看 Helm 安装列表

# helm list
helm list -n iotdb-ns

13、查看 Pods

# 查看 iotdb的pods
kubectl get pods -n iotdb-ns -o wide

14、发现故障的排除方式

# 查看k8s的创建log
kubectl get events -n iotdb-ns 
watch kubectl get events -n iotdb-ns

# 获取详细信息
kubectl describe pod confignode-0 -n iotdb-ns
kubectl describe pod datanode-0 -n iotdb-ns

# 查看confignode日志
kubectl logs -n iotdb-ns confignode-0 -f

15、激活 IoTDB，进入confignode的容器中激活

kubectl exec -it -n iotdb-ns confignode-0 -- /bin/bash
cd /iotdb/sbin
/bin/bash start-activate.sh
# 拿到机器码后进行激活
# 退出容器

16、验证 IoTDB（查看iotdb-ns命名空间内的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>

17、查看命名空间内的端口映射情况

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

18、在任意服务器启动 CLI 脚本验证 IoTDB 集群状态（端口即jdbc-balancer的端口，服务器为k8s任意节点的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

19、扩容，新增pv

20、扩容confignode：修改iotdb-cluster-k8s/helm的values.yaml文件，将confignode的3改成4

helm upgrade iotdb . -n iotdb-ns

21、扩容datanode（修改iotdb-cluster-k8s/helm的values.yaml文件，将datanode的3改成4）

helm upgrade iotdb . -n iotdb-ns

22、验证IoTDB状态

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>
# datanode-3     1/1     Running   10 (5m55s ago)   75m   10.20.191.76   a88    <none>           <none>

Apache IoTDB 完整操作指南：从数据模型到高级查询实战

基本概念与数据模型

IoTDB 采用层次化的数据组织方式，路径表达式类似于文件系统路径：

根(root)
├── 数据库(Database/Storage Group)
│   └── 设备(Entity)
│       └── 测点(Measurement)

创建存储组和时间序列

创建存储组（数据库）

-- 创建单个存储组
CREATE DATABASE root.factory1;
CREATE STORAGE GROUP root.factory2;

-- 创建多级存储组
CREATE DATABASE root.plant1.workshopA;

-- 查看所有存储组
SHOW DATABASES;
SHOW STORAGE GROUP;

-- 设置存储组属性（如TTL）
SET TTL TO root.factory1 86400000; -- 设置24小时TTL
UNSET TTL TO root.factory1; -- 取消TTL

创建时间序列

-- 基本语法
CREATE TIMESERIES root.factory1.device1.temperature 
WITH DATATYPE=FLOAT, 
ENCODING=GORILLA, 
COMPRESSOR=SNAPPY;

-- 创建多个时间序列
CREATE TIMESERIES 
root.factory1.device1.temperature WITH DATATYPE=FLOAT, ENCODING=RLE,
root.factory1.device1.pressure WITH DATATYPE=INT32, ENCODING=TS_2DIFF,
root.factory1.device1.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN;

-- 带标签和时间序列
CREATE TIMESERIES root.factory1.device1.voltage 
WITH DATATYPE=DOUBLE, ENCODING=GORILLA
TAGS(unit='V', location='line1', manufacturer='SIEMENS');

-- 查看时间序列
SHOW TIMESERIES root.factory1.**;
SHOW TIMESERIES root.factory1.device1.*;

-- 查看时间序列数量
COUNT TIMESERIES root.factory1.**;
COUNT TIMESERIES root.factory1.** GROUP BY LEVEL=2;

数据写入操作

单设备单点写入

-- 标准写入
INSERT INTO root.factory1.device1(timestamp, temperature, pressure) 
VALUES (1690000000000, 25.5, 100);

-- 多时间点写入
INSERT INTO root.factory1.device1(timestamp, temperature, pressure) 
VALUES 
(1690000001000, 26.1, 101),
(1690000002000, 24.8, 99),
(1690000003000, 25.9, 102);

-- 指定时间精度（毫秒、微秒、纳秒）
INSERT INTO root.factory1.device1(timestamp, temperature) 
VALUES (1690000000123456, 25.5);

多设备批量写入

-- 多设备同时写入
INSERT INTO root.factory1.device1(timestamp, temperature) VALUES (1690000000000, 25.5)
root.factory1.device2(timestamp, humidity) VALUES (1690000000000, 60)
root.factory2.device1(timestamp, voltage) VALUES (1690000000000, 220.5);

带对齐时间戳的写入

-- 对齐写入（同一时间戳写入多个测点）
INSERT INTO root.factory1.device1(timestamp, temperature, pressure, status) 
VALUES (1690000000000, 25.5, 100, true);

数据查询操作

基础查询

-- 查询特定测点
SELECT temperature FROM root.factory1.device1;

-- 查询多个测点
SELECT temperature, pressure FROM root.factory1.device1;

-- 查询所有测点
SELECT * FROM root.factory1.device1;

-- 带时间范围查询
SELECT temperature FROM root.factory1.device1 
WHERE time >= 1690000000000 AND time <= 1690000005000;

-- 值过滤查询
SELECT temperature FROM root.factory1.device1 
WHERE temperature > 25.0;

-- 复合条件查询
SELECT * FROM root.factory1.device1 
WHERE (time >= 1690000000000 AND time <= 1690000005000) 
AND (temperature > 25.0 OR pressure < 95);

高级查询功能

时间滑动窗口聚合

-- 等时间间隔聚合
SELECT 
  COUNT(temperature), 
  AVG(temperature), 
  MAX(temperature), 
  MIN(temperature) 
FROM root.factory1.device1 
GROUP BY ([1690000000000, 1690003600000), 5m);

-- 带填充的聚合查询
SELECT 
  AVG(temperature) 
FROM root.factory1.device1 
GROUP BY ([1690000000000, 1690003600000), 5m) 
FILL(previous);

分层聚合

-- 按层级聚合
SELECT 
  COUNT(temperature) 
FROM root.factory1.device1 
GROUP BY LEVEL=1,2;

-- 按设备聚合
SELECT 
  AVG(temperature) 
FROM root.factory1.** 
GROUP BY DEVICE;

最新值查询

-- 查询最新数据点
SELECT last * FROM root.factory1.device1;

-- 查询指定测点最新值
SELECT last temperature FROM root.factory1.device1;

-- 查询带时间限制的最新值
SELECT last temperature FROM root.factory1.device1 WHERE time > 1690000000000;

分页查询

-- LIMIT 限制返回数量
SELECT * FROM root.factory1.device1 LIMIT 100;

-- LIMIT + OFFSET 分页
SELECT * FROM root.factory1.device1 LIMIT 100 OFFSET 200;

-- SLIMIT 限制测点数量
SELECT * FROM root.factory1.device1 SLIMIT 2;

排序查询

-- 按时间降序
SELECT * FROM root.factory1.device1 
ORDER BY TIME DESC;

-- 按值排序
SELECT * FROM root.factory1.device1 
ORDER BY temperature DESC;

数据更新与删除

数据更新（覆盖写入）

-- IoTDB 中的数据更新实际上是写入新的时间戳
-- 或者使用覆盖写入（需要配置支持）
INSERT INTO root.factory1.device1(timestamp, temperature) 
VALUES (1690000000000, 26.0); -- 覆盖原时间戳的值

数据删除

-- 删除特定时间范围的数据
DELETE FROM root.factory1.device1.temperature 
WHERE time >= 1690000000000 AND time <= 1690000001000;

-- 删除特定值的数据
DELETE FROM root.factory1.device1.temperature 
WHERE temperature > 100.0;

-- 删除整个时间序列
DELETE TIMESERIES root.factory1.device1.temperature;

-- 批量删除时间序列
DELETE TIMESERIES root.factory1.device1.*;
DELETE TIMESERIES root.factory1.**;

元数据操作

标签管理

-- 添加标签
ALTER TIMESERIES root.factory1.device1.temperature 
ADD TAGS(unit='°C', precision='0.1');

-- 更新标签
ALTER TIMESERIES root.factory1.device1.temperature 
SET unit='°F', location='buildingA';

-- 删除标签
ALTER TIMESERIES root.factory1.device1.temperature 
DROP location;

-- 根据标签查询
SHOW TIMESERIES WHERE TAGS(unit)='V';
SHOW TIMESERIES WHERE TAGS(unit)='V' AND TAGS(location)='line1';

属性管理

-- 添加属性
ALTER TIMESERIES root.factory1.device1.temperature 
ADD ATTRIBUTES(min_value=0, max_value=100);

-- 更新属性
ALTER TIMESERIES root.factory1.device1.temperature 
SET max_value=120;

-- 删除属性
ALTER TIMESERIES root.factory1.device1.temperature 
DROP min_value;

修改时间序列

-- 修改数据类型（需要先删除数据）
ALTER TIMESERIES root.factory1.device1.temperature 
ALTER DATATYPE=DOUBLE;

-- 修改编码方式
ALTER TIMESERIES root.factory1.device1.temperature 
ALTER ENCODING=TS_2DIFF;

高级查询示例

连接查询

-- 设备间数据对比
SELECT 
  t1.temperature as temp1, 
  t2.temperature as temp2 
FROM 
  root.factory1.device1 t1, 
  root.factory1.device2 t2 
WHERE t1.time = t2.time;

子查询

-- 嵌套查询（查找高于平均值的温度）
SELECT temperature 
FROM root.factory1.device1 
WHERE temperature > (
  SELECT AVG(temperature) 
  FROM root.factory1.device1 
  WHERE time >= 1690000000000
);

模式匹配查询

-- 使用通配符查询
SELECT * FROM root.factory1.*.temperature;
SELECT * FROM root.*.device1.*;

-- 正则表达式查询
SELECT * FROM root.factory1.device1 
WHERE temperature REGEXP '^25\..*';

性能优化技巧

批量写入

-- 使用 VALUES 列表批量写入
INSERT INTO root.factory1.device1(timestamp, temperature) 
VALUES 
(1690000000000, 25.5),
(1690000001000, 26.1),
(1690000002000, 24.8),
(1690000003000, 25.9),
(1690000004000, 26.3);

使用合适的编码

-- 根据数据类型选择合适的编码
CREATE TIMESERIES root.factory1.device1.counter 
WITH DATATYPE=INT64, ENCODING=TS_2DIFF; -- 适合单调递增序列

CREATE TIMESERIES root.factory1.device1.temperature 
WITH DATATYPE=FLOAT, ENCODING=GORILLA; -- 适合浮点数值

分区策略

-- 合理设置存储组分区
CREATE DATABASE root.region1.factory1; -- 按地域分区
CREATE DATABASE root.factory1.line1; -- 按产线分区

实用工具函数

数学函数

SELECT 
  sin(temperature) as sin_temp,
  cos(temperature) as cos_temp,
  abs(temperature) as abs_temp,
  log(temperature) as log_temp 
FROM root.factory1.device1;

统计函数

SELECT 
  stddev(temperature) as temp_stddev,
  variance(temperature) as temp_variance,
  skew(temperature) as temp_skewness 
FROM root.factory1.device1;

时间函数

SELECT 
  year(timestamp) as year,
  month(timestamp) as month,
  day(timestamp) as day,
  hour(timestamp) as hour 
FROM root.factory1.device1;

错误处理与调试

查看执行计划

-- 解释查询计划
EXPLAIN SELECT * FROM root.factory1.device1 WHERE time > 1690000000000;

事务操作

-- 开始事务
START TRANSACTION;

-- 执行多个操作
INSERT INTO root.factory1.device1(timestamp, temperature) VALUES (1690000000000, 25.5);
INSERT INTO root.factory1.device1(timestamp, pressure) VALUES (1690000000000, 100);

-- 提交事务
COMMIT;

-- 回滚事务
ROLLBACK;

监控查询

-- 查看正在运行的查询
SHOW QUERY PROCESSLIST;

-- 终止查询
KILL QUERY 12345;

TimechoDB（基于 Apache IoTDB）增强特性

TimechoDB 国产自研高性能时序数据库，核心团队源于清华大学，自主研发积累深厚，多项发明专利与顶会论文为技术支撑，通过工信部信创测评，适配信创生态，性能经 TPx - IoT 国际榜单验证达国际领先水平 ，成本把控上大幅降低存储与运维成本，借助云边协同节省网络带宽、接收端 CPU 等资源；原厂团队提供企业级技术支持与可视化工具，提升使用便捷性；超 40 项国产 CPU、OS 兼容认证，集成多类大数据系统，构建稳定全流程方案，助力各行业高效运用时序数据

✅端边云数据协同：支持设备端、边缘、云端数据高效流转，适配多场景部署，实现数据分层处理与协同管理

✅性能无瓶颈：高并发写入（百万级设备）、低延迟查询，经存储与编码优化，平衡读写性能与成本

✅智能 AI 分析：内置时序大模型（本地微调 / 推理），配 70 + 时序 UDF 函数，覆盖数据处理到智能分析全流程

✅稳定安全：分布式架构保障高可用，结合权限、加密机制，满足工业场景数据安全与业务连性需求

✅运维便捷：可视化工具 + 简化部署，支持集群监控、故障诊断，降低工业环境运维门槛

总结

通过本次实践，我们完整体验了 Apache IoTDB 在 Kubernetes 环境中的部署、配置与扩展流程，并深入了解了其在物联网场景下的核心优势：高性能、高压缩率、边云协同与灵活的可扩展架构。IoTDB 以"设备-测点"模型为核心，充分满足工业物联网、智慧城市、能源管理等复杂场景的时序数据管理需求。在此基础上，TimechoDB 进一步强化了国产化兼容性、智能分析能力与企业级支持体系，为用户提供更安全、更稳定、更高效的时序数据全栈解决方案。未来，随着边缘计算与AI的深度融合，IoTDB 与 TimechoDB 将在万物互联的时代中持续发挥关键作用，助力企业构建智能化的数据基础设施。