金仓KDTS 工具部署与迁移实操：从环境配置到项目落地

做国产数据库替换项目这么久，我发现异构数据迁移一直是整个落地过程中最棘手的环节。很多项目出现数据丢失、对象迁移不全、业务衔接异常等问题，基本都是迁移工具选型和操作不当导致的。金仓KDTS是专门为KingbaseES数据库配套打造的数据迁移工具，主要用来将Oracle的业务数据和数据库对象平稳迁移到金仓数据库中。

日常普通业务数据迁移、以及政企项目中常见的GIS空间数据迁移，它都能完美支撑，也是我在各类国产化改造项目中，用得最顺手、故障率最低的官方迁移工具。

一、工具基础适配说明

动手部署使用KDTS之前，必须先摸清工具的适配范围，避免因版本不匹配、对象不支持导致迁移失败。这是很多新手容易忽略的问题，前期核对到位，能规避后续80%的迁移故障。

1.1 数据库版本兼容范围

KDTS对源端、目标端数据库版本有明确限制，不支持的版本强行迁移会出现驱动加载失败、数据同步中断等问题，具体适配情况如下：

（1）源端待迁移数据库

目前仅支持Oracle主流数据库，具体适配版本及版本核验SQL如下：

|--------|--------------------|----------------------------|
| 源数据库 | 支持版本 | 版本查询SQL |
| Oracle | 9i、10g、11g、12c、19c | select * from v$version; |

（2）目标端数据库

KDTS仅支持迁移至金仓KingbaseES数据库，兼容V7、V9R3、V9、V9C7多个主流版本，项目中可按需适配。数据库版本核验统一使用SQL：select version();。

1.2 可迁移业务对象

实测下来，KDTS对Oracle的各类数据库对象支持非常全面，基本覆盖企业所有常规业务数据库对象。日常迁移中用到的表、视图、序列、函数、存储过程、程序包、同义词、触发器、自定义类型，以及所有字段、对象注释，都可以完整迁移，无需手动补充，能最大程度减少人工改造成本。

1.3 工具两种运行形态及适用场景

KDTS自带两种运行模式，不用刻意全部掌握，根据服务器环境和运维场景选择即可，实操选型建议如下：

BS网页可视化版：操作直观、上手简单，全程图形化配置，不用改配置文件。适合带图形桌面的服务器、日常调试迁移、小规模数据迁移场景，新手优先用这个版本。

Shell命令行版：无图形界面，纯脚本+配置文件运行，轻量化、资源占用低。专门适配堡垒机远程运维、无桌面服务器、自动化批量迁移场景，生产环境大规模迁移优先选用。

二、迁移前置环境准备（必做）

不管用哪种版本的KDTS，环境准备都是重中之重。很多迁移卡顿、内存溢出、工具启动失败的问题，根源都是前期硬件、软件环境不达标。下面是项目落地的标准化前置配置要求。

2.1 硬件资源要求

硬件配置不用盲目拉高，但核心指标必须达标：

CPU方面：需要根据服务器架构（x64、AArch64）匹配对应的JDK版本，同时结合源库、目标库的运行负载，合理设置迁移并行度，避免CPU满载导致迁移超时。

内存方面：KDTS默认会占用服务器可用内存的2/3作为JVM运行内存，普通数据迁移无需手动调整。但如果业务表包含BLOB、CLOB、NCLOB等大对象字段，一定要手动扩容JVM内存，否则百分百出现内存溢出、任务中断的问题。

磁盘方面：确保KDTS部署目录预留500MB以上空闲空间，用来存放运行日志、迁移脚本、结果报告。如果需要多次测试迁移，建议定期清理logs、results目录，避免磁盘占满导致工具异常。

2.2 软件依赖：JDK部署规范

KDTS有硬性依赖，必须使用JDK11及以上版本，低版本JDK无法启动工具。这里分享一套实测最稳定的部署方式，避开大部分环境冲突问题：

优先使用解压版独立JDK，绝对不建议将KDTS所需JDK配置到系统全局环境变量，很容易和服务器其他业务程序的JDK版本冲突，引发各类未知报错。

JDK安装包可从OpenJDK官方归档站下载：https://jdk.java.net/archive/，实测JDK11.0.2版本兼容性最好、最稳定，适合长期使用。下载解压后，直接放在KDTS程序根目录的jdk文件夹内即可，无需额外配置。

三、KDTS工具详细部署流程

正常安装KingbaseES数据库后，KDTS工具会自动随数据库打包部署，默认存放路径为${KES_HOME}/ClientTools/guitools/KDts/，其中${KES_HOME}是金仓数据库的安装根目录。下面分别讲解两种版本的部署配置步骤。

3.1 BS可视化版部署配置

BS版程序文件都在${KES_HOME}/ClientTools/guitools/KDts/KDTS-WEB目录下，核心包含bin启动脚本、conf配置、drivers驱动、jdk运行环境等子文件夹，部署核心就是调整启动脚本参数。

3.1.1 启动脚本核心配置

Linux系统对应startup.sh脚本，Windows系统对应startup.bat脚本，只需要修改JDK路径和JVM内存两个核心参数，其余默认配置无需改动。

1、配置JDK路径（确保工具能识别本地JDK环境）

Linux脚本配置：

# JDK路径，默认指向目录内jdk文件夹，自定义JDK需修改此处
JAVA_PATH=${BASE_PATH}"/jdk"

Windows脚本配置：

rem JDK路径
set "JAVA_PATH=%BASE_PATH%/jdk"

2、手动调整JVM内存（大对象迁移必改）

默认内存参数较小，处理大数据量、大字段数据时，需要取消注释手动设置，参考配置如下：

Linux环境：

# 取消注释，设置JVM最大/最小内存为18G
JAVA_MEMORY=18G

Windows环境：

rem 取消注释，设置JVM内存为13G
set JAVA_MEMORY=13G

3、默认JVM基础参数保留

脚本内置的编码、网络、模块放行参数是适配高版本JDK的关键，不要随意删除修改，完整核心参数如下：

JAVA_OPT="
-server
-Dfile.encoding=UTF-8
-Djava.net.preferIPv4Stack=true
--add-opens java.base/jdk.internal.loader=ALL-UNNAMED
-Xms${JAVA_MEMORY}
-Xmx${JAVA_MEMORY}
"

3.1.2 工具启动与访问方式

Linux环境执行./startup.sh后台启动工具，实时查看运行日志可执行tail -f logs/kdts-appconsole_*.log，需要停止工具时运行./shutdown.sh即可。Windows直接双击startup.bat脚本启动。

工具仅支持谷歌浏览器访问，默认地址：http://localhost:54523/，初始账号密码为用户名kingbase、密码Kb_DI@2019，登录会话默认有效期1天，超时需重新登录。

3.1.3 国际化语言切换

工具自带中英文双语适配，默认自动跟随浏览器语言。如果需要手动固定语言，可在启动脚本中添加对应参数：中文适配参数-Duser.country=CN -Duser.language=zh，英文适配参数-Duser.country=US -Duser.language=en。

3.2 Shell命令行版部署配置

Shell版程序目录为${KES_HOME}/ClientTools/guitools/KDts/KDTS-CLI，目录结构和BS版基本一致，包含bin启动脚本、conf配置文件、logs日志、results迁移报告等核心目录，部署逻辑完全通用。

3.2.1 脚本参数配置

启动脚本位于kdts-plus/bin目录，JDK路径配置规则和BS版完全一致，仅JVM内存可根据无桌面环境资源占用情况微调，Linux环境参考配置：

# 取消注释，设置内存为12G
JAVA_MEMORY=12G

3.2.2 启停与日志查看

Linux环境执行./startup.sh启动迁移任务，日志统一输出在kdts-plus/logs/kdtsplus_*.log，实时排查问题可使用tail -f命令监控日志，执行./shutdown.sh即可停止运行中的迁移任务。

四、BS可视化版实操全流程

可视化版本操作简单、门槛低，适合大部分常规迁移场景。整体流程很清晰：新建数据源→创建迁移任务→配置迁移参数→执行任务→核对迁移结果，下面是一步步的实操步骤。

4.1 数据源创建与管理

使用工具第一步必须配置数据源，分为源端待迁移数据库、目标端金仓数据库，支持新增、编辑、测试、删除、批量管理等操作。

4.1.1 源端数据库配置（Oracle）

新建数据源时，需要自定义连接名称，选择Oracle数据库类型和对应版本，填写服务器IP、端口、账号密码、数据库名称。Oracle数据库支持SID和ServiceName两种连接模式，集群环境优先用ServiceName，稳定性更高。配置完成后务必点击「测试连接」，验证网络、账号、驱动是否正常，避免后续任务执行失败。

4.1.2 目标端KingbaseES配置

目标端固定选择KingbaseES数据库，匹配对应的版本型号。连接URL分为两种模式，通用JDBC模式适配所有服务器环境，UnixDomainSocket模式仅适用于KDTS和金仓数据库同机部署的Linux环境，能有效提升数据传输效率。配置后同样需要测试连接可用性。

4.2 迁移任务创建与执行（核心步骤）

新建迁移任务分为四步，每一步都有对应的精细化配置，按需调整即可，不用默认照搬所有参数。

第一步：填写自定义任务名称，选择提前配置好的源库和目标库，未提前建数据源的可在此页面快速新建。

第二步：勾选需要迁移的Schema模式，根据业务需求选择是否包含系统模式，必须至少勾选一个模式，否则无法进入下一步配置。

第三步：筛选迁移表对象，支持三种模式：全表迁移、指定表迁移、排除无用表迁移。日常运维中，可直接排除临时表、日志表，减少无效迁移工作量。如果无需筛选表，可直接跳过该步骤。

第四步：核心参数配置，重点关注常用读写参数：源库单次读取100条数据、目标库批量写入1000条、单次提交100MB数据、LOB字段预读取4000Byte，默认参数适配大部分场景。大表可开启拆分功能，设置行数、大小拆分阈值，实现分块并行迁移。同时可配置是否清空目标表、转换Oracle专属语法、开启无日志提速等功能，线程池可按需开启独立配置，提升迁移效率。

4.2.1 任务状态管理

配置完成后，可仅保存任务模板，也可直接保存并启动迁移。任务分为未启动、处理中、迁移完成、迁移失败四种状态。针对失败任务，支持重启、二次增量迁移（仅迁移失败对象），可查看任务详情、DDL语句、报错日志，运行中的任务可手动停止（停止后标记为失败）。

4.3 日志与结果核查

工具会自动生成三类日志，其中Error日志是排错核心，所有迁移异常、报错都会汇总在此。任务结束后，系统会自动统计对象总数、成功数、失败数、忽略数，同时生成对应的脚本文件和执行记录，方便后续核对复盘。

4.4 个人中心管理

支持查看当前登录账号信息、修改登录密码，多人协作运维场景下，可通过该功能管理账号权限，适配团队批量迁移工作。

五、Shell命令行版实操配置

Shell版没有图形界面，所有迁移规则都靠修改yml配置文件实现，适合自动化脚本调度、无桌面服务器、大规模批量迁移场景，稳定性和效率更高。

5.1 全局基础配置

核心配置文件为conf目录下的application.yml，主要用来指定源库类型和运行模式。

通过active参数固定选择oracle源库类型，配置示例：

spring:
  profiles:
    active: oracle  # 按需切换源库类型

默认注释running-mode参数，为常规数据迁移模式；如需校验迁移前后数据一致性，可开启running-mode: DataCompare数据对比模式。

5.2 源库精细化配置（Oracle示例）

打开kdts-oracle.yml文件，可自定义数据库连接、模式过滤、大表拆分、对象筛选等所有参数，实战常用完整配置如下：

# 源库基础连接信息
dbType: oracle
dbVersion: 11g
url: jdbc:oracle:thin:@192.168.1.100:1521/orcl
driver-class-name: oracle.jdbc.OracleDriver
username: oracle_user
password: Oracle@123456
validationQuery: select 1 from dual

# 迁移模式过滤
schemas: "TEST_SCHEMA"
schema-excludes: SYS,SYSTEM,OUTLN,CTXSYS

# 大表拆分优化配置
large-table-split-threshold-rows: 5000000
large-table-split-threshold-size: 5000
large-table-split-max-chunk-num: 24

# 迁移对象精准控制
table-includes: TEST_TABLE1,TEST_TABLE2
view-excludes: VIEW_LOG
migrate-function: false
migrate-procedure: false
migrate-comment: true

# 大对象与超时配置
table-with-large-object-fetch-size: 100
table-with-big-large-object-fetch-size: 50
net-read-timeout: 900
maximum-poolsize: 200

5.3 目标库KingbaseES配置

在同一配置文件的target节点，配置金仓数据库连接信息和迁移规则，适配V9版本的常用配置如下：

target:
  dbType: KINGBASE
  dbVersion: V9
  url: jdbc:kingbase8://192.168.1.101:54321/TEST_DB
  driver-class-name: com.kingbase8.Driver
  username: kingbase
  password: KES@123456
  schemas: "*"
  drop-existing-object: true
  truncate-table: false
  write-batch-size: 1000
  maximum-poolsize: 200

5.4 线程池优化配置

线程池配置文件为conf/thread-config_sample.json，IO密集型的数据库迁移场景，可根据服务器CPU核心数调整线程数量，实测最优配置参考：

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

实操计算公式：IO密集型任务线程数=CPU核心数/(1-阻塞系数)，日常迁移阻塞系数取0.9即可。

5.5 任务运行与结果查看

所有配置完成后，进入bin目录执行./startup.sh启动迁移任务。运行日志按时间归档在kdts-plus/logs目录，error日志为核心排错依据。任务结束后，kdts-plus/result目录会生成完整的HTML可视化报告，同时归档成功、失败的SQL脚本，方便后续核查修正。

六、GIS空间数据专项迁移方案

针对ArcGIS、GeoScene等GIS平台的空间数据迁移，KDTS有专属适配方案，源端仅支持Oracle数据库，目标端KingbaseES可完美承接各类GIS空间业务数据，适配政企GIS业务国产化迁移场景。这部分是小众刚需功能，很多文档讲解不全，下面是完整落地流程。

6.1 迁移前环境预处理

Linux环境下，首先需要部署PostGIS依赖包，将库文件拷贝至金仓数据库对应目录，命令如下：

# 解压PostGIS安装包
tar -xvf postgis_libs.tar
# 拷贝依赖文件到金仓运行目录
cp /home/kingbase/postgis_libs/* /home/kingbase/kes/lib/
cp /home/kingbase/postgis-3.1.2/bin/* /home/kingbase/kes/bin/

# 初始化数据库并启动服务
./initdb -U system -D data
./sys_ctl -D data start

随后登录数据库，创建GIS专属SDE用户、模式并安装必备扩展，这是GIS数据正常运行的核心前提：

-- 登录金仓数据库
./ksql -Usystem -p54321 test
-- 创建GIS专用超级用户
create user sde superuser;
alter user sde password '123456';
-- 创建并授权SDE模式
create schema sde;
alter schema sde owner to sde;
-- 安装GIS空间扩展
create extension postgis;
create extension postgis_raster;
create extension postgis_topology;

6.2 GIS迁移任务配置

首先在application.yml中激活oracle源库模式，再编辑kdts-oracle.yml，必须使用SDE用户连接源库，且数据必须迁移至目标库SDE模式，配置示例：

sources:
  dbType: oracle
  dbVersion: 11g
  url: jdbc:oracle:thin:@192.168.1.100:1521/GIS_DB
  username: SDE
  password: SDE@123456
  schemas: SDE
  table-includes: POINT,LINE,POLYGONT
target:
  dbType: KINGBASE
  dbVersion: V9
  username: SDE
  schemas: SDE

同时需要修改数据类型映射规则，将Oracle的NUMBER类型适配为金仓int类型，配置文件路径为conf/mapping_rule/data_type/oracle_to_kingbase.json：

{
  "sourceType": {"name": "NUMBER","precisionMin": 0,"precisionMax": 38,"scaleMin": 0,"scaleMax": 0},
  "targetType": {"name": "int"}
}

6.3 任务执行与数据注册

执行startup.sh脚本启动迁移，迁移完成后必须手动注册GIS数据 ，否则ArcGIS无法正常加载图层。从迁移报告目录提取acrpyRegisterWithGeodatabase.py脚本，拷贝至ArcGIS服务器Python运行目录，修改脚本内数据库连接信息，执行python acrpyRegisterWithGeodatabase.py完成注册，最后打开ArcMap验证空间图层正常显示即可。

6.4 常见GIS迁移报错排查

实测高频报错及解决方案：ERROR 001050为脚本数据库连接参数与ArcGIS配置不匹配，核对workspace参数即可；ERROR 001400为数据未迁移至SDE模式，需重新配置任务迁移；ERROR 999999多为表缺少objectid主键或字段类型不匹配，手动修正表结构即可。

七、总结

在国产数据库替换的项目落地中，KDTS是我日常用得最多、稳定性最好的专属迁移工具。它兼顾了新手易用性和生产实用性，图形化BS版适合日常调试、小规模迁移，命令行Shell版更适配生产环境自动化、大批量迁移场景，不管是普通业务数据，还是专业性极强的GIS空间数据，都能稳定完成从Oracle到金仓数据库的迁移切换。

结合我历次项目的实操经验，其实KDTS迁移翻车大多不是工具本身的问题，都是前期环境准备不到位、参数配置不合理、操作细节疏忽导致的。部署前一定要核对JDK版本和内存配置，从根源规避基础报错；根据现场环境灵活选择工具模式；遇到超大表和大字段数据，务必提前开启分块拆分、调优内存和线程并发；GIS数据迁移的关键不在于同步数据，而在于后续的SDE注册步骤。排查问题时，优先看error错误日志，从运行环境、账号权限、对象依赖三个方向逐一排查，基本都能快速定位问题。

只要严格按照现场标准化流程操作，提前做好参数调优和风险预判，就能最大程度规避迁移中断、数据丢失、对象缺失等问题，高效、稳妥完成数据库国产化迁移替换，保障业务平滑过渡上线。