KDTS 迁移工具使用指南：从Oracle平滑迁移至KES

正文开始——

一、KDTS 迁移工具概述

KDTS是金仓数据库官方推出的迁移工具，核心用于Oracle向KingbaseES的全量迁移，支持各类数据库对象迁移，提供BS可视化和SHELL命令行两种形态，适配多种使用场景。其深度适配两者语法与数据类型差异，无需大量手动脚本，自带数据一致性校验和断点续传功能，能保障迁移稳定，广泛应用于金融、政务等对迁移要求较高的场景。

核心能力

• 支持源库：Oracle 9i/10g/11g/12c/19c等主流版本
• 支持目标库：KingbaseES V7/V9/V9R3/V9C7系列版本
• 迁移对象：涵盖表、视图、序列、函数、存储过程、包、同义词、触发器、自定义类型、注释等全量对象
• 关键特性：支持大表自动拆分、LOB大对象迁移、线程池并发优化，迁移日志和报告可可视化查看，同时兼容GIS数据迁移

产品形态对比

版本	操作方式	适用场景
BS 版	通过浏览器进行Web可视化操作	适合日常运维工作、快速完成配置、实时监控迁移任务，对新手用户也比较友好
SHELL 版	通过修改配置文件配合命令行执行操作	适用于堡垒机、无图形化界面的专用服务器，以及需要自动化脚本部署的场景

---

二、迁移前环境准备

迁移前的环境准备是KDTS工具稳定运行的基础，需结合硬件、软件及迁移场景综合配置。无论使用BS版还是SHELL版，均需满足基础软硬件要求，明确源库（Oracle）和目标库（KingbaseES）参数，保障软件兼容性并合理分配硬件资源，减少迁移性能瓶颈。

1. 硬件资源要求

• CPU：需匹配服务器的架构（x64/AArch64），后续可根据CPU核心数，合理配置并发线程数量
• 内存：JVM默认会分配可用内存的2/3，要是涉及大表或LOB对象迁移，建议手动调大JAVA_MEMORY参数
• 磁盘：需预留不低于500MB的空间，用于存储迁移过程中产生的日志、迁移报告以及临时脚本文件

2. 软件依赖

• JDK：建议使用JDK 11及以上版本，推荐选择解压版OpenJDK，不需要配置系统环境变量，避免出现环境冲突
• 驱动：KDTS工具自带Oracle和KingbaseES的连接驱动，我们无需额外下载安装，直接使用即可

---

三、KDTS 工具部署

KDTS工具随KingbaseES安装包一同发布，具体路径为${KES_HOME}/ClientTools/guitools/KDts/。它的部署主要分为BS版和SHELL版两种形式，两种形态的部署流程都比较简洁，核心工作就是完成JDK配置、启动脚本设置以及核心参数调整，以此适配不同的运行环境。部署过程中，有几个关键点需要重点关注：一是JDK路径的配置，二是JVM内存的调优，三是启动脚本的权限设置，这三点如果配置不当，很可能导致工具无法正常启动。另外，部署前要确认服务器的端口没有被占用，尤其是BS版的访问端口，确保部署完成后，能够正常访问和操作工具，为后续迁移任务的顺利执行打下基础。

（一）BS 版部署（Web 可视化）

目录结构

KDTS-WEB/
├── bin/      # 启动脚本（startup.sh/startup.bat）
├── conf/     # 配置文件
├── drivers/  # 数据库驱动
├── jdk/      # 内置JDK
├── lib/      # 程序依赖包
└── web/      # 前端页面

JDK 配置

• 如果使用工具内置的JDK，不需要做任何修改；要是想用外置JDK，需要在启动脚本中配置好JAVA_PATH路径
• JVM内存调优（针对startup.sh/startup.bat脚本），以Linux系统的startup.sh为例，具体配置如下：

# Linux（startup.sh）
JAVA_MEMORY=18G
JAVA_OPT="-Xms${JAVA_MEMORY} -Xmx${JAVA_MEMORY}"

启动与访问

• 启动命令很简单，Linux系统执行startup.sh脚本，Windows系统执行startup.bat脚本即可
• 访问地址：http://localhost:54523/，在浏览器中输入该地址就能进入BS版操作界面
• 默认账号和密码：kingbase / Kb_DI@2019，登录后可根据需求修改密码

（二）SHELL 版部署（命令行）

目录结构

KDTS-CLI/
├── bin/      # 启动/停止脚本
├── conf/     # 核心配置（application.yml、kdts-xxx.yml）
├── logs/     # 运行日志
├── results/  # 迁移报告
└── lib/      # 程序包

核心配置

• 核心配置的关键是激活源库类型，在application.yml文件中进行设置，具体如下：

spring:
  profiles:
    active: oracle  # 仅支持oracle源库

启动命令

# Linux
cd KDTS-CLI/bin
chmod +x startup.sh
./startup.sh
# 查看日志
tail -f ../logs/kdts-plus_xxx.log

---

四、BS 版可视化操作指南

BS版作为KDTS工具的可视化形态，最大的优势就是操作直观、上手简单，不需要掌握复杂的命令行语法，很适合日常运维人员和新手用户使用。它的整个操作流程围绕“数据源管理—迁移任务创建—任务监控—结果查看”这四个环节展开，每一步操作都有清晰的界面指引和操作提示，按照提示一步步操作，就能快速完成从Oracle源库到KingbaseES目标库的全流程迁移。操作过程中，我们可以实时查看迁移进度、监控任务状态，要是遇到迁移失败的对象，还能快速定位失败原因，进行二次迁移，大大提升了迁移效率和操作便捷性。另外，它还支持多任务并行管理，能够很好地适配多场景下的迁移需求。

1. 数据源管理

1.1 新建源数据库（Oracle）

• 在界面上填写相关信息，包括连接名称、数据库类型（选择Oracle）、数据库版本、IP地址、端口、用户名、密码，以及SID/ServiceName
• 关键配置要点：Oracle数据库需要选择对应的SID或ServiceName，而KingbaseES支持UnixDomainSocket，要是源库和目标库在同一台机器上，使用这个功能能提升连接效率
• 填写完成后，点击界面上的“测试”按钮，提示“连接成功”后，再点击保存，完成源数据库的配置

1.2 新建目标数据库（KingbaseES）

• 数据库类型固定选择KingbaseES，不需要手动切换其他类型
• 填写目标库的IP地址、端口、库名、账号和密码，点击“测试”按钮，确认连通性正常后，保存配置即可

2. 迁移任务创建（核心步骤）

1. 选择数据源：先自定义一个迁移任务名称，方便后续识别和管理，然后关联之前已经配置好的Oracle源库和KingbaseES目标库

2. 选择迁移模式：根据实际业务需求，勾选需要迁移的业务模式，同时可以设置包含或排除系统模式，配置好搜索路径，确保迁移的对象准确无误

3. 选择迁移对象

   1. 可根据需求选择全表迁移，也可以选择包含指定表或排除指定表的迁移方式
   2. 筛选表的方式有三种，分别是手动输入表名、从列表中选择、通过文件导入，可根据实际情况灵活选择

4. 参数配置（关键优化）

   1. 源库参数：主要配置游标提取数、大表拆分阈值、LOB预读取大小，合理配置这些参数能提升迁移效率
   2. 目标库参数：包括批量写入数、表名大小写设置、是否清空已有数据、无日志表迁移配置等，根据目标库的实际情况调整
   3. 线程池配置：开启独立线程池，分别配置读、写、元数据、LOB相关的线程数，避免线程冲突，提升并发迁移能力

5. 执行任务：参数配置完成后，可选择“保存”按钮，先保存配置，后续再执行迁移；也可以选择“保存并迁移”，立即启动迁移任务

3. 任务监控与日志

• 任务状态会实时显示，主要分为未启动、处理中、迁移完成、迁移失败四种状态，方便我们实时掌握迁移进度
• 日志分为系统日志、Error日志、Info日志三类，支持自动滚动查看，遇到问题时，可通过日志快速定位原因
• 迁移完成后，会显示成功、失败、忽略的对象数量，对于迁移失败的对象，支持二次迁移，直至迁移成功

---

五、SHELL 版命令行配置指南

SHELL版的操作全程通过修改配置文件完成，非常适合自动化部署和无桌面环境使用。比如堡垒机、无图形化界面的专用服务器，或者需要通过自动化脚本部署迁移任务的场景，用SHELL版会更加便捷。它的核心操作逻辑很简单，就是通过修改配置文件，定义好源库（Oracle）、目标库（KingbaseES）、线程池等相关参数，然后执行启动命令，就能自动完成迁移任务，不需要手动进行界面操作。配置过程中，有几个关键点需要注意：一是配置文件的语法要正确，二是参数要匹配实际环境，尤其是源库和目标库的连接信息、迁移对象开关这些关键参数，一旦配置错误，很可能导致迁移失败。另外，我们可以通过日志实时监控迁移状态，确保大规模、自动化迁移任务顺利完成。

1. 源库配置（kdts-oracle.yml 示例）

# 源库连接
dbType: oracle
dbVersion: 11g
url: jdbc:oracle:thin:@192.168.1.10:1521:orcl
username: test
password: 123456

# 迁移模式
schemas: TEST  # 迁移的模式
schema-excludes: SYS,SYSTEM  # 排除系统模式

# 大表拆分
large-table-split-threshold-rows: 5000000
large-table-split-max-chunk-num: 24

# 迁移对象开关
migrate-table-structure: true
migrate-table-data: true
migrate-view: true
migrate-function: true

2. 目标库配置（kdts-oracle.yml）

# 目标库连接
dbType: KINGBASE
dbVersion: V9
url: jdbc:kingbase8://192.168.1.20:54321/test
username: system
password: 123456

# 目标模式
schemas: "*"  # 与源模式同名

# 写入配置
write-batch-size: 1000
drop-existing-object: true  # 覆盖已有对象
truncate-table: false

3. 线程池配置（thread-config_sample.json）

[  {"poolName":"read","corePoolSize":24,"maxPoolSize":24},  {"poolName":"write","corePoolSize":96,"maxPoolSize":96},  {"poolName":"writeLargeObject","corePoolSize":32,"maxPoolSize":32}]

4. 执行与结果查看

• 执行命令：进入KDTS-CLI的bin目录，执行./bin/startup.sh，即可启动迁移任务
• 日志查看：日志文件存放在kdts-plus/logs/目录下，按模式分类存放，遇到迁移问题时，重点查看error.log日志，快速定位原因
• 报告查看：迁移完成后，会在kdts-plus/results/目录下生成HTML格式的迁移报告，打开index.html文件，就能查看详细的迁移结果

---

六、关键迁移场景配置

在实际的Oracle到KingbaseES数据迁移过程中，我们经常会遇到一些特殊场景，比如大表迁移、LOB大对象迁移、GIS数据迁移、无日志表迁移等。这些场景对迁移效率和数据完整性的要求都比较高，不能按照常规配置来操作，需要针对性地调整参数，优化迁移效果。KDTS工具针对这些关键场景，都提供了专属的配置项，我们可以根据数据量、数据类型、系统环境等实际情况，灵活调整参数，避免出现迁移卡顿、数据丢失、性能瓶颈等问题，确保不同场景下的迁移任务都能高效、稳定地完成，同时兼顾数据一致性和迁移速度，满足各类业务场景的迁移需求。

1. 大表迁移优化

• KDTS会根据表的行数或大小，自动拆分大表，然后进行并行读取，提升大表迁移效率
• 大表拆分阈值可自行配置，一般建议行数≥500万或大小≥5000M时，自动拆分大表
• 为了避免出现OOM（内存溢出）问题，需要降低大表的游标读取数，具体配置如下：

table-with-large-object-fetch-size: 10
table-with-big-large-object-fetch-size: 5

2. LOB 大对象迁移（BLOB/CLOB/NCLOB）

• LOB大对象迁移对内存要求较高，建议调大JVM内存，同时降低并发线程数，避免内存不足
• 可以配置大对象专用线程池，专门用于处理LOB对象迁移，有效控制内存占用
• 有一个简单的公式可以参考，保障迁移稳定：(游标读取数 + 大表拆分块数 + 写线程数)× 单行大小 ≤ JVM内存 × 0.9

3. GIS 数据迁移（ArcGIS/GeoScene）

1. 首先在KingbaseES目标库中安装空间扩展，然后创建SDE用户和对应的模式，为GIS数据迁移做好准备
2. 配置数据类型映射：将Oracle中的NUMBER (38,0)类型，映射为KingbaseES中的int类型，确保数据格式兼容
3. 数据迁移完成后，执行注册脚本acrpyRegisterWithGeodatabase.py，完成GIS图层的注册，确保GIS数据正常使用

4. 无日志表加速迁移

# 目标库URL添加应用标识
url: jdbc:kingbase8://ip:port/db?ApplicationName=kingbase_transfer
# 无日志表配置
unlogged-table: true
relogged-table: true  # 迁移后恢复为日志表

---

七、常见问题与注意事项

在Oracle到KingbaseES的迁移过程中，我们可能会遇到一些常见问题，比如驱动加载失败、网络抖动导致迁移中断、迁移顺序不合理、集群迁移异常等。提前了解这些常见问题的解决方法，能有效规避迁移风险，提升迁移成功率。同时，在操作过程中关注各类注意事项，规范操作流程，也能避免因为操作不当，导致数据丢失、迁移中断等问题。下面汇总了迁移过程中最常出现的问题，给出具体的解决思路和操作建议，同时明确迁移顺序、集群迁移等关键环节的注意事项，帮助大家高效解决迁移过程中的各类异常，确保迁移工作顺利推进。

1. 驱动加载失败

• 常见问题：使用Java 9及以上版本时，由于模块化特性，会出现驱动加载权限异常
• 解决方法：在启动脚本中添加JVM参数，具体参数如下：

--add-opens java.base/java.net=ALL-UNNAMED

2. 网络抖动导致迁移中断

• 针对Oracle源库，可以配置net-read-timeout参数，实现主动超时中断，避免因网络抖动导致的长时间阻塞
• 针对KingbaseES目标库，在数据库连接URL中添加socketTimeout=900（单位：秒），设置连接超时时间，减少网络抖动的影响

3. 迁移顺序建议

建议按照以下顺序进行迁移，确保数据一致性和迁移顺利：1.序列 → 2.表结构 + 数据 + 主键 + 索引 → 3.外键 → 4.检查约束 + 视图 + 函数 → 5.同义词 → 6.触发器 → 7.注释

4. 集群迁移优化

• 如果目标库是KingbaseES集群，建议先将集群改为异步同步模式，待迁移任务完成、数据追平后，再恢复为同步模式，避免迁移过程中出现集群同步异常

---

八、总结

KDTS是金仓数据库生态中的官方标准化迁移工具，提供BS可视化和SHELL命令行两种形态，能够覆盖从开发测试到生产环境的全场景迁移需求。它内置了大表拆分、LOB优化、并发调优、GIS兼容、自动类型映射等核心能力，再加上完善的日志与报告体系，能够实现Oracle到KingbaseES的零代码、高效率、高稳定性平滑迁移。实际使用中，KDTS有效解决了异构数据库迁移过程中常见的语法不兼容、数据丢失、迁移效率低等痛点，即便没有专业的迁移开发人员，也能顺利完成从Oracle到KingbaseES的全量迁移。作为企业数据库国产化替代的重要工具支撑，KDTS适配各类行业的迁移需求，能够帮助企业实现数据的平滑过渡，确保业务稳定运行。