Apache IoTDB 从 1.3.x 迁移到 2.x 完整指南

2026-03-05 10 min

为什么必须迁移到 2.x？

先说结论：1.3.x 已进入维护模式，2.x 才是 IoTDB 的未来。

版本现状对比

维度	1.3.x	2.x
开发状态	维护模式	活跃开发
新功能	无	持续更新
数据模型	Tree only	Tree + Table
查询能力	基础 SQL	MATCH RECOGNIZE、窗口函数等
社区支持	逐渐减少	全力投入
建议	临时过渡	长期选择

1.3.x 用户面临的现实问题

问题一：功能停滞
├─ 没有 Table 模型（关系型查询）
├─ 没有 MATCH RECOGNIZE（流式分析）
├─ 没有最新的 UDF 和函数库
└─ 无法享受社区新功能

问题二：生态脱节
├─ 新工具优先支持 2.x
├─ 新文档以 2.x 为主
└─ 社区问题解答偏向 2.x

问题三：长期风险
├─ 1.3.x 最终会停止维护
├─ 迟早要迁移，越晚成本越高
└─ 团队技术栈落后

迁移评估：你的情况适合哪种方案？

方案一：直接迁移（推荐 80% 用户）

适合场景：

□ 1.3.x 生产环境，但可以安排维护窗口
□ 查询逻辑以标准 SQL 为主
□ 团队有测试和验证能力
□ 希望尽快获得 2.x 新功能

迁移难度： 中等

预计时间： 2-4 周（含测试）

方案二：渐进迁移（保守选择）

适合场景：

□ 超大规模集群（100+ 节点）
□ 业务不能有任何中断
□ 有充足的测试资源
□ 可以接受较长的迁移周期

迁移难度： 较低

预计时间： 1-3 个月

方案三：并行部署（特殊场景）

适合场景：

□ 新旧业务隔离
□ 需要 A/B 测试
□ 迁移风险极高
□ 有充足的硬件资源

迁移难度： 较高

预计时间： 1-2 个月

迁移前评估清单

1. 数据模型兼容性检查

Tree 模型（100% 兼容）：

-- 1.3.x 的查询在 2.x 完全兼容
SELECT * FROM root.sg.d1;
SELECT count(*) FROM root.** WHERE time > now() - 1h;

需要检查的场景：

-- 1.3.x 特有功能（2.x 已移除）
SELECT JEXL('value * 2') FROM root.sg.d1;  -- JEXL 已移除，需改为内置算术或 UDF

检查命令：

# 扫描查询日志中的 JEXL 使用
grep -i "JEXL" /path/to/query/logs/*.log

# 统计使用频率
grep -c "JEXL" /path/to/query/logs/*.log | awk -F: '{sum+=$2} END {print sum}'

2. 配置注意事项

迁移到 2.x 时，配置文件格式基本兼容，但需要注意以下几点：

dn_rpc_address 和 dn_internal_address：集群部署时必须显式配置为本机实际 IP，不能使用默认值 127.0.0.1
部分新增配置项需要手动合并，建议 diff 对比新旧配置文件
详细的配置变更参见 V2.0.7 与 V1.3.7 功能解析中的 RPC 地址变更章节

3. 客户端兼容性

需要升级的客户端：

客户端	1.3.x 版本	2.x 版本	操作
JDBC	1.3.x	2.0.x	升级依赖
Session (Java)	1.3.x	2.0.x	升级依赖
Python SDK	1.3.x	2.0.x	升级依赖
Go SDK	1.3.x	2.0.x	升级依赖
CLI	内置	内置	使用对应版本

依赖升级示例：

<!-- Maven (Java) -->
<dependency>
    <groupId>org.apache.iotdb</groupId>
    <artifactId>iotdb-session</artifactId>
    <!-- 1.3.x 版本 -->
    <version>1.3.7</version>
    <!-- 升级到 2.x -->
    <version>2.0.7</version>
</dependency>

# Python
# 1.3.x 版本
pip install apache-iotdb==1.3.7

# 升级到 2.x
pip install apache-iotdb==2.0.7

方案一：直接迁移实战（推荐）

迁移架构

┌─────────────────────────────────────────────────────┐
│                  迁移前 (1.3.x)                      │
│                                                      │
│  应用层 → JDBC/Session → IoTDB 1.3.x 集群            │
│                                                      │
└─────────────────────────────────────────────────────┘
                      ↓ 迁移
┌─────────────────────────────────────────────────────┐
│                  迁移后 (2.x)                        │
│                                                      │
│  应用层 → JDBC/Session → IoTDB 2.x 集群              │
│              ↑                                        │
│          升级客户端依赖                               │
└─────────────────────────────────────────────────────┘

步骤一：准备阶段（Week 1）

# 1. 搭建测试环境（与生产配置一致）
$ cp -r /path/to/prod/config /path/to/test/config

# 2. 部署 2.0.7 测试集群
$ wget https://dlcdn.apache.org/iotdb/2.0.7/apache-iotdb-2.0.7-bin.tar.gz
$ tar -xzf apache-iotdb-2.0.7-bin.tar.gz
$ cd apache-iotdb-2.0.7

# 3. 修改配置（关键！）
$ vim conf/iotdb-conf.properties
dn_rpc_address=192.168.1.10      # 实际 IP
dn_internal_address=192.168.1.10

# 4. 启动测试集群
$ ./sbin/start-confignode.sh
$ ./sbin/start-datanode.sh

步骤二：数据迁移（Week 2）

方式一：Cross-Cluster Sync（推荐）

-- 在 2.x 集群上创建 Pipe
CREATE PIPE pipe_from_13x
WITH EXTRACTOR (
    'extractor' = 'iotdb-extractor',
    'ip' = '192.168.1.10',  -- 1.3.x 集群 IP
    'port' = '6667',
    'user' = 'root',
    'password' = 'xxx'
)
WITH PROCESSOR (
    'processor' = 'do-nothing-processor'
)
WITH SINK (
    'sink' = 'iotdb-sink',
    'ip' = '192.168.1.20',  -- 2.x 集群 IP
    'port' = '6667',
    'user' = 'root',
    'password' = 'xxx'
);

-- 启动 Pipe
START PIPE pipe_from_13x;

方式二：TsFile 拷贝导入

# 1. 停止 1.3.x 集群
$ ./sbin/stop-datanode.sh

# 2. 拷贝数据目录中的 TsFile 文件
$ cp -r /path/to/iotdb-1.3.x/data/datanode/data /tmp/tsfile_backup

# 3. 在 2.x 集群上使用 LOAD 命令导入
$ ./sbin/start-cli.sh -h 192.168.1.20
IoTDB> LOAD '/tmp/tsfile_backup';

方式三：原地升级（适合单机或小集群）

原地升级是最简单的方式，直接在现有节点上替换二进制文件：

# 1. 停止服务
$ ./sbin/stop-datanode.sh
$ ./sbin/stop-confignode.sh

# 2. 全量备份（关键！不可跳过）
$ cp -r data/ /backup/data.$(date +%Y%m%d)
$ cp -r conf/ /backup/conf.$(date +%Y%m%d)

# 3. 下载 2.x 版本
$ wget https://dlcdn.apache.org/iotdb/2.0.7/apache-iotdb-2.0.7-bin.tar.gz
$ tar -xzf apache-iotdb-2.0.7-bin.tar.gz

# 4. 替换 lib 和 sbin 目录
$ cp -r apache-iotdb-2.0.7/lib/* /path/to/iotdb/lib/
$ cp -r apache-iotdb-2.0.7/sbin/* /path/to/iotdb/sbin/

# 5. 合并配置文件（注意：不要直接覆盖 conf，需手动合并）
$ diff conf/iotdb-conf.properties apache-iotdb-2.0.7/conf/iotdb-conf.properties
# 将新增的配置项合并到现有配置中
# 特别注意修改 dn_rpc_address 和 dn_internal_address

# 6. 启动服务
$ ./sbin/start-confignode.sh
$ ./sbin/start-datanode.sh

# 7. 验证
$ ./sbin/start-cli.sh -h <实际IP>
IoTDB> show datanodes;
IoTDB> SELECT count(*) FROM root.**;

步骤三：应用迁移（Week 2-3）

# 1. 升级客户端依赖
# Java (Maven)
$ mvn versions:use-dep-version -Dincludes=org.apache.iotdb -DdepVersion=2.0.7

# Python
$ pip install --upgrade apache-iotdb==2.0.7

# 2. 修改连接配置（如果 IP 变化）
# 旧配置
jdbc:iotdb://192.168.1.10:6667
# 新配置
jdbc:iotdb://192.168.1.20:6667

# 3. 运行测试用例
$ mvn test
$ pytest tests/

步骤四：验证与切换（Week 3-4）

# 1. 数据一致性验证
$ ./sbin/start-cli.sh -h 192.168.1.10  # 1.3.x
IoTDB> SELECT count(*) FROM root.**;

$ ./sbin/start-cli.sh -h 192.168.1.20  # 2.x
IoTDB> SELECT count(*) FROM root.**;

# 2. 灰度切换（推荐）
# 先切换 10% 流量
# 观察 1-2 天
# 逐步增加到 50% → 100%

# 3. 回滚方案（如有问题）
# 保持 1.3.x 集群运行
# 切换流量回 1.3.x
# 排查问题后重新尝试

方案二：渐进迁移（大规模集群）

架构

┌─────────────────────────────────────────────────────┐
│              渐进迁移（按节点分组）                   │
│                                                      │
│  应用层                                              │
│    │                                                 │
│    ├─→ 路由层（负载均衡）                            │
│    │     ├─→ 10% 流量 → 2.x 集群（新节点）           │
│    │     └─→ 90% 流量 → 1.3.x 集群（老节点）         │
│    │                                                 │
│    │              ↓ 逐步切换                         │
│    │                                                 │
│    │     ├─→ 50% 流量 → 2.x 集群                     │
│    │     └─→ 50% 流量 → 1.3.x 集群                   │
│    │                                                 │
│    │              ↓ 完全切换                         │
│    │                                                 │
│    └─→ 100% 流量 → 2.x 集群                          │
│                                                      │
└─────────────────────────────────────────────────────┘

步骤详解

Phase 1: 部署 2.x 集群（10% 容量）
         处理 10% 的读写流量

Phase 2: 数据同步
         使用 Pipe 从 1.3.x 同步到 2.x

Phase 3: 灰度切换
         10% → 30% → 50% → 70% → 100%
         每个阶段观察 2-3 天

Phase 4: 下线 1.3.x
         确认稳定后，下线老集群

常见坑与解决方案

坑一：RPC 地址配置错误

现象：

Error: Connection refused
无法连接到 2.x 集群

原因：

# 使用了默认配置
dn_rpc_address=127.0.0.1  # 只监听本地

解决：

# 修改为实际 IP
dn_rpc_address=192.168.1.20

坑二：客户端版本不兼容

现象：

// Java 客户端报错
Exception: Protocol version mismatch
// 1.3.x 客户端无法连接 2.x 服务端

解决：

<!-- 升级依赖到 2.x 版本 -->
<version>2.0.7</version>

坑三：JEXL 函数报错

现象：

-- 查询报错
SELECT JEXL('value * 2') FROM root.sg.d1;
-- Error: Function JEXL not found

解决：

-- 改为内置函数
SELECT value * 2 FROM root.sg.d1;

-- 或自定义 UDF
SELECT my_udf(value) FROM root.sg.d1;

坑四：内存配置不合理

现象：

Error: Out of memory
频繁 Full GC

解决：

# 2.x 使用动态内存管理
# 建议配置：
dn_memory_allocate_proportion=0.6
dn_heap_size=4g

迁移检查清单

迁移前

□ 完成兼容性评估
□ 搭建测试环境
□ 准备回滚方案
□ 通知相关团队
□ 安排维护窗口

迁移中

□ 数据同步完成
□ 应用依赖升级
□ 查询测试通过
□ 性能测试通过
□ 监控告警配置

迁移后

□ 数据一致性验证
□ 业务功能验证
□ 性能指标达标
□ 观察 1-2 周
□ 下线老集群

参考资料

IoTDB 数据库迁移指南