XXL-JOB 调度中心在默认情况下就是跟 MySQL 深度绑定的这个只要跑过生产环境的人都有体感。最近我接手一个国产数据库替换项目调度中心要从 MySQL 迁移到人大金仓 KingbaseES接任务的时候我想得比较简单换个驱动、改个连接串最多再处理几条建表语句半天总该结束了。结果实际情况比预想顽强得多——初始化脚本直接报错Mapper 里的 LIMIT 语法不认字符串比较行为跟 MySQL 不一样前前后后排查了快一周才把所有坑填平。这篇博文就把 XXL-JOB 适配人大金仓数据库的完整过程写下来包括环境准备、SQL 兼容改造、大小写敏感的坑、回归验证清单给准备做同样改造的同学一份可以直接抄作业的参考。1. 适配前先看清XXL-JOB与KingbaseES之间的三道坎1.1 XXL-JOB的MySQL依赖症体现在哪普通业务系统从 MySQL 迁到人大金仓工作量通常集中在驱动、连接串、部分分页 SQL因为这些系统对数据库专有特性的使用往往不深。但 XXL-JOB 不一样调度中心的所有核心链路都压在数据库上执行器注册与心跳维护写 xxl_job_registry任务配置、路由策略、阻塞处理策略、调度周期存 xxl_job_info 和 xxl_job_group每次触发调度、执行器回调、失败重试记录全部落在 xxl_job_log调度中心集群部署时要靠 xxl_job_lock 这张表维护分布式锁调度前要拿数据库行级锁首页的调度报表、日志报表靠连续多天的 xxl_job_log_report 统计用户权限、GLUE 模式的任务源码分别存 xxl_job_user 和 xxl_job_logglue。每张表背后都有对应的 MyBatis Mapper XML而这些 XML 全部是拿 MySQL 方言写的。大家常用的 XXL-JOB 2.3.x、2.4.x 版本里LIMIT #{offset}, #{pagesize}这种 MySQL 专有分页写法直接写在 XML 里反引号、AUTO_INCREMENT、IFNULL、DATE_FORMAT 这些词也随处可见。所以适配的第一步不是改代码而是认清一个事实XXL-JOB 绑定的是 MySQL 方言不只是 MySQL 驱动。1.2 人大金仓的兼容模式怎么选KingbaseES 跟很多国产数据库一样同一套内核提供了多种方言兼容模式常见的有兼容 Oracle、兼容 PostgreSQL、兼容 MySQL 等。做 XXL-JOB 适配方向很明确尽量选择 MySQL 兼容模式因为 XXL-JOB 的 SQL 就是按 MySQL 写的这个模式能兜住一部分语法能省不少改造量。这里要提醒一句金仓的兼容模式并不是所有版本、所有小版本行为完全一致的。我在技术社区里看到不少人在问为什么同样的 SQL 在 A 环境能跑、在 B 环境报错排查下来往往是初始化数据库时选的模式或者 locale 配置不一样。所以正式动工前先在本地用一个空库把整个流程验证一遍不要把在某个环境能跑当成在金仓上一定能跑。1.3 迁移的整体动作拆解整个适配工作可以拆成六个步骤后面每一章对应一部分准备 KingbaseES 实例初始化时选定 MySQL 兼容模式在调度中心工程里引入 kingbase8 驱动改数据源配置改造官方 tables_xxl_job.sql 初始化脚本建库建表逐个核对 Mapper XML把 MySQL 专有语法替换成金仓能认的写法启动调度中心按核心链路逐一验证功能回归边界场景比如日志清理、执行器过期、调度报表、并发触发。这套顺序有个好处前面每步的产物都是下一步的输入任何一步报错都能快速定位是环境问题还是 SQL 问题不会出现改了半天不知道哪条 SQL 挂了的情况。我在实际执行时把每一步的报错都截图存档后面排查问题时非常有用。2. 从驱动到建表环境准备阶段最容易翻车的细节2.1 驱动引入与连接串写法金仓的 JDBC 驱动通常叫 kingbase8驱动类名com.kingbase8.Driver连接串前缀jdbc:kingbase8://默认端口是 54321不是 MySQL 的 3306也不是 PostgreSQL 常见的 5432。如果公司私服里已经有这个依赖直接引入即可如果没有先去官网下载对应版本的驱动 jar通过 maven install-file 装到本地仓库或者私有仓库mvn install:install-file -Dfilekingbase8-x.x.x.jar -DgroupIdcn.com.kingbase \ -DartifactIdkingbase8 -Dversionx.x.x -Dpackagingjar然后改 Spring Boot 的 application.propertiesspring.datasource.urljdbc:kingbase8://10.0.0.10:54321/xxl_job spring.datasource.usernamexxljob spring.datasource.passwordxxljob spring.datasource.driver-class-namecom.kingbase8.Driver这段配置看起来简单但有两个坑值得说。第一个坑连接串上不要带 MySQL 习惯的参数比如 useSSL、characterEncodingutf8 这种金仓驱动未必认识反而可能因为多余参数启动报错。需要指定 schema 或者时区时按 kingbase8 驱动的参数规范来写。第二个坑驱动 jar 的版本要跟数据库实例版本配套。我们遇到过驱动太老连新版本数据库导致的认证报错问题排查了很久最后换掉驱动就好了。启动调度中心时如果日志出现通信协议相关异常优先怀疑驱动版本。2.2 官方建表脚本的逐项改写XXL-JOB 官方的建表脚本 doc/db/tables_xxl_job.sql 是标准 MySQL 写法直接扔给金仓执行大概率会在前几条就报错。我以手头 2.3.0 版本的脚本为例把常见需要处理的片段列出来MySQL 原文金仓改造后说明idint(11) NOT NULL AUTO_INCREMENTid int NOT NULL GENERATED BY DEFAULT AS IDENTITY自增主键改造金仓 MySQL 模式若兼容 AUTO_INCREMENT 也可保留以实测为准ENGINEInnoDB DEFAULT CHARSETutf8mb4删掉表选项金仓不认或忽略xxl_job_info反引号xxl_job_info去掉反引号表名统一小写不带引号varchar(255)varchar(255)一般兼容datetimedatetime / timestamp金仓支持注意默认值函数LONGTEXTTEXT主要涉及 xxl_job_log.trigger_msg、xxl_job_logglue.glue_sourceTIMESTAMP DEFAULT CURRENT_TIMESTAMPDEFAULT CURRENT_TIMESTAMP 或 DEFAULT now()实测驱动能否正确读取否则改 now()很多同学一开始纠结 ENGINEInnoDB 这种表选项要不要改成别的实际上不用改直接删掉最省心。金仓的存储引擎机制跟 MySQL 不是一回事这种选项对它没有实际意义。反引号是另一个高频报错点。MySQL 里反引号用来包裹标识符金仓的 SQL 解析器基本不认。虽然 MySQL 兼容模式可能做了容错但我的建议是所有建表语句里都去掉反引号同时把表名、列名全部保持小写、不带双引号。这跟第四章要讲的标识符大小写策略有关先在这里把习惯定下来后面会少很多表不存在的诡异报错。2.3 自增主键和默认值为什么是刚需可能有人觉得建表 SQL 改到能执行就算完了其实关键还在两处自增主键和默认值。XXL-JOB 在新增任务、新增用户、保存 GLUE 源码时都在 MyBatis 里配了useGeneratedKeystrue keyPropertyid这意味着数据库必须支持自增主键回填。如果建表时把 AUTO_INCREMENT 简单改成普通 intinsert 之后拿不到自增 id新增任务接口很可能直接报错或者任务 ID 一直是 0。所以主键这行必须处理对。最省事的替代方案是GENERATED BY DEFAULT AS IDENTITY这是 PG 语法体系的标准写法金仓支持得很好。如果你的金仓在 MySQL 模式下也能认 AUTO_INCREMENT那就更省事但不要把省事建立在应该能认上最好一条条跑完并且实际验证新增功能。默认值同理。xxl_job_info 的 add_time、update_time 等字段在 MySQL 里用了 CURRENT_TIMESTAMP金仓大部分版本也支持这个默认值但如果驱动读出的是空值或者 SQL 执行报 invalid default value就统一改成 now()。到这里库和表已经立住了下一步真正费时间的是 Mapper XML 的逐条扫雷。3. Mapper XML里的MySQL痕迹逐条SQL扫雷3.1 LIMIT分页语法第一个必踩的坑XXL-JOB 的后台页面的任务列表、调度日志列表全都走分页查询Mapper 里写的分页 SQL 是这样的SELECT include refidBase_Column_List/ FROM xxl_job_info where if testjobGroup gt 0 AND job_group #{jobGroup}/if /where ORDER BY id DESC LIMIT #{offset}, #{pagesize}问题就出在LIMIT #{offset}, #{pagesize}。这是 MySQL 风格的偏移量在前、行数在后写法金仓走了 PG 语法体系规定的写法是LIMIT #{pagesize} OFFSET #{offset}。改造之后LIMIT #{pagesize} OFFSET #{offset}为什么金仓不兼容 MySQL 的逗号写法因为 PG 语法里 LIMIT 后面只接行数偏移量必须用 OFFSET 关键字分开这是语法层面的定义不接受用逗号把两个数字拼在一起。这个差异不需要死记只要记住凡是 MySQL 的LIMIT a, b都要换成LIMIT b OFFSET a。我在实际迁移中光这一个坑就修了四处xxl_job_info、xxl_job_log、xxl_job_group、xxl_job_user 的分页查询里都有类似写法。改完之后最好全局搜一遍LIMIT把 XML 里所有分页的位置都确认一遍不要只看任务列表这一个 Mapper。3.2 MySQL函数替换表IFNULL、DATE_FORMAT、NOWXXL-JOB 的 Mapper 在不同版本里对 MySQL 函数的使用程度不一样有的多有的少。我自己整理过一张替换表搬过来基本够用MySQL 写法金仓推荐写法说明IFNULL(a, b)COALESCE(a, b)COALESCE 是标准 SQL最稳IF(expr, a, b)CASE WHEN expr THEN a ELSE b END条件函数CASE 全库通用DATE_FORMAT(t, %Y-%m-%d)TO_CHAR(t, YYYY-MM-DD)日期格式化注意占位符差异NOW()now()小写也能跑大小写一般都没问题CONCAT(a, b)CONCAT(a, b)两库都支持GROUP_CONCAT可改写为 string_agg(列, 分隔符)逻辑一致但返回类型和空值处理要验证这里要特别说明一下 DATE_FORMAT 和 TO_CHAR 的占位符差异。MySQL 里月份是 %m、日期是 %d而金仓沿用的是 Oracle/PG 体系月份是 MM、日期是 DD。很多同学把函数名换成 TO_CHAR忘掉占位符也换了结果查出来的日期全是 00这种错误特别隐蔽问了半天才发现是格式串写错了。另一个容易忽略的点是如果你的金仓开的是 MySQL 兼容模式部分 MySQL 函数可能也被兼容了。我在测试环境里就发现 IFNULL 在某些小版本里能用但我不建议依赖这种能用因为你不知道它内部是不是真的按 MySQL 语义实现的一旦老版本升级到新版本行为变了就不好排查。COALESCE 这种标准写法在任何模式下都不会有歧义。3.3 调度锁和事务SELECT FOR UPDATE的兼容性XXL-JOB 集群调度依赖 xxl_job_lock 表的行级锁Mapper 里的 SQL 是这个SELECT * FROM xxl_job_lock WHERE lock_name #{lockName} FOR UPDATE这个语法在金仓里是兼容的不需要改。但有两个事情要注意。第一FOR UPDATE 必须在一个显式事务里才有意义。XXL-JOB 的 Service 层已经加了事务注解所以调度执行时这个锁能正确持有到方法结束你不需要额外处理。但如果你自己二次开发在自定义 Mapper 方法里直接调用这个查询外面没有包事务锁会在语句执行完就释放并发调度就会出现两个节点同时拿到锁的问题。这个不是金仓独有的任何数据库都这样但适配过程中容易被忽略。第二我见过有人为了让调度锁更快想把 xxl_job_lock 改成内存表或者干脆从数据库里拿走。我的建议是别动集群调度锁依赖数据库的持久化和行锁语义金仓的普通表就能提供这个能力不要引入额外复杂度。3.4 registry心跳、日志清理和批量写入的细节执行器注册表 xxl_job_registry 的操作很简单主要是注册时先删后插、心跳时更新字段、清理时删除超时记录。这里的 SQL 没有复杂语法金仓基本能吃下。真正要注意的是字符串比较下一章会详细展开。日志清理方面XXL-JOB 管理界面提供了清理日志按钮对应的 Mapper 往往是一个 DELETE比如DELETE FROM xxl_job_log WHERE trigger_time #{triggerTimeoutTime}这种最简单的 DELETE 金仓完全兼容。但如果你用的版本里带 limit比如 DELETE ... LIMIT 100金仓不支持。MySQL 允许 DELETE 语句直接跟 LIMITPG 语法不允许。要改成通过子查询来限制行数DELETE FROM xxl_job_log WHERE id IN ( SELECT id FROM xxl_job_log WHERE trigger_time #{time} LIMIT #{count} );另外批量 INSERT 的多 VALUES 写法INSERT INTO t (...) VALUES (...), (...)金仓是支持的我在 registry 和日志报表相关 SQL 里没有遇到障碍。唯一可能出问题的是 MySQL 的INSERT ... ON DUPLICATE KEY UPDATE这个语法金仓不认如果 XXL-JOB 的某个版本或者二次开发里用了要换成INSERT ... ON CONFLICT (...) DO UPDATE SET ...或者先 delete 再 insert。4. 字符串不区分大小写一个让很多人懵掉的真实原因4.1 现象和根因排序规则说了算kingbase mysql模式字符串不区分大小写咋回事是一个反复出现的高频问题。我在适配 XXL-JOB 时也确实遇到了类似的现象在 registry 表里查询时registry_key 写成小写能匹配到大写的数据看起来像是数据库在自动忽略大小写但实际不是这是字符串比较规则的问题。大小写是否敏感最终由排序规则collation决定。熟悉 MySQL 的人都知道utf8mb4_general_ci 这种以 _ci 结尾的排序规则就是大小写不敏感的abc 和 ABC 会被认为是同一个值。人大金仓在 MySQL 兼容模式下为了贴近 MySQL 的默认行为很可能把默认排序规则设成了大小写不敏感的类型。所以你在这种模式下做 where 等值比较字符串的大小写就被忽略了。这个结论也可以通过一条 SQL 验证SHOW LC_COLLATE;如果返回的排序规则名称带着 ci或者库里配置的 locale 是大小写不敏感的就能解释你看到的现象。很多业务系统在 MySQL 里习惯了不区分大小写切到金仓 MySQL 模式反而觉得正常但对 XXL-JOB 这种带用户名、执行器唯一标识的系统来说不一定是想要的行为。4.2 对XXL-JOB调度体系带来的具体影响字符串不区分大小写对 XXL-JOB 的影响主要体现在三处。第一处是执行器注册。执行器的 registry_key 通常是用 AppName 和地址拼出来的如果两个执行器一个注册成 xxl-job-executor-demo另一个注册成 XXL-JOB-EXECUTOR-DEMO在不区分大小写的规则下可能被当成同一个 key导致注册信息互相覆盖。虽然正常项目不会这么起名但一旦有环境差异定位起来非常难受。第二处是用户登录。xxl_job_user 表里的用户名如果也不区分大小写就存在弱账号风险比如数据库里存的是 Admin攻击者用 admin 可能也能登录进去。这个问题在做安全审计时特别显眼。第三处是任务 AppName 的匹配。任务绑定执行器分组时底层要做 group 和 registry 的匹配如果字符串比较忽略了大小写可能出现分组名差个大小写也能匹配上的情况运行期行为跟预期不一致。4.3 如何让字符串比较恢复大小写敏感如果你确认业务需要区分大小写可以从三个层面解决。查询级别强制区分。在金仓支持的 SQL 里可以这样写SELECT * FROM xxl_job_registry WHERE registry_key xxl-job-executor-demo COLLATE C;COLLATE C 强制使用 C 排序规则字符串比较按字节进行自然区分大小写。这种写法改造成本低适合先应急验证也能帮助确认问题是不是出在 collation 上。建表级别锁定规则。在建表时给关键的 varchar 列指定一个大小写敏感的 collation这样整张表的比较行为都能固定下来。不过要注意具体支持的 collation 名称每个版本可能不同建议先查实例支持的列表再动手不要照抄网上的例子。实例参数层面统一策略。如果整个库都要求区分大小写就要回到初始化阶段选对 locale 和大小写敏感相关参数。这个改动影响面最大如果业务库已经在跑不建议轻易改需要先评估所有业务 SQL 的行为变化。我个人给 XXL-JOB 适配项目的建议是查询级别方案保留在框架里建表级别方案落实在 XXL-JOB 的表上不要依赖默认不区分这个隐含行为。同时在代码里做一下兜底比如登录取用户时统一 trim 和精确匹配不要让太多不确定性下沉到数据库。5. 实测验证从空表到跑通一次完整调度的回归清单5.1 基础功能的验证顺序改完代码、建完表最怕的就是启动起来了就当成功。我建议按下面这个顺序做一遍完整回归每一步都有明确预期。启动调度中心观察启动日志无 SQL 报错端口正常监听浏览器访问管理界面默认账号 admin 能正常登录启动一个示例执行器等心跳周期过后在执行器管理页面能看到在线节点新建一个 simple 触发类型的任务保存成功且 ID 正常回填手动执行一次任务列表显示执行成功打开调度日志能看到完整的触发日志和执行日志首页调度报表数据不是全 0图表能正常展示配置日志保留天数执行清理日志操作数据能按预期删除同时部署两个调度中心节点手动触发同一个任务观察调度锁是否生效创建 GLUE(Java) 任务修改源码保存触发一次确认能跑出结果。这十条跑下来基本覆盖了 XXL-JOB 管理端和调度端的核心链路。里面最容易漏掉的是第 10 条GLUE 模式要读写 xxl_job_logglue 表如果建表脚本在处理 LONGTEXT 字段时出了问题页面能打开但 GLUE 任务一触发就报错。5.2 运行时错误对照表适配过程中常见的报错我整理成了一张表基本能覆盖八成场景。报错信息根因解决方式ERROR: LIMIT #,# syntax is not supportedMySQL 风格 LIMIT 偏移量写法改成 LIMIT #{pagesize} OFFSET #{offset}Table xxl_job.xxl_job_lock doesnt exist大小写或表名不一致统一使用小写表名并去掉反引号核对建表脚本relation xxl_job_info does not exist金仓将未加引号标识符转换了大小写建表、查询全部统一小写不依赖带引号的标识符No suitable driver found for jdbc:kingbase8://驱动 jar 未引入或未打包检查 maven 依赖确认打包产物里包含驱动 classinvalid default value for date column默认值函数不兼容默认值改成 now() 或去掉默认值登录页进去了但列表页 500Mapper XML 某处 MySQL 语法报错打开 MyBatis SQL 日志定位具体 Mapper 方法查询结果中文乱码建库字符集或驱动参数不一致数据库初始化为 UTF8连接串按驱动规范设置这张表看起来简单但每条背后都是实打实踩过的坑。比如内部 No suitable driver 这个问题很多时候不是缺 jar而是 maven 打包时没有把 system scope 的依赖打进 fat jar开发环境能跑、部署包一启动就崩。如果采用 install-file 方式引入记得确认最终产物里包含驱动的 class。5.3 上线前的最终检查上线前除了功能回归还要查几件事。第一xxl_job_log 这张表会随着调度量快速增长一定要确认 trigger_time、job_group、job_id 等常用查询条件的索引都建上了。官方脚本里通常有索引但迁移过程中如果你手工改过表结构很容易把索引弄丢。没有索引的情况下日志多了之后清理任务和分页查询都会变成全表扫描调度中心会越来越慢。第二备份策略。金仓有自己的备份工具跟 MySQL 的 mysqldump 不是一套。上线前先做一次全量备份恢复演练至少跑一遍别等到数据出问题才发现备份根本恢复不了。第三把整个适配改动整理成 diff 文件或者 patch记录改了哪些 XML、哪些建表语句。XXL-JOB 官方发版比较勤后续升级版本时这些改动很可能需要重新套一遍有记录能省一半的返工时间。6. 上线之后需要长期盯的几个点6.1 SQL日志和小版本升级适配完成不代表一劳永逸。我在上线后的头两周一直把 MyBatis 的 SQL 日志打开保留 ERROR 和部分慢查询。这样做的好处是业务侧一个看起来像金仓抽风的报错日志里往往直接能看到是哪条 SQL、哪个参数引发的问题。国产数据库的问题大多数情况下最后都能定位到某条 SQL 的方言差异而不是数据库本身不稳定。金仓的小版本升级同样要注意。跟 MySQL 一样数据库升级可能带来解析器行为变化今天能跑的 SQL升个小版本后可能在某个边界上报错。所以升级数据库前先在测试环境把 XXL-JOB 的回归清单完整跑一遍。6.2 Docker部署验证时的两个细节很多人本地验证喜欢用 Docker 装人大金仓这确实是最省事的方式。有两点提醒一下第一容器里的数据目录一定要挂载到宿主机否则容器删掉数据就没了前面所有适配工作白做第二初始化容器时注意选择 MySQL 兼容模式不同版本的镜像配置方式不完全一样以官方镜像文档为准。如果初始化选错了模式后面建表、函数兼容性都会受影响很容易让人误判是 XXL-JOB 适配的问题。6.3 后续扩展时给自己留一条规矩完成适配之后团队后续会在这个 XXL-JOB 上做二次开发比如增加新的任务类型、扩展告警通道。我给自己定了一条规矩新加的 Mapper SQL 只准用标准 SQL或者金仓明确支持的 PG 语法不允许再引入 MySQL 专有写法。否则每迭代一个版本就要重新翻一遍 Mapper 找兼容性问题成本持续累加。我自己的体会是适配国产数据库这件事技术难度并不高难的是把每一个看起来能跑但不知道为什么会跑的细节都搞清楚。把大小写策略、排序规则、分页语法、函数占位符这些底层差异理解透了XXL-JOB 迁到人大金仓并没有想象中那么玄乎。希望这篇文章能帮你少走几天弯路。