KDTS迁移工具全流程实战教程：从安装配置到增量同步@[toc] 一、工具简介与环境准备 1.1 功能定位 KDTS（K

@[toc]

在这里插入图片描述

一、工具简介与环境准备

1.1 功能定位

KDTS（Kingbase Data Transfer Service）是金仓数据库提供的异构数据迁移工具，支持Oracle、MySQL等源库向KingbaseES的全量/增量数据迁移，具备大表拆分、并行抽取、数据类型自动转换等核心能力[1]。

1.2 环境要求

JDK版本：Oracle JDK 8（推荐），避免使用OpenJDK 11+（可能导致驱动加载异常）
内存配置：迁移大表时建议JVM参数设置为-Xms4G -Xmx8G
网络要求：源端与目标端数据库网络互通，开放数据库端口（默认54321）

1.3 工具获取

官方下载链接需通过金仓技术支持获取，社区版可从信创生态合作渠道申请。安装包包含BS版（Web界面）和SHELL版（命令行），推荐生产环境使用SHELL版提升稳定性[1]。

二、安装部署与初始化

2.1 解压与目录结构

tar -zxvf kdts_v8.6.0.tar.gz
cd kdts_v8.6.0
# 目录说明
bin/        # 执行脚本
conf/       # 配置文件
lib/        # 依赖库
logs/       # 迁移日志

2.2 配置文件修改

编辑conf/application.properties，设置数据库连接池与线程池参数：

# 源库最大连接数
spring.datasource.source.max-active=50
# 目标库写入线程数
kdts.writer.thread-pool.size=20
# 日志级别
logging.level.com.kingbase=INFO

2.3 启动服务

# 前台启动（测试）
bin/startup.sh

# 后台启动（生产）
nohup bin/startup.sh > logs/startup.log 2>&1 &

访问Web界面：http://localhost:8080，默认账号密码：admin/admin[[1](https://bbs.kingbase.com.cn/kingbase-doc/v8)]

三、数据源配置详解

3.1 新建源端连接（Oracle示例）

登录Web界面，进入「数据源管理」→「新建数据源」

配置参数：

<datasource id="oracle_source">
    <type>oracle</type>
    <url>jdbc:oracle:thin:@//192.168.1.100:1521/orcl</url>
    <username>system</username>
    <password>oracle123</password>
    <driver>oracle.jdbc.OracleDriver</driver>
    <connection-params>
        <param name="oracle.net.tns_admin">/opt/oracle/network/admin</param>
    </connection-params>
</datasource>

关键配置说明：
- URL格式：ServiceName模式需指定service_name，SID模式需替换为:SID
- 驱动选择：Oracle 11g使用ojdbc6.jar，12c+使用ojdbc8.jar，需将驱动包放入lib/目录[1]

3.2 目标端KingbaseES配置

<datasource id="kingbase_target">
    <type>kingbase8</type>
    <url>jdbc:kingbase8://192.168.1.200:54321/kingbase?currentSchema=public</url>
    <username>sysdba</username>
    <password>kingbase123</password>
    <driver>com.kingbase8.Driver</driver>
</datasource>

注意：目标库需提前创建数据库和模式，推荐使用CREATE DATABASE kingbase ENCODING 'UTF8';[1]

四、迁移任务配置与执行

4.1 新建迁移任务

进入「迁移管理」→「新建任务」，填写任务名称与描述
选择源端Oracle和目标端KingbaseES数据源
选择迁移对象：
- 全库迁移：勾选所有 schema
- 部分表迁移：手动勾选需迁移的表，支持按名称模糊搜索[1]

4.2 核心参数配置（重点）

在「配置参数」步骤中，重点设置以下选项：

4.2.1 大表拆分策略

大表拆分阈值依据：
- 拆分阈值行数：1000000（100万行以上表自动拆分）
- 拆分最大块数：10（单个表最多拆分为10个批次）
- 含大对象表游标读取记录数：1000（CLOB/BLOB字段降低批次大小）

原理：通过主键范围拆分大表，并行抽取提升迁移效率[1]

4.2.2 数据类型映射调整

系统默认映射规则可能需要手动调整，例如：

Oracle NUMBER(38,0) → KingbaseES BIGINT（默认映射为NUMERIC导致索引效率低）
Oracle DATE → KingbaseES TIMESTAMP(6)（保留毫秒精度）

4.2.3 并行线程配置

表数据读线程池：10（源库读取并发数）
表数据写线程池：15（目标库写入并发数）

建议：读线程数不超过源库CPU核心数，写线程数不超过目标库连接池上限[1]

4.3 保存并执行迁移

预迁移：点击「保存」生成任务，不立即执行
立即执行：点击「保存并迁移」启动任务
任务监控：在「迁移监控」页面查看实时进度，包括已迁移表数、行数、耗时等指标[1]

五、高级功能实战

5.1 按条件迁移（增量同步基础）

对于历史数据已迁移，需同步增量数据的场景：

在「迁移对象」步骤中，勾选目标表后点击「高级设置」

配置过滤条件：

WHERE create_time >= TO_DATE('2023-01-01', 'YYYY-MM-DD')

注意：需确保源表有时间戳或自增ID字段，作为增量条件[1]

5.2 迁移失败处理

5.2.1 驱动加载失败

错误特征：

ERROR: 加载数据库驱动 ORACLE 11g oracle.jdbc.OracleDriver 失败！
java.lang.reflect.InaccessibleObjectException

解决方案：添加JVM参数--add-opens java.base/java.net=ALL-UNNAMED，修改bin/startup.sh：

JAVA_OPTS="$JAVA_OPTS --add-opens java.base/java.net=ALL-UNNAMED"
```[[1](https://bbs.kingbase.com.cn/kingbase-doc/v8)]

#### 5.2.2 约束冲突处理
迁移后目标表外键约束失败：
1. 在迁移任务配置中，取消勾选「外键」迁移
2. 全量数据迁移完成后，手动创建外键约束：
   ```sql
   ALTER TABLE orders ADD CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users(id);

六、任务调度与自动化（替代方案）

由于KDTS未内置任务调度功能，推荐通过以下方式实现定时增量同步：

6.1 Linux Crontab配置

# 每天凌晨2点执行增量迁移脚本
0 2 * * * /opt/kdts/bin/kdts_sync.sh >> /var/log/kdts_cron.log 2>&1

其中kdts_sync.sh内容：

curl -X POST http://localhost:8080/api/task/execute -H "Content-Type: application/json" -d '{"taskId": 1001}'

6.2 增量同步逻辑

-- 增量条件示例（基于时间戳）
WHERE update_time > TO_TIMESTAMP('${last_sync_time}', 'YYYY-MM-DD HH24:MI:SS')

需在脚本中动态维护last_sync_time变量，记录上次同步时间[1]

七、迁移后验证与优化

7.1 数据一致性校验

对比源端与目标端表行数：

-- Oracle
SELECT COUNT(*) FROM t_user;

-- KingbaseES
SELECT COUNT(*) FROM t_user;

关键字段MD5校验：

-- 源端
SELECT MD5(TO_CHAR(id) || name || TO_CHAR(create_time)) FROM t_user;

-- 目标端
SELECT MD5(id || name || create_time) FROM t_user;
```[[1](https://bbs.kingbase.com.cn/kingbase-doc/v8)]

7.2 性能优化建议

索引重建：迁移后对大表重建索引提升查询性能
```
REINDEX INDEX idx_t_user_name;
```
统计信息更新：
```
ANALYZE VERBOSE t_user;
```

八、常见问题与解决方案

问题类型	错误信息示例	解决方案
驱动加载失败	`Unable to make protected void java.net.URLClassLoader.addURL`	添加JVM参数`--add-opens java.base/java.net=ALL-UNNAMED`
连接超时	`Connection refused (Connection refused)`	检查数据库服务状态、防火墙策略、端口开放情况
数据类型转换错误	`column "status" is of type boolean but expression is of type numeric`	在配置参数中调整类型映射规则	[1]

九、总结与参考资料

9.1 教程总结

本教程基于金仓官方文档，详细介绍了KDTS工具的安装部署、数据源配置、大表迁移、增量同步等核心流程，重点解决了并行抽取、驱动兼容、数据一致性校验等关键问题。

9.2 官方文档参考

《KDTS迁移工具使用指南》：bbs.kingbase.com.cn/kingbase-do…
《KingbaseES数据迁移最佳实践》：bbs.kingbase.com.cn/kingbase-do…

注意：工具下载与详细配置模板需联系金仓技术支持获取，生产环境迁移前建议进行小范围验证测试。