2.8. 多发比对功能概览

本章节重点介绍比对服务的功能。功能清单列表如下：

比对服务功能概览

服务

功能

描述

比对服务

1

多租户功能

支持根据业务用户名进行区分用户的操作

2

比对结果页面展示

展示traceId、业务SQL、比对结果状态、错误原因、SQL类型、源库、目标库、源库SQL、目标库多发SQL、比较内容、记录行数、应用类型、应用名、业务用户名、schema、业务执行时间、比对执行时间、操作详情展示

3

比对结果筛选

支持根据租户名、比对结果状态、TraceID、应用类型、应用名、用户名、SQL类型（增/删/改/查）、报告时间范围等多维度进行筛选

比对规则自定义

1

忽略表字段规则

指定某张表里的某些字段不进行比较。

2

替换规则

用于将数据替换为另一部分内容，用于例如oracle系中数据库系统内时间格式配置不同，对于相同日期的展示格式不同，可对一侧格式进行替换拉起后比较时间的一致性。

3

忽略大小写规则

用于某些跨系数据库比较时，底层存储规则大小写不一致，配置后可忽略大小写对数据比对的影响。

4

精度截取规则

将数值小数部分精确到指定的位数(四舍五入)，该规则用于保证数值精度在特定应用场景下的一致性和准确性。

5

字符串截取规则

从输入字符串中截取指定长度的子串。

6

布尔转数字规则

将true转成1，将false转成0，例如mysql系和pg系，bool类型比较即存在该情况。

7

时间戳转字符串规则

将数值类型的时间戳（通常为毫秒数）转换为格式化的日期字符串。

8

支持比对语句规则配置

可配置租户级别多库比较SQL类型需支持哪些类别，忽略哪些类别（包括insert、update、delete、select、merge）

其他特色功能

1

支持全表同步

目标库与源库的表数据不一致，支持全表同步。

2

支持钉钉消息推送

在发生比对失败的时候，发送钉钉消息。

2.8.1. 比对服务

注意：

  • 推荐使用 Chrome 浏览器

2.8.1.1. 比对结果页面展示

登录系统后，进入左侧菜单【多发比对】-【多发比对报告】，即可查看比对报告列表界面，比对报告可以基于租户名、比对报告状态、TraceId、应用类型、应用名、用户名、报告生成时间等条件进行筛选。

../_images/%E6%AF%94%E5%AF%B9%E6%8A%A5%E5%91%8A%E5%88%97%E8%A1%A8.png

点击每个比对报告右侧的 详情 链接即可进入比对报告详情界面：

../_images/%E6%AF%94%E5%AF%B9%E6%8A%A5%E5%91%8A%E8%AF%A6%E6%83%85.png

特别注意

  • 比对详情界面展示的表名称在多表操作时会包含所有涉及的表，无法直接看出表与列的关系，需要结合多发查询SQL来明确列字段具体来自哪张表中。

  • 为了列表页面的查询效率，比对结果页面的分页总数与列表是分开查询的，当您点击具体页码切换分页时，分页总数是不会进行更新的；如果您发现分页总数已不准确，需要刷新分页总数时，可点击右下角的刷新按钮，来刷新分页总数。

  • 比对规则下拉列表租户名、应用名、用户名数据量在10000以内时可快速显示，下拉列表数据持续变大时显示会变慢。

  • 比对规则下拉列表租户名、应用名、用户名中的数据每隔一分钟刷新，比对报告中如果出现新的租户名、应用名、用户名需要等待1分钟定时刷新后才会显示在下拉列表中。

点击历史报告刷新时，会根据过滤条件筛选出所有满足条件的报告进行重新刷新生成，确认重新刷新后会删除现有报告并重新生成报告。

特别注意

  • 触发历史报告刷新后，在旧的报告记录上进行详情查看可能会失败，原因是重新生成报告后旧报告数据库已经删除了，因此需要等历史报告刷新完毕后重新查询再进行详情查看。

2.8.1.2. 比对报告列表头支持自定义配置和排序

进入比对报告页面后，在第一列的上方存在一个圆形配置按钮，该按钮即为比对报告列表头配置入口，如下所示：

../_images/column_config_1.png

点击按钮后即可进入配置界面，比对报告列表头配置可基于【租户名+用户名】配置，默认显示全部列信息，隐藏表头Tab表示哪些表头是隐藏不显示的，显示表头Tab表示哪些表头是需要在比对报告列表中显示的， 可以通过操作按钮 <【部分左移】 <<【全部左移】 >【部分右移】 >>【全部右移】在两个Tab之间调整需要显示的表头信息，可以通过拖拽的方式调整Tab中的表头排序，调整完毕后点击确认即可保存，保存完成后即可使用该列配置，如下所示：

../_images/column_config_2.png

注意

  • 该功能在 25.3.2 添加，涉及到增量SQL脚本，非首次安装时，需要参考比对服务部署章节进行升级。

  • 比对报告列表头配置租户名不允许使用全部，用户名不允许使用全部，且租户名、用户名、状态列不可取消，操作列默认保留在表格尾部。

  • 重置操作会将显示列表头还原为全部显示，需要点击确认后才会保存并生效。

  • 列表头配置调整后，在比对报告列表界面点击查询，列表头配置才会生效。

2.8.2. 比对规则说明

2.8.2.1. 支持多租户隔离

  • 比对规则支持多个租户之间相互隔离，每个租户可以使用自己独立的比对规则。比对规则支持配置基于【列数据类型】、【列名称】、【表名称+列名称】、【表名称+列名称+列数据类型】等多个维度的比对规则。

  • 比对规则应用时基于先精确后模糊的流程，比如【表名称+列名称+列数据类型】>【表名称+列名称】>【列名称】>【列数据类型】，在以上维度中只要在一个维度找到了比对规则，应用了比对规则后便不再进行后续查找。

  • 数据库列值不匹配比对规则时，比对规则执行后还是原始值，比如对于精度截取规则，如果数据库列值不是数值类型，如abc，则规则应用后还是原值abc。

  • 比对规则列表页面中的租户名、表名、列名下拉列表，最大支持10000个不重复的选项值，根据创建时间逆序排列。

  • 界面操作时请注意：新增比对规则界面，比对规则类型更改时，默认会清除上一次和规则绑定的配置值，如替换规则中的【待替换的值、替换后的值】，精度截取规则中的【精度截取值】，字符串截取规则中的【截取长度值】，时间戳转字符串规则中的【格式化字符串】。

  • 比对规则验证界面，验证同一个规则时，默认关闭验证窗口会保留上次输出的待测试列值；只有在切换比对规则后会清空。

  • 比对规则配置表名或表列名时，针对逗号分割的多表场景，规则应用时会基于表名进行排序处理，因此表名 a,c,b 和 c,a,b 都能匹配到 a,b,c 三张表关联的场景，无需重复设置，重复设置时，以后设置的规则为准。

    ../_images/%E6%AF%94%E5%AF%B9%E8%A7%84%E5%88%99%E5%A4%9A%E7%A7%9F%E6%88%B7.png

2.8.2.2. 比对规则列数据类型映射说明

  • 对于定长字符串、变长字符串、大字符串等统一映射为 VARCHAR 类型进行处理，在确保语义一致的同时以规避数据库层及驱动层差异。

  • 对于所有精确数值类型，则统一映射为 DECIMAL 类型进行处理。

  • 对于所有非精确数值类型，则统一映射为 DOUBLE 类型进行处理。

  • 对于日期时间和时间戳类型，则统一映射为 TIMESTAMP 类型进行处理。

  • 其他列类型请参考以下映射关系表进行选择。

  • 数据库列类型统一展示为小写格式，比对规则列类型统一展示为大写格式，以示区分。

数据库列类型

比对规则映射类型

char

VARCHAR

nchar

VARCHAR

bpchar

VARCHAR

varchar

VARCHAR

varchar2

VARCHAR

nvarchar2

VARCHAR

long

VARCHAR

tinytext

VARCHAR

text

VARCHAR

mediumtext

VARCHAR

longtext

VARCHAR

json

VARCHAR

number

DECIMAL

numeric

DECIMAL

decimal

DECIMAL

bit

DECIMAL

bool

DECIMAL

boolean

DECIMAL

tinyint

DECIMAL

smallint

DECIMAL

int

DECIMAL

integer

DECIMAL

mediumint

DECIMAL

bigint

DECIMAL

int1

DECIMAL

int2

DECIMAL

int4

DECIMAL

int8

DECIMAL

serial

DECIMAL

bigserial

DECIMAL

float

DOUBLE

double

DOUBLE

binary_float

DOUBLE

binary_double

DOUBLE

real

DOUBLE

float4

DOUBLE

float8

DOUBLE

double precision

DOUBLE

timestamp

TIMESTAMP

timestamp with time zone

TIMESTAMP

datetime with time zone

TIMESTAMP

timestamptz

TIMESTAMP

datetime

TIMESTAMP

date

DATE

time

TIME

blob

BLOB

tinyblob

BLOB

mediumblob

BLOB

longblob

BLOB

clob

CLOB

nclob

CLOB

binary

BINARY

raw

BINARY

bytea

BINARY

varbinary

BINARY

其他所有非以上列类型

OTHER

2.8.2.3. 忽略表列规则

  • 忽略表列规则针对单个表列配置，支持【表名称】、【表名称:*】、【*:列名称】、【表名称:列名称】几种模式，忽略表列规则匹配时不考虑列数据类型，只要匹配该规则，即为当前列值比对成功，将不再应用其他比对规则。

  • 忽略表列规则多个表列配置之间可使用 ; 分割配置，多个列名称之间可通过 , 分割配置，表列名之间使用 : 分割配置，因此这几个分割符不可作为表列名中的一部分。

  • 忽略表列规则典型应用于基于系统时间生成的时间戳，如create_time、update_time等数据列。

  • 忽略表列规则在进行规则测试时，不考虑列值是什么，只要匹配规则，规则应用后列值一直为true。

  • 忽略表列规则中的【比对报告展示】选项用于不需要生成比对报告的场景，当源库或目标库查询结果命中至少一个忽略表列规则且比对报告展示不勾选，即使其他的忽略表列规则同时命中并勾选了比对报告展示，比对报告也不生成，需谨慎使用。

  • 忽略表列规则仅支持租户名、比对规则类型过滤，表列名不支持筛选。

  • 表列名配置出现重叠时，比对报告展示值以后创建的为准，例如 a:c[展示比对报告] a:c,b[不展示比对报告]，针对表 a 的 c 列配置，最终为不展示比对报告。

    ../_images/%E5%BF%BD%E7%95%A5%E8%A1%A8%E5%88%97%E8%A7%84%E5%88%99.png

2.8.2.4. 布尔转数字规则

  • 布尔转数字规则统一将boolean类型中的true转换为1，false转换为0，再进行后续的比对。

  • 布尔转数字规则典型应用于boolean类型在不同数据库中表现形式不一样的场景，MySQL数据库存储时为boolean值，Oracle数据库存储时为整数值。

    ../_images/%E5%B8%83%E5%B0%94%E8%BD%AC%E6%95%B0%E5%AD%97%E8%A7%84%E5%88%99.png

2.8.2.5. 时间戳转字符串规则

  • 时间戳转字符串规则用于将时间戳类型统一转换为字符串后再进行比对，默认转换格式为 yyyy-MM-dd HH:mm:ss。

  • 时间戳转字符串规则典型用于日期时间类型在不同的数据库中行为不一致的问题，数据库驱动序列化后可能是java.util.Date、java.sql.Date、java.sql.Timestamp、java.util.LocalDateTime等不同类型。

  • 配置的格式化字符串长度等于10时，如 yyyy-MM-dd，规则应用时会自动在尾部拼接字符串 00:00:00。

  • 格式化字符串解析依赖于 JDK java.time.format.DateTimeFormatter#ofPattern(java.lang.String) 方法，比对服务本身不做特殊验证，如格式化字符串不包含格式化符号时，也能转换成功，如格式化字符串 123，在应用规则后列值也是 123。

    ../_images/%E6%97%B6%E9%97%B4%E6%88%B3%E8%BD%AC%E5%AD%97%E7%AC%A6%E4%B8%B2%E8%A7%84%E5%88%99.png

2.8.2.6. 精度截取规则

  • 精度截取规则用于将浮点数的精度截取到指定的位数，以忽略浮点数处理在不同数据库中的精度差异。

  • 精度截取规则典型应用于浮点数函数计算，如 expr、sqrt、ceil、floor、round 等数学函数。

  • 对于待测试的数值型列值精度小于配置的截取精度值时，默认尾部填充0。

    ../_images/%E7%B2%BE%E5%BA%A6%E6%88%AA%E5%8F%96%E8%A7%84%E5%88%99.png

2.8.2.7. 字符串截取规则

  • 字符串截取规则用于将字符串截取到指定的长度，以解决字符串处理在不同数据库中的差异。

  • 对于待测试的列值长度小于配置的截取长度值时，默认返回原始列值。

    ../_images/%E5%AD%97%E7%AC%A6%E4%B8%B2%E6%88%AA%E5%8F%96%E8%A7%84%E5%88%99.png

2.8.2.8. 替换规则

  • 替换规则用于将字符串中的指定子字符串替换为用户自定义的子字符串，以解决字符串处理在不同数据库中的差异。

  • 替换规则典型应用于星期处理，如 MySQL 的 WEEKDAY() 返回 0-6，0 代表星期一；DM 中 TO_CHAR(date, ‘D’) 返回的星期值与 Oracle 一致，1 代表星期日，7 代表星期六。

  • 替换规则在界面显示时，被替换值和目标值之间使用§¢£§特殊符号分割，该特殊符号不可用于待替换值和目标值，可能导致结果错误。

    ../_images/%E6%9B%BF%E6%8D%A2%E8%A7%84%E5%88%99.png

2.8.2.9. 忽略大小写规则

  • 忽略大小写规则用于将字符串规范化为小写格式后进行比对，忽略字符串大小写在不同数据库中的差异性。

  • 忽略大小写规则典型应用于系统表列信息查询，如Oracle查询出的表列名称默认为大写，而Postgresql查询出的表列名称默认为小写。

    ../_images/%E5%BF%BD%E7%95%A5%E5%A4%A7%E5%B0%8F%E5%86%99%E8%A7%84%E5%88%99.png

2.8.2.9.1. 指定表列规则

  • 指定表列规则用于限定比对报告的生成范围，如果查询结果集中的表和列至少一个匹配指定表列规则，则比对报告才会生成；当设置了指定表列规则，且查询结果集的表列信息无法匹配到指定表列规则，则比对报告不生成，需谨慎使用。

  • 指定表列规则匹配时，在进行数据比对时，仅会比对指定表列范围内的查询结果，未命中指定表列规则的查询列值不进行比对，且比对提示为【指定表列规则未命中不进行数据比对】。

  • 如果配置了指定表列规则，则不应用忽略规则中的比对报告显式功能，但是不影响在数据比对时应用忽略规则。

  • 指定表列规则仅支持租户名、比对规则类型过滤，表列名不支持筛选。

    ../_images/%E6%8C%87%E5%AE%9A%E8%A1%A8%E5%88%97%E8%A7%84%E5%88%99.png

2.8.2.9.2. COUNT差异数据忽略查询规则

  • COUNT差异数据忽略查询规则是租户级别的比对规则，对于一个业务操作中的所有SQL，这些SQL的多发查询结果具有相同的traceId，如果存在count(xx)查询且结果为0的SQL，则对于和该SQL具有相同表名的所有查询SQL都不进行比对，适用于先查询count后查询详情，且参与多发比对的某个数据库无数据的场景下使用，主要用于解决数据不一致时的多发比对问题。

    ../_images/COUNT%E5%B7%AE%E5%BC%82%E6%95%B0%E6%8D%AE%E5%BF%BD%E7%95%A5%E6%9F%A5%E8%AF%A2%E8%A7%84%E5%88%99.png

2.8.2.10. 比对规则在线验证

  • 比对规则支持在线验证，可在新增规则时先确认下规则的执行效果，规则生效值即为比对规则应用后的列值。

  • 比对规则应用只在数据比对时生效，实际展示比对报告时还是显示原始列值。

以忽略表列规则为例，比对规则匹配时，无论列值是什么，都以true进行对待。

../_images/%E6%AF%94%E5%AF%B9%E8%A7%84%E5%88%99%E5%8C%B9%E9%85%8D.png

以忽略表列规则为例，比对规则不匹配时【此处为列名不匹配】，则返回原始列值。

../_images/%E6%AF%94%E5%AF%B9%E8%A7%84%E5%88%99%E4%B8%8D%E5%8C%B9%E9%85%8D.png

2.8.2.11. 列忽略规则快速添加

  • 比对详情页面支持一键新增列忽略规则，规则新增成功后，将在下次执行比对时生效。忽略该列按钮将在首次点击后置灰。

    ../_images/%E5%BF%BD%E7%95%A5%E8%AF%A5%E5%88%97.png

  • 新增忽略规则成功后，将显示在比对数据规则列表中。

    ../_images/%E5%BF%BD%E7%95%A5%E8%A7%84%E5%88%99%E6%98%BE%E7%A4%BA.png

2.8.3. 比对白名单

2.8.3.1. 比对白名单配置页面

  • 比对白名单作用：通过租户形式配置的SQL操作类型在多发时才会进行数据比对，没有勾选的以及不在范围内的SQL操作类型将不进行数据比对。未配置的租户则默认全部比对。

登录系统后，进入左侧菜单【多发比对】-【比对白名单】，即可查看现有的租户白名单配置列表：可以新增、修改、删除白名单配置；查询基于租户名、源库类型进行筛选。

../_images/%E6%AF%94%E5%AF%B9%E7%99%BD%E5%90%8D%E5%8D%95.png

点击新增按钮，进入新增页面：

../_images/%E6%96%B0%E5%A2%9E%E6%AF%94%E5%AF%B9%E7%99%BD%E5%90%8D%E5%8D%95.png

点击编辑按钮，进入修改页面：

../_images/%E4%BF%AE%E6%94%B9%E6%AF%94%E5%AF%B9%E7%99%BD%E5%90%8D%E5%8D%95.png

点击删除按钮，进行删除操作：

../_images/%E5%88%A0%E9%99%A4%E6%AF%94%E5%AF%B9%E7%99%BD%E5%90%8D%E5%8D%95.png

举例：autotest97租户配置白名单后，配置了忽略DELETE操作类型，发起多发比对后DELETE操作类型SQL将不进行数据比对，同时比对报告界面中会显示状态为操作类型忽略比对：

../_images/%E6%93%8D%E4%BD%9C%E7%B1%BB%E5%9E%8B%E5%BF%BD%E7%95%A5%E6%AF%94%E5%AF%B9%E9%85%8D%E7%BD%AE.png ../_images/%E6%93%8D%E4%BD%9C%E7%B1%BB%E5%9E%8B%E5%BF%BD%E7%95%A5%E6%AF%94%E5%AF%B9%E6%8A%A5%E5%91%8A.png

警告

  • 租户名称支持大小写字母，数字，下划线。暂不支持中文、特殊符号，不支持有空格，不支持 $SYS-ALL$ 和 全部（该标记为HUI前端页面下拉框元素对应的全部标记，不可用于租户名）;

  • 租户名必须唯一，不允许重复;

  • 如果租户配置了白名单没有勾选的操作类型以及不在范围内的SQL操作类型将不进行数据比对，同时详情页不展示，处于置灰状态;

  • MERGE操作类型为预留的操作类型;

  • 白名单配置过程中有发起的多发比对，多个库可能存在有些过滤有些没过滤。因此以白名单配置成功后发起的多发比对为准;

  • 比对报告界面的操作类型忽略比对是在比对的时候改的状态，前置步骤出错那显示的还是前置步骤的状态，比如：解析失败、业务SQL执行失败;

  • 【比对报告(未选中的操作类型)是否展示】选项仅针对不勾选的操作类型生效，当勾选是否展示时，未勾选的操作类型会生成比对报告；当不勾选是否展示时，未勾选的操作类型不生成比对报告，需谨慎使用。

2.8.4. 全库数据同步

2.8.4.1. 全库数据同步页面

  • 业务在开展多发比对服务的第一步，需要确保源库、目标库的数据是一致的。假如数据不一致，会导致比对过程出现异常。所以，需要在界面上提供一个同步工具，供测试人员进行使用。。

  • 增加数据库全库同步页面，确保用户可以进行手动同步，解决数据库同步的难题。。

登录系统后，进入左侧菜单【多发比对】-【全库数据同步】，即可查看现有的全库数据同步列表：可以新增、修改、删除以及执行同步；查询基于源库和目标库进行筛选。

../_images/%E5%85%A8%E5%BA%93%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E9%A1%B5%E9%9D%A2.jpg

点击新增或者修改按钮，进入新增修改全库数据同步页面：

../_images/%E6%96%B0%E5%A2%9E%E6%88%96%E8%80%85%E4%BF%AE%E6%94%B9%E5%85%A8%E5%BA%93%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E4%BB%BB%E5%8A%A1.jpg

不论新增还是修改，均需要测试源库或者目标库可以连通。

点击删除按钮，进行删除操作：

../_images/%E5%88%A0%E9%99%A4%E5%85%A8%E5%BA%93%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E4%BB%BB%E5%8A%A1.jpg

点击同步按钮，进行全库数据同步操作：

备注

同步数据前，需完成以下准备工作：

  1. 配置环境变量

    在比对服务所在服务器手动配置环境变量 LIGHTDB_ETL_JAR，需指向 lightdb-etl 的 jar 包完整路径（ lightdb-etl的下载界面 ）

    示例：export LIGHTDB_ETL_JAR=/data/multiplex/LightDB1.0-comparison-V202502-00-000/lightdb-etl/lightdb-etl-25.1.jar

  2. 放置数据库驱动

在比对服务的 config 目录下放置当前数据迁移所需数据库驱动。

以比对服务工作目录 /data/multiplex/LightDB1.0-comparison-V202502-00-000 为例，可在 /data/multiplex/LightDB1.0-comparison-V202502-00-000/config 中放置以下驱动(lightdb-etl携带)：

  • mysql-connector-j-8.0.30.jar

  • gaussdbDriver-3.0.0-htrunk21.jar

  • gdb_mysql-connector-java-5.1.46.57.jar

  1. 配置数据比对规则

    在比对服务的 config 目录下配置数据迁移后的比对规则。

    以比对服务工作目录 /data/multiplex/LightDB1.0-comparison-V202502-00-000 为例，需在 /data/multiplex/LightDB1.0-comparison-V202502-00-000/config 中放置比较规则目录 compareRules。

    比较规则目录 compareRules 下比对规则文件如下：

    • Boolean2Number.json

    • ForceIgnore.json

    • ForceReplace.json

    • SubPrecision.json

    • SubString.json

    • Timestamp2String.json

    比对规则参考链接 支持多租户隔离。

../_images/%E6%89%A7%E8%A1%8C%E5%85%A8%E5%BA%93%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E4%BB%BB%E5%8A%A1.jpg

警告

  • 支持的是全库数据同步，使用同步前确认目标库结构与源库兼容，同步过程中先删除目标库数据再迁移源库数据;

  • 全库数据同步任务的名称必须唯一，不允许重复;

点击 数据比对结果HTML 可以弹窗查看数据同步之后的表数据比对详情报告

../_images/%E8%A1%A8%E6%95%B0%E6%8D%AE%E6%AF%94%E5%AF%B9%E6%8A%A5%E5%91%8A.png

问题排查

  1. 数据同步日志路径：{比对服务log目录}/lightdb-etl/{yyyyMMdd_HHmmss_任务Id_计数}。示例：/data/multiplex/LightDB1.0-comparison-V202502-00-000/logs/lightdb-etl/20250929_135931_22_19

  2. 上述路径下的 lightdb-etl.log：同步总日志，可查看具体迁移的表、数据等信息。

  3. 上述路径下的 lightdb-etl-error.log：同步报错汇总日志。

2.8.5. 接口数据比对

2.8.5.1. 功能概述

../_images/interface_compare_sequence_diagram_2026-01-25_23-35-12.png

主要功能如下：

  1. 多环境接口数据比对：支持多发微服务环境（对接Oracle/DM/LightDB等数据库）的HTTP接口响应数据一致性比对。

  2. 差异报告生成：自动平铺JSON属性，识别缺失字段、值差异等问题，生成汇总报告和详情报告。

  3. 钉钉告警推送：比对失败时自动发送Markdown格式告警，包含租户、traceId、差异详情等核心信息。

  4. 前端可视化展示：支持分页查询、多条件筛选、差异树可视化、详情弹窗查看等操作。

2.8.5.2. 准备条件

  1. 环境要求：JDK 8+、Spring Boot 2.x、lightdb数据库（比对服务存储）。

  2. 依赖组件：multiplex-filter.jar、multiplex-driver.jar、sql-convert-runtime-fat.jar、unisql-compare-client.jar

  3. 权限要求：具备数据库建表权限(比对服务需要)、服务部署与重启权限、钉钉机器人配置权限。

2.8.5.3. 接口数据比对页面

功能概述

  1. 筛选查询：支持租户、业务用户名、URL、traceId、源库/目标库、时间范围等11种筛选条件。

  2. 查看汇总报告：分页展示比对结果，包含链路ID、比对状态、执行时间等核心信息。

  3. SQL比对结果：点击“成功或者失败”跳转至多发比对页面，携带报告ID、traceId等参数。

  4. 业务接口比对结果：点击“成功或者失败”打开弹窗，再在差异一栏点击差异按钮可弹窗展示JSON差异树（差异节点默认展开，支持滚动同步）。

../_images/interface_compare_main_2026-01-26_00-14-58.png ../_images/interface_compare_detail_window_2026-01-26_00-14-58.png

2.8.5.4. 差异树操作

功能概述

  1. 展开/收缩：点击节点前“+/-”按钮展开或收缩子节点。

  2. 差异标识：缺失字段划横线，值差异标红（源库）/绿（目标库）。

../_images/interface_compare_json_tree_2026-01-26_00-14-58.png

2.8.5.5. 接口数据比对失败发送钉钉告警

功能概述

  1. 告警依赖比对配置项multi.dingding.enableNotifyFunc的内容包含interfaceCompare。示例 multi.dingding.enableNotifyFunc=interfaceCompare

  2. 告警触发条件：接口数据比对失败。

  3. 告警消息包含：租户名称、traceId、目标库数量、总差异数、差异汇总、报告跳转链接。

  4. 钉钉告警推送功能，具体参考 支持钉钉消息推送

../_images/dinding_interfaceCompare_message_2026-01-25_23-35-12.png

2.8.6. 系统工具

2.8.6.1. 比对报告清理

  • 支持比对报告按照租户名、用户名、报告时间进行筛选并清理，如下所示：

../_images/deleteCompareReport.png

警告

  • 该功能在 25.3.2 添加，涉及到增量SQL脚本，非首次安装时，需要参考比对服务部署章节进行升级。

  • 租户名和用户名不能使用全部，报告时间可按需选择，清理操作会将比对报告永久删除，清理前请仔细核对并确认。

  • 操作成功后，租户名和用户名将还原为全部，报告时间保持不变。

2.8.6.2. 系统版本号

  • 可查看当前部署多发比对系统的版本号信息，如下所示。

../_images/systemVersion.png

注意

  • 该功能在 25.3.2 添加，涉及到增量SQL脚本，非首次安装时，需要参考比对服务部署章节进行升级。

2.8.7. 其他特色功能

2.8.7.1. 支持全表同步

  1. 功能概述

    • 全表同步功能用于将比对失败的表从源库全量/条件同步至目标库，同步完成后自动执行数据比对，支持单表/多表批量同步，且针对不同数据库类型提供适配的同步策略。

  2. 环境依赖

    • 下载匹配版本的LightDB-ETL工具（需与比对服务版本兼容）：ETL下载页面

    • 配置环境变量，将LightDB-ETL的jar包（如lightdb-etl-24.3.jar）绝对路径配置到系统环境变量LIGHTDB_ETL_JAR（linux环境）

    • 权限要求，运行比对服务的用户需具备

      • ETL工作目录（{比对服务安装目录}/logs/lightdb-etl）的读写权限

      • 源库的SELECT权限、目标库的INSERT/UPDATE/DELETE权限

      • 源库/目标库的网络连通性（比对服务服务器可访问数据库端口）

  3. 数据库兼容性：

源库

目标库

oracle19c

dm8

oracle19c

gaussdb_oracle

oracle19c

gaussdb_pg

oracle19c

ocean_base_oracle

oracle19c

tdsql_pg_oracle

mysql8/mariadb10

gaussdb500_oracle

mysql8/mariadb10

lightdb_mysql

mysql8/mariadb10

ob_mysql

mysql8/mariadb10

tdsql_mysql

mysql8/mariadb10

gaussdb_oracle

  1. 操作步骤

4.1 触发全表同步

  • 在比对报告页面，针对比对失败的表点击「全表数据同步」按钮；

  • 若为多表同步：

    • 在弹窗中勾选需同步的表（至少选择1张，表名区分大小写，与数据库中一致）；

    • 若目标库为PG系（LightDB_MySQL、GaussDB_Oracle、GaussDB500_Oracle等）：手动输入目标库Schema（默认值 public，支持自定义，不可包含特殊字符）；

    • （可选）配置表的筛选条件：在“where条件”输入框填写筛选规则（如 id > 100 AND create_time < '2025-01-01'，需符合源库SQL语法）；

  • 点击「确认同步」，页面弹出“同步等待框”（不可关闭页面，超时时间默认30分钟），等待后端返回同步结果。

4.2 同步结果查看

  • 同步成功：提示 数据同步完成，数据比对一致，可查看同步的表、数据量、比对结果；

  • 同步完成但比对不一致：提示 数据同步已完成，数据比对不一致，可查看具体差异行数、快速失败提示（不一致行数超过阈值时触发）；

  • 同步失败：提示具体错误信息（如 任务正在执行中，请勿重复提交, 端口占用 等）。

  1. 日志说明

5.1 日志目录

ETL工作目录： {比对服务安装目录}/logs/lightdb-etl/{时间戳_traceId_计数器}（例：20251017_102030_e123456_1），系统会自动清理7天前的过期目录，避免磁盘占用。

5.2 日志文件说明

日志文件

内容说明

lightdb-etl.log

同步总日志：记录同步的表清单、数据量、同步耗时、执行步骤

lightdb-etl-error.log

错误汇总日志：按时间戳记录同步异常，比如连接失败、SQL语法错误、权限不足等

result.info

同步结果核心文件：记录同步是否完成、基础结果信息

table_data_compare_*.html

可视化比对报告：浏览器直接打开，查看字段级数据差异、比对规则应用情况

  1. 问题排查

6.1 常见错误场景及解决方案

错误提示

可能原因

解决方案

任务正在执行中，请勿重复提交

同一表/任务标识的同步任务未结束

等待当前任务完成后重试，或联系管理员查看RUNNING_SYNC_TASKS状态

找不到随机可用端口

服务器端口被占满

释放无用端口，或重启比对服务

源库/目标库连接信息无效

数据库连接串/账号密码错误

核对源库/目标库的JDBC连接信息，测试网络连通性

数据同步完成，数据比对不一致

字段值不匹配/比对规则触发

查看html比对报告，确认差异字段；核对比对白名单/忽略规则配置

ETL配置文件创建失败

目录权限不足/路径非法

检查ETL工作目录权限，确保路径无非法字符

环境校验失败：LIGHTDB_ETL_JAR

环境变量未配置/路径错误

重新配置环境变量，验证jar包路径存在且可读

6.2 高级排查步骤

  1. 查看lightdb-etl-error.log获取详细报错堆栈；

  2. 检查ETL配置文件（application_${时间戳}.properties）核对源/目标库配置；

  3. 验证LightDB-ETL jar包版本与比对服务兼容性；

  4. 确认源库where条件语法正确性（同步筛选条件）。

  1. 注意事项

    1. 数据备份：同步前建议备份目标库对应表数据，避免同步过程中数据覆盖；

    2. 业务影响：同步期间目标库表会写入数据，建议在业务低峰期执行；

    3. 批量同步：多表同步建议分批执行，避免占用过多数据库资源；

    4. 日志保留：系统自动清理7天前的ETL目录，如需保留日志请手动备份。

  2. 术语解释

    • PG系目标库：基于PostgreSQL内核的目标库（LightDB_MySQL/GaussDB_Oracle/GaussDB500_Oracle等）；

    • TraceID：链路ID，用于追踪单次同步任务的全流程日志；

    • Schema：数据库模式，区分不同的数据库对象集合（PG系目标库必填）；

    • 快速失败：数据比对时不一致行数超过阈值，停止比对以提升效率；

    • ETL工作目录：存储同步配置、日志、比对结果的临时目录（自动清理过期数据）。

  3. 截图说明：

在比对报告中，可点击 全表数据同步 将对比失败的表进行表数据的全量同步。详细操作步骤如下：

../_images/%E5%85%A8%E9%87%8F%E5%90%8C%E6%AD%A5%E6%AF%94%E5%AF%B9%E5%A4%B1%E8%B4%A5%E7%9A%84%E8%A1%A8.png ../_images/%E6%88%90%E5%8A%9F%E5%85%A8%E9%87%8F%E5%90%8C%E6%AD%A5%E6%AF%94%E5%AF%B9%E5%A4%B1%E8%B4%A5%E7%9A%84%E8%A1%A8.png

比对失败，多表数据同步，可选择同步的表，至少选择一个

../_images/%E5%A4%9A%E8%A1%A8%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E5%BC%B9%E7%AA%97__2026-01-30_17-31-22.png

目标库是pg 系，举例：lightdb_mysql，gaussdb_oracle，gaussdb500_oracle，在确认数据同步之前，需要手工输入目标库 schema

多表数据同步，选择表之后，点击确认同步后，同步等待后端返回本次迁移结果(先同步数据再比对数据)，具体如下图:

../_images/%E5%A4%9A%E8%A1%A8%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5_%E5%90%8C%E6%AD%A5%E7%AD%89%E5%BE%85%E6%A1%86_2025-10-17_09-51-02.png

2.8.7.2. 支持钉钉消息推送

按照如下操作步骤添加机器人，第一步：打开群设置

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA1.png

第二步：进入机器人

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA2.png

第三步：添加机器人

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA3.png

第四步：选择自定义机器人

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA4.png

第五步：安全设置选择加签

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA5.png

第六步：使用webhook方式

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA6.png

第七步：获取accessToken和secret配置到比对服务中

../_images/%E6%9C%BA%E5%99%A8%E4%BA%BA7.png

比对配置项如下

  1. multi.dingding.accessToken 配置为钉钉机器人Webhook的accessToken，在Webhook的连接参数上获取。

  2. multi.dingding.secret 配置为钉钉机器人的secret，使用加签复选框下面的密钥。

  3. multi.dingding.url 配置为比对服务的访问地址。

  4. multi.dingding.enableNotifyFunc 取值范围sqlCompare,interfaceCompare，分别表示(sql)数据比对失败和接口数据比对失败

当配置钉钉机器人后，(sql)数据比对失败(multi.dingding.enableNotifyFunc的内容包含sqlCompare)，会给钉钉机器人发送消息，如下图：

../_images/dingding_message.png

当配置钉钉机器人后，接口数据比对失败(multi.dingding.enableNotifyFunc的内容包含interfaceCompare)，会给钉钉机器人发送消息，如下图：

../_images/dinding_interfaceCompare_message_2026-01-25_23-35-12.png

2.8.7.3. 详情页面支持横向、竖向展示可配置

功能概述

  1. 实现比对详情表格在竖向展示（默认，数据库表格式） 和横向展示（列转行格式） 间的切换，

  2. 保留差异样式、忽略列、复制等核心交互，适配不同数据查看场景。

比对详情表格在竖向展示（默认，数据库表格式）

../_images/compare_report_detail_table_vertical_2026-01-27_15-51-37.png

横向展示（列转行格式）

../_images/compare_report_detail_table_horizontal_2026-01-27_15-51-37.png