1. 为什么我最终选了XXL-JOB做分布式任务调度先说结论如果你正在搭建一套需要集中管理、动态调整、多机协同的定时任务系统XXL-JOB基本可以做到上午引入依赖、下午上线跑任务是一个把“开箱即用”做到极致的轮子。我最早接触XXL-JOB是在一个数据中台项目里当时的痛点很典型业务方时不时要求“每天晚上3点同步一下供应商的库存数据”“每10分钟拉一次第三方接口的推送结果”“每个月的1号上午跑一遍上个月的结算报表”。如果所有任务都硬编码在业务系统里用Spring自带注解定时跑三五个任务时还能忍到了几十上百个任务、并且多台机器同时部署时就完全失控了。问题集中在三点第一每个节点各跑各的定时器同一任务可能在多台机器上重复执行产生脏数据第二任务挂在某个服务进程里服务重启或者版本发布期间任务直接消失没有任何补偿机制第三任务执行情况不透明失败原因、执行耗时、日志详情全部要靠人工翻日志排查效率极低。XXL-JOB解决的就是这三件事。它是一个把“调度中心”和“执行器”分离的分布式任务调度平台调度中心负责任务的配置、触发、监控和日志业务侧只需要把一个执行器嵌在应用里接收调度指令并执行对应代码。这样一来定时任务不再绑死在某个服务进程里即使业务应用重启调度中心也会按照既有的任务配置继续触发等执行器重新上线后自动恢复执行。这套架构理解起来其实很简单调度中心像一个大脑只管“什么时候该干什么”业务应用里的执行器像手脚只管“接到指令后具体怎么干”。两者之间通过HTTP接口通信所以执行器天然支持跨语言、跨网络部署这对很多人来说可能没有意识到即便你的业务系统不是Java写的只要能提供一个HTTP接口接收调度请求就能接入XXL-JOB的调度体系。适合谁来参考这篇文章我是按“先理清原理、再动手部署、最后解决线上问题”这条线来写的前两章适合刚接触分布式定时任务、想快速搭一套环境的人后面几章涉及自动注册、分片广播、任务幂等、多版本JDK兼容这些实战问题适合已经跑起来、正在被各种边界情况折磨的开发者。2. 部署之前的三个关键准备2.1 别急着下代码先把环境版本理清楚我第一次部署XXL-JOB时踩过最无脑的坑就是JDK版本。老版本的项目包里源码编译用的还是JDK 8但你本地如果装了高版本JDK像JDK 17这类编译和运行过程中会露出各种兼容性问题。这个项目在JDK 8环境下是最稳定的尤其是2.3.x系列的release版本建议直接拿官方release版本的源码包或者已经打好的发行包来用而不要自己在高版本JDK下从master分支现编译。具体来说XXL-JOB的“调度中心”模块本身是一个独立的Spring Boot应用需要单独部署在一个进程里。你可以把它部署在一台2核4G的小机器上也可以直接部署在已有的应用服务器里只要保证业务应用所在的执行器能够通过网络访问到调度中心就行。另外提醒一点XXL-JOB的release版本号看起来五花八门但从2.3.0到2.4.0再到2.5.0核心调度功能的变化并不大大多数是界面交互和细节功能的优化。如果你的业务诉求是“先把基础调度跑起来”用官方推荐的稳定版本就好没有必要追最新。但如果你在JDK 8环境下部署请确认你下的版本是对应JDK 8的有些较新版本开始要求JDK 8以上的环境变量配置这点我在后面的常见问题章节会专门讲。2.2 数据库准备一张表搞定所有元数据XXL-JOB的调度中心需要一张数据库表来存储任务配置、执行记录、调度日志、执行器注册信息等。官方SQL脚本在源码目录的/doc/db/tables_xxl_job.sql里整个项目只需要这一个库脚本会创建多张表表之间有明确的外键关系。我建议你在正式部署前先专门为XXL-JOB建一个独立数据库账号和实例不要和业务库混在一起。原因有两点其一XXL-JOB的调度日志表增长比较快长时间运行后单表数据量会很大混在业务库会影响业务查询性能其二调度中心本身没有复杂的分布式事务需求它追求的是调度信息的可靠落库独立库能避免业务侧误操作导致核心调度数据损坏。数据库类型支持MySQL、PostgreSQL等主流关系型数据库。我在项目中用的是MySQL 5.7配合InnoDB引擎按官方默认配置就能稳定运行。如果你用MySQL 8.x需要注意连接驱动的版本差异后续我会讲到排查方法。2.3 源码结构看一眼部署心里有底XXL-JOB的工程结构非常经典整个项目可以拆成三块xxl-job-admin调度中心是一个Spring Boot应用打包后就是一个可执行的jar或者war。xxl-job-core核心公共库封装了执行器端的接入SDK业务应用引入这个依赖就能获得执行器的能力。xxl-job-executor-sample-*官方提供的一系列示例执行器工程里面有Spring Boot版本、Spring版本、JFinal版本等对应不同技术栈的接入示范。我的建议是第一次部署时先不要从零写执行器代码直接在示例工程的基础上做加法。因为示例工程把执行器配置、任务Handler的写法、日志输出的规范都整理好了你只需要改动几个配置项再删掉示例任务类替换成自己的业务逻辑就能跑通全链路。3. 部署时你真正要做的事3.1 调度中心的启动和配置调度中心的配置都在application.properties文件里主要包括服务端口、数据库连接信息、登录账号密码这几项。默认端口是8080如果你机器上的8080端口被占了改成别的端口就行。数据库连接配置和普通Spring Boot应用没区别。启动调度中心之前确保数据库脚本已经执行完毕然后直接启动这个Spring Boot应用。启动成功后浏览器访问/xxl-job-admin路径输入默认管理员账号admin/123456登录就能看到调度中心的主界面。这里面有一个很容易被忽略的配置项调度中心自身有一个“调度线程池”的概念它决定了调度中心能够支撑多大的并发调度压力。默认配置是10个线程对于绝大多数中小规模业务系统来说完全够用不需要额外调优。只有当你的调度任务非常密集、每秒触发几十上百次时才需要关注线程池的调整否则动多了反而会引起调度延迟的误判。还有一点调度中心是支持集群部署的也就是多台机器同时跑同一个调度中心应用、连同一个数据库。如果你做的是高可用架构可以在前端加负载均衡调度中心内部的分布式锁会保证同一时间只有一个节点在触发某个任务不会出现重复调度。3.2 执行器的接入逻辑执行器接入时核心是引入xxl-job-core依赖然后在Spring配置里注册一个XxlJobSpringExecutor的Bean。这个Bean需要配置三个关键参数adminAddresses是调度中心的地址列表appname是执行器的应用名port是执行器自身对外提供HTTP服务的端口用来接收调度中心的回调指令。执行器注册这一块需要明确它有两种方式自动注册和手动录入。从2.x版本开始系统默认推荐自动注册也就是执行器启动后主动往调度中心上报自己的IP和端口调度中心会自动维护一个在线执行器列表。这个设计比手动录入方式省心太多你不需要在任务配置里写死执行器的IP新加一台机器、机器迁移、IP变更这些操作对业务透明只要新执行器启动成功它就会自动出现在调度中心的执行器管理列表里。我建议在生产环境使用自动注册但需要给执行器配上固定端口避免因为随机端口导致多个实例注册信息混乱。如果你是多网卡机器还需要指定执行器绑定的IP地址在配置里用xxl.job.executor.ip这个参数显式指定否则可能会注册成内网IP导致调度中心无法访问。3.3 从添加执行器到跑通第一个任务的完整过程登录调度中心后第一步是进入“执行器管理”页面点击新增创建一个执行器。AppName一定要和业务应用里配置的xxl.job.executor.appname保持一致否则执行器无法注册上来。名称和排序随便填不影响功能。第二步是启动你的业务应用。如果配置无误几秒钟后刷新执行器管理页面就能看到该执行器的状态变为“在线”并显示注册的IP和端口。如果一直是“离线”优先检查网络是否能互通调度中心和执行器的端口再检查执行器配置是否完全匹配。第三步是进入“任务管理”页面添加一个任务。关键配置项包括调度类型支持Cron表达式和固定速度触发两种方式。JobHandler对应执行器里某个被XxlJob注解标注的方法名。路由策略决定这次调度下发到哪一台执行器机器上。阻塞处理策略任务执行超时或堆积时怎么处理。失败重试次数。全部配置好之后保存然后在任务列表上点击“执行一次”就能在调度日志里看到任务的执行状态和输出结果。到此一条完整的调度链路已经跑通。4. 核心功能的原理与配置搞懂这些才算会用4.1 自动注册任务原理就是一次心跳上报网上很多人在问“xxl-job自动注册任务”是什么意思其实就是两个层面的能力一是执行器自动注册到调度中心二是任务Handler自动被发现。第二个层面很多人没注意到它靠的是Spring容器启动时扫描带XxlJob注解的方法把方法名和实例注册成一个个可供调度的Handler。所以你不需要像Quartz那样在某个XML或者DB配置里维护一大堆JobDetail和Trigger绑定关系。这带来的一个显著便利是任务代码和服务代码在同一个工程里版本发布时一起上线不会出现“配置改了但代码没发布”“代码改了但配置没同步”这类乱七八糟的问题。我见过不少团队用老的Quartz方案时任务表达式散落各处排查问题时不仅要去代码仓库翻还要去数据库翻而XXL-JOB的全部配置集中在调度中心的后台界面上同一套入口管理所有业务线的任务配置这对运维的友好度是质变。执行器自动注册的心跳逻辑默认是执行器每隔30秒向调度中心上报一次注册信息。实际生产环境里如果发现执行器明明活着但界面上显示离线多半是网络策略拦了调度中心连接执行器IP端口的请求或者执行器端口冲突。这类问题我会在后面专门给出排查建议。4.2 路由策略怎么选不要默认值用到底路由策略是调度中心下发任务时决定从在线执行器列表里选哪些机器来执行的方式。默认是“第一个”也就是每次都挑集群列表里第一台机器。听起来没什么问题但如果第一台机器挂了或者第一台机器的负载明显高于其他机器这种策略就会导致严重倾斜。我个人常用的几个策略如下轮询Round任务交替分发到每一台机器上适合各机器性能接近、任务执行时间相近的普通业务任务。这是我最推荐的兜底策略。一致性哈希同一个任务编号总是落到同一台机器上适合依赖本地缓存、希望减少跨机器状态同步的任务。故障转移Failover调度中心会先检测执行器是否在线主动避开已经宕机的机器然后把任务打到健康节点上适合对单次执行成功率要求高的场景。分片广播一次调度同时通知所有在线机器每台机器拿到相同的分片参数分片序号和总分片数各自处理自己负责的数据分片。这是处理大数据量任务最常用的模式比如一张表有100万条记录要批量处理三台机器分片后每台处理约33万条速度几乎线性提升。我强烈建议每个任务都根据业务特性显式选择路由策略而不是保留默认值。尤其是大任务一旦用默认的“第一个”策略集群中只有一台机器在干活其他机器空转这个坑我见过太多次了。4.3 阻塞处理策略这是防止任务堆成山的核心阻塞处理策略是指任务被触发了但上一次触发还在执行中这一次触发怎么处理。默认情况下是“丢弃后续调度”意思很简单上一次没跑完这次就不跑了等下一次调度再触发。这个策略适合绝大多数准点执行类任务比如每小时整点同步一次数据如果某次执行耗时超过了一个小时那么宁可跳过一次也不要做任何积压。另一种策略是“单机串行”意思是后续调度会排队等待前一个执行完立刻接着执行下一个。这对一些不允许跳过次数的任务很重要比如每5分钟拉取一次交易流水如果拉取过程偶发超时你不能把这次拉取丢了宁可让它排队延迟。但要注意这种策略只对单个执行器机器生效不会跨机器排队所以在多机部署时排队行为是在每台机器上独立发生的。如果任务有堆积迹象我建议先去检查执行耗时和阻塞策略是否匹配而不是盲目调大线程池。很多任务积压的根源是任务本身执行太慢调度侧做得再多也消化不了。4.4 分片广播的典型场景批量数据四倍速处理分片广播是我觉得XXL-JOB最“值钱”的一个功能。它的实现原理是调度中心触发一次任务时把所有在线执行器列表作为参数一并下发每台执行器在接到任务时能得知自己是第几片、总共有多少片。实际开发中遇到批量数据处理我是这样用的假设有200万条用户数据需要跑一遍风控规则我配置一个分片广播任务任务代码大致是这样XxlJob(riskScanJob) public void riskScanJob() { int shardIndex XxlJobHelper.getShardIndex(); int shardTotal XxlJobHelper.getShardTotal(); // 按用户ID取模分片 ListLong userIds userMapper.selectByShard(shardIndex, shardTotal); for (Long userId : userIds) { processUserRisk(userId); } }这里的selectByShard需要你自己在SQL里实现取模或者区间过滤的逻辑。实际运行下来三台机器处理200万条数据总耗时大约是单台机器跑三分之一的时间这是分片广播最直观的收益。分片广播的另一个好处是天然支持执行器的弹性扩缩容新加一台机器调度中心自动把分片总数加一下一次任务触发时就自动按新数量重新分片不需要人工干预。4.5 调度日志与任务告警别等线上出了问题再去看XXL-JOB的调度日志功能覆盖了每个任务的完整生命周期什么时候触发、选中的哪台机器、执行器是否成功接收、执行结果是什么。这个日志是排查问题的第一入口比业务日志要前置得多。我在实际项目里要求每个执行器代码里用XxlJobHelper.log来输出关键步骤日志而不要用普通的logger.info。因为调度中心的日志查看界面是从执行器本地拉取日志的通过普通日志打印的内容不会被收集到调度日志里排查问题时查不到关键业务信息。这个细节在很多文档里都不起眼但遇到线上问题时就特别重要。告警方面任务执行失败后调度中心支持配置任务告警联系人通过邮件或者企业微信机器人推送告警消息。我把告警和分片任务结合使用分片任务中某一片执行失败能通过告警及时暴露。对于没有专职运维的团队来讲告警配置就是那条兜底的安全绳。5. JDK版本选择与常见兼容性问题5.1 JDK 8正确使用XXL-JOB的姿势XXL-JOB在JDK 8环境下最流行的版本是2.2.x到2.3.x之间。官方源码的编译级别默认就是JDK 8所以直接用这系列版本配合JDK 8运行几乎不会遇到编译问题。需要特别注意的是如果你用Spring Boot 2.7以上的版本来集成xxl-job-coreSpring Boot 2.7默认兼容的是JDK 8到JDK 17但xxl-job-core对Servlet API的传递依赖有时候会和Spring Boot的新版本产生冲突。我遇到过的典型报错是ClassNotFoundException涉及javax.servlet还是jakarta.servlet的包名差异。这种问题本质上是Spring Boot 3.x之后把javax换成了jakarta而xxl-job-core老版本还是基于旧包名编译的。所以不要拿着JDK 8就跑Spring Boot 3.x这两者的搭配本身就是矛盾的。如果你确实需要在JDK 11或JDK 17环境下跑调度中心建议先确认两个前提调度中心应用本身能正常编译启动且执行器SDK的HTTP回调接口能正常被访问。JDK 11和JDK 17对XXL-JOB的兼容性比JDK 8要差一些主要体现在某些网络库的反射调用和模块化限制上没有充分测试前不要直接上生产。5.2 日志和内存相关的坑XXL-JOB调度中心在运行一段时间后内存占用会缓慢增长。原因有两方面一是调度日志表的数据累积导致查询变慢容易引起接口超时二是执行器注册信息在内存中的缓存正常情况下很稳定但如果执行器频繁上下线注册中心的缓存清理不及时会导致内存碎片。建议对调度中心所在的JVM设置合理的堆内存并在部署层面加一个日志归档策略。数据库层面也要定期清理过期日志官方提供了一个日志自动清理的接口和界面入口可以配置日志保留天数。我一向建议生产环境保留7天以内的调度日志更长时间的日志导出归档不要长期堆在业务数据库里。5.3 常见的NoClassDefFoundError和版本冲突集成xxl-job-core到自己的业务工程时常见的问题是依赖版本冲突。XXL-JOB内部用了一个比较老的Jetty版本做执行器的内嵌HTTP服务器如果你的业务工程里已经引入了更高版本的Jetty或者引入了Netty等其他网络框架可能会在启动时出现类冲突。这里我的处理经验是一定要用mvn dependency:tree查看依赖树把xxl-job-core相关的冲突依赖排除干净。尤其是xxl-job-core传递依赖的javax.servlet-api和Spring Boot内嵌Tomcat自带的Servlet API保持同一版本即可不要私自升级否则调度回调接口几乎必然报错。6. 常见问题与排查技巧实录6.1 执行器一直显示离线这是最常被问的问题。遇到执行器离线我的排查顺序是先看调度中心的日志确认是否收到执行器的注册请求再看执行器和调度中心之间的网络是否能通尤其是执行器所在服务器防火墙是否放行了执行器端口最后看执行器配置的AppName是否和调度中心创建的执行器AppName一致。这里还有一个很容易被忽略的细节如果你的执行器部署在Docker容器里有可能会因为容器网络模式导致执行器上报的IP是容器内部IP调度中心访问不到。解决方法是给执行器显式指定注册IP用宿主机IP或者在Docker启动时加上--networkhost参数让容器直接使用宿主机网络。6.2 任务触发成功但执行器没有反应任务在调度日志里显示调度成功但执行器侧没有日志输出多半是JobHandler名称匹配出了问题。检查执行器代码里XxlJob注解的名称和任务配置里JobHandler的填写是否完全一致。这里不存在模糊匹配名称错一个字都不可能触发。另外如果执行器应用是多实例部署并且路由策略是“第一个”在所有实例负载均衡的场景下某个实例因为线程池繁忙而拒绝了调度请求也会表现为“没有反应”。这时候需要去任务列表里看看调度结果详情一般会有明确的错误码提示不用从零排查。6.3 任务偶发重复执行XXL-JOB在设计上保证了调度记录不会丢失但在某些极端场景下比如执行器处理完成后回调调度中心时网络中断调度中心超时后会重新触发一次这会导致业务逻辑被重复执行。所以业务侧一定要做幂等处理。我的经验是凡是涉及金额计算、状态流转、外部接口调用的任务在代码里必须设计幂等机制。最简单的做法是给任务处理记录加一个业务唯一键处理前先查重处理成功后再写入记录。有些团队把幂等期望寄托在调度平台的“防重复”能力上这是不现实的所有分布式调度平台都只能保证尽量不重复不能绝对保证不重复。6.4 调度日志表膨胀导致调度中心性能下降在没有配置自动清理的情况下调度日志表会持续膨胀。我遇到过一张表几千万行数据任务列表打开要十几秒的情况。解决办法是启用调度中心自带的日志清理功能在系统管理里配置一个清理周期比如每天凌晨4点执行一次保留最近7天的日志。如果想手动清理也可以直接操作数据库。但注意不要删除正在处理中的调度日志对应的记录否则任务列表的调度状态会不同步。7. 附表XXL-JOB核心配置项速查手册配置项作用推荐配置xxl.job.admin.addresses调度中心地址列表生产环境配置完整地址如http://ip:8080/xxl-job-adminxxl.job.executor.appname执行器AppName与调度中心创建的执行器保持一致xxl.job.executor.ip执行器注册IP多网卡或Docker环境必填避免注册错误xxl.job.executor.port执行器HTTP端口同一台机器多实例时避免端口冲突xxl.job.executor.logpath执行器日志目录务必配置独立目录方便日志收集xxl.job.executor.logretentiondays日志保留天数建议7天看业务诉求调整xxl.job.accessToken调度中心与执行器通信令牌生产环境务必开启防止恶意调度这些配置项在官方示例工程里都有完整注释第一次接入时对着抄就行。需要注意的是accessToken一旦配置调度中心和执行器两边的值必须一致否则任务调度时会被直接拒绝。8. 结尾我踩过的那些坑希望你绕开文章写到这里我不打算做什么总结了就分享几条我个人的实操习惯。第一XXL-JOB真正跑得稳靠的是任务设计而不是平台参数。拿到一个业务任务先分析它是不是允许跳过、允许重复、允许堆积再决定路由策略和阻塞策略这个顺序不能反。如果你的任务代码本身执行耗时超过调度周期那再完美的调度平台也救不了你。第二执行器的日志必须用XxlJobHelper.log输出。刚开始接入时我图省事沿用业务系统的日志框架打印了什么“开始处理订单”“处理完成”这类信息结果线上任务失败后在调度中心看到的日志只有一句“执行成功”本质上什么业务信息都没有排查靠猜效率极低。后来统一改成XxlJobHelper.log输出任务执行的关键节点一目了然。第三新版本固然好但XXL-JOB的老版本在稳定性上已经经过了大量生产环境验证对于大多数团队在新版本发布后至少等待一两个补丁版本再上生产是一个更稳的策略。最后如果你团队里还没有任何分布式任务调度的沉淀XXL-JOB应该是性价比最高的一条入门路径。它不会像很多重量级框架那样把一个简单问题复杂化它的每个功能点都对应着一个真实生产场景。把这篇文章里的配置和排查思路吃透你的分布式定时任务体系大概率能安安稳稳跑很久。
XXL-JOB分布式任务调度：部署、原理与实战避坑指南
1. 为什么我最终选了XXL-JOB做分布式任务调度先说结论如果你正在搭建一套需要集中管理、动态调整、多机协同的定时任务系统XXL-JOB基本可以做到上午引入依赖、下午上线跑任务是一个把“开箱即用”做到极致的轮子。我最早接触XXL-JOB是在一个数据中台项目里当时的痛点很典型业务方时不时要求“每天晚上3点同步一下供应商的库存数据”“每10分钟拉一次第三方接口的推送结果”“每个月的1号上午跑一遍上个月的结算报表”。如果所有任务都硬编码在业务系统里用Spring自带注解定时跑三五个任务时还能忍到了几十上百个任务、并且多台机器同时部署时就完全失控了。问题集中在三点第一每个节点各跑各的定时器同一任务可能在多台机器上重复执行产生脏数据第二任务挂在某个服务进程里服务重启或者版本发布期间任务直接消失没有任何补偿机制第三任务执行情况不透明失败原因、执行耗时、日志详情全部要靠人工翻日志排查效率极低。XXL-JOB解决的就是这三件事。它是一个把“调度中心”和“执行器”分离的分布式任务调度平台调度中心负责任务的配置、触发、监控和日志业务侧只需要把一个执行器嵌在应用里接收调度指令并执行对应代码。这样一来定时任务不再绑死在某个服务进程里即使业务应用重启调度中心也会按照既有的任务配置继续触发等执行器重新上线后自动恢复执行。这套架构理解起来其实很简单调度中心像一个大脑只管“什么时候该干什么”业务应用里的执行器像手脚只管“接到指令后具体怎么干”。两者之间通过HTTP接口通信所以执行器天然支持跨语言、跨网络部署这对很多人来说可能没有意识到即便你的业务系统不是Java写的只要能提供一个HTTP接口接收调度请求就能接入XXL-JOB的调度体系。适合谁来参考这篇文章我是按“先理清原理、再动手部署、最后解决线上问题”这条线来写的前两章适合刚接触分布式定时任务、想快速搭一套环境的人后面几章涉及自动注册、分片广播、任务幂等、多版本JDK兼容这些实战问题适合已经跑起来、正在被各种边界情况折磨的开发者。2. 部署之前的三个关键准备2.1 别急着下代码先把环境版本理清楚我第一次部署XXL-JOB时踩过最无脑的坑就是JDK版本。老版本的项目包里源码编译用的还是JDK 8但你本地如果装了高版本JDK像JDK 17这类编译和运行过程中会露出各种兼容性问题。这个项目在JDK 8环境下是最稳定的尤其是2.3.x系列的release版本建议直接拿官方release版本的源码包或者已经打好的发行包来用而不要自己在高版本JDK下从master分支现编译。具体来说XXL-JOB的“调度中心”模块本身是一个独立的Spring Boot应用需要单独部署在一个进程里。你可以把它部署在一台2核4G的小机器上也可以直接部署在已有的应用服务器里只要保证业务应用所在的执行器能够通过网络访问到调度中心就行。另外提醒一点XXL-JOB的release版本号看起来五花八门但从2.3.0到2.4.0再到2.5.0核心调度功能的变化并不大大多数是界面交互和细节功能的优化。如果你的业务诉求是“先把基础调度跑起来”用官方推荐的稳定版本就好没有必要追最新。但如果你在JDK 8环境下部署请确认你下的版本是对应JDK 8的有些较新版本开始要求JDK 8以上的环境变量配置这点我在后面的常见问题章节会专门讲。2.2 数据库准备一张表搞定所有元数据XXL-JOB的调度中心需要一张数据库表来存储任务配置、执行记录、调度日志、执行器注册信息等。官方SQL脚本在源码目录的/doc/db/tables_xxl_job.sql里整个项目只需要这一个库脚本会创建多张表表之间有明确的外键关系。我建议你在正式部署前先专门为XXL-JOB建一个独立数据库账号和实例不要和业务库混在一起。原因有两点其一XXL-JOB的调度日志表增长比较快长时间运行后单表数据量会很大混在业务库会影响业务查询性能其二调度中心本身没有复杂的分布式事务需求它追求的是调度信息的可靠落库独立库能避免业务侧误操作导致核心调度数据损坏。数据库类型支持MySQL、PostgreSQL等主流关系型数据库。我在项目中用的是MySQL 5.7配合InnoDB引擎按官方默认配置就能稳定运行。如果你用MySQL 8.x需要注意连接驱动的版本差异后续我会讲到排查方法。2.3 源码结构看一眼部署心里有底XXL-JOB的工程结构非常经典整个项目可以拆成三块xxl-job-admin调度中心是一个Spring Boot应用打包后就是一个可执行的jar或者war。xxl-job-core核心公共库封装了执行器端的接入SDK业务应用引入这个依赖就能获得执行器的能力。xxl-job-executor-sample-*官方提供的一系列示例执行器工程里面有Spring Boot版本、Spring版本、JFinal版本等对应不同技术栈的接入示范。我的建议是第一次部署时先不要从零写执行器代码直接在示例工程的基础上做加法。因为示例工程把执行器配置、任务Handler的写法、日志输出的规范都整理好了你只需要改动几个配置项再删掉示例任务类替换成自己的业务逻辑就能跑通全链路。3. 部署时你真正要做的事3.1 调度中心的启动和配置调度中心的配置都在application.properties文件里主要包括服务端口、数据库连接信息、登录账号密码这几项。默认端口是8080如果你机器上的8080端口被占了改成别的端口就行。数据库连接配置和普通Spring Boot应用没区别。启动调度中心之前确保数据库脚本已经执行完毕然后直接启动这个Spring Boot应用。启动成功后浏览器访问/xxl-job-admin路径输入默认管理员账号admin/123456登录就能看到调度中心的主界面。这里面有一个很容易被忽略的配置项调度中心自身有一个“调度线程池”的概念它决定了调度中心能够支撑多大的并发调度压力。默认配置是10个线程对于绝大多数中小规模业务系统来说完全够用不需要额外调优。只有当你的调度任务非常密集、每秒触发几十上百次时才需要关注线程池的调整否则动多了反而会引起调度延迟的误判。还有一点调度中心是支持集群部署的也就是多台机器同时跑同一个调度中心应用、连同一个数据库。如果你做的是高可用架构可以在前端加负载均衡调度中心内部的分布式锁会保证同一时间只有一个节点在触发某个任务不会出现重复调度。3.2 执行器的接入逻辑执行器接入时核心是引入xxl-job-core依赖然后在Spring配置里注册一个XxlJobSpringExecutor的Bean。这个Bean需要配置三个关键参数adminAddresses是调度中心的地址列表appname是执行器的应用名port是执行器自身对外提供HTTP服务的端口用来接收调度中心的回调指令。执行器注册这一块需要明确它有两种方式自动注册和手动录入。从2.x版本开始系统默认推荐自动注册也就是执行器启动后主动往调度中心上报自己的IP和端口调度中心会自动维护一个在线执行器列表。这个设计比手动录入方式省心太多你不需要在任务配置里写死执行器的IP新加一台机器、机器迁移、IP变更这些操作对业务透明只要新执行器启动成功它就会自动出现在调度中心的执行器管理列表里。我建议在生产环境使用自动注册但需要给执行器配上固定端口避免因为随机端口导致多个实例注册信息混乱。如果你是多网卡机器还需要指定执行器绑定的IP地址在配置里用xxl.job.executor.ip这个参数显式指定否则可能会注册成内网IP导致调度中心无法访问。3.3 从添加执行器到跑通第一个任务的完整过程登录调度中心后第一步是进入“执行器管理”页面点击新增创建一个执行器。AppName一定要和业务应用里配置的xxl.job.executor.appname保持一致否则执行器无法注册上来。名称和排序随便填不影响功能。第二步是启动你的业务应用。如果配置无误几秒钟后刷新执行器管理页面就能看到该执行器的状态变为“在线”并显示注册的IP和端口。如果一直是“离线”优先检查网络是否能互通调度中心和执行器的端口再检查执行器配置是否完全匹配。第三步是进入“任务管理”页面添加一个任务。关键配置项包括调度类型支持Cron表达式和固定速度触发两种方式。JobHandler对应执行器里某个被XxlJob注解标注的方法名。路由策略决定这次调度下发到哪一台执行器机器上。阻塞处理策略任务执行超时或堆积时怎么处理。失败重试次数。全部配置好之后保存然后在任务列表上点击“执行一次”就能在调度日志里看到任务的执行状态和输出结果。到此一条完整的调度链路已经跑通。4. 核心功能的原理与配置搞懂这些才算会用4.1 自动注册任务原理就是一次心跳上报网上很多人在问“xxl-job自动注册任务”是什么意思其实就是两个层面的能力一是执行器自动注册到调度中心二是任务Handler自动被发现。第二个层面很多人没注意到它靠的是Spring容器启动时扫描带XxlJob注解的方法把方法名和实例注册成一个个可供调度的Handler。所以你不需要像Quartz那样在某个XML或者DB配置里维护一大堆JobDetail和Trigger绑定关系。这带来的一个显著便利是任务代码和服务代码在同一个工程里版本发布时一起上线不会出现“配置改了但代码没发布”“代码改了但配置没同步”这类乱七八糟的问题。我见过不少团队用老的Quartz方案时任务表达式散落各处排查问题时不仅要去代码仓库翻还要去数据库翻而XXL-JOB的全部配置集中在调度中心的后台界面上同一套入口管理所有业务线的任务配置这对运维的友好度是质变。执行器自动注册的心跳逻辑默认是执行器每隔30秒向调度中心上报一次注册信息。实际生产环境里如果发现执行器明明活着但界面上显示离线多半是网络策略拦了调度中心连接执行器IP端口的请求或者执行器端口冲突。这类问题我会在后面专门给出排查建议。4.2 路由策略怎么选不要默认值用到底路由策略是调度中心下发任务时决定从在线执行器列表里选哪些机器来执行的方式。默认是“第一个”也就是每次都挑集群列表里第一台机器。听起来没什么问题但如果第一台机器挂了或者第一台机器的负载明显高于其他机器这种策略就会导致严重倾斜。我个人常用的几个策略如下轮询Round任务交替分发到每一台机器上适合各机器性能接近、任务执行时间相近的普通业务任务。这是我最推荐的兜底策略。一致性哈希同一个任务编号总是落到同一台机器上适合依赖本地缓存、希望减少跨机器状态同步的任务。故障转移Failover调度中心会先检测执行器是否在线主动避开已经宕机的机器然后把任务打到健康节点上适合对单次执行成功率要求高的场景。分片广播一次调度同时通知所有在线机器每台机器拿到相同的分片参数分片序号和总分片数各自处理自己负责的数据分片。这是处理大数据量任务最常用的模式比如一张表有100万条记录要批量处理三台机器分片后每台处理约33万条速度几乎线性提升。我强烈建议每个任务都根据业务特性显式选择路由策略而不是保留默认值。尤其是大任务一旦用默认的“第一个”策略集群中只有一台机器在干活其他机器空转这个坑我见过太多次了。4.3 阻塞处理策略这是防止任务堆成山的核心阻塞处理策略是指任务被触发了但上一次触发还在执行中这一次触发怎么处理。默认情况下是“丢弃后续调度”意思很简单上一次没跑完这次就不跑了等下一次调度再触发。这个策略适合绝大多数准点执行类任务比如每小时整点同步一次数据如果某次执行耗时超过了一个小时那么宁可跳过一次也不要做任何积压。另一种策略是“单机串行”意思是后续调度会排队等待前一个执行完立刻接着执行下一个。这对一些不允许跳过次数的任务很重要比如每5分钟拉取一次交易流水如果拉取过程偶发超时你不能把这次拉取丢了宁可让它排队延迟。但要注意这种策略只对单个执行器机器生效不会跨机器排队所以在多机部署时排队行为是在每台机器上独立发生的。如果任务有堆积迹象我建议先去检查执行耗时和阻塞策略是否匹配而不是盲目调大线程池。很多任务积压的根源是任务本身执行太慢调度侧做得再多也消化不了。4.4 分片广播的典型场景批量数据四倍速处理分片广播是我觉得XXL-JOB最“值钱”的一个功能。它的实现原理是调度中心触发一次任务时把所有在线执行器列表作为参数一并下发每台执行器在接到任务时能得知自己是第几片、总共有多少片。实际开发中遇到批量数据处理我是这样用的假设有200万条用户数据需要跑一遍风控规则我配置一个分片广播任务任务代码大致是这样XxlJob(riskScanJob) public void riskScanJob() { int shardIndex XxlJobHelper.getShardIndex(); int shardTotal XxlJobHelper.getShardTotal(); // 按用户ID取模分片 ListLong userIds userMapper.selectByShard(shardIndex, shardTotal); for (Long userId : userIds) { processUserRisk(userId); } }这里的selectByShard需要你自己在SQL里实现取模或者区间过滤的逻辑。实际运行下来三台机器处理200万条数据总耗时大约是单台机器跑三分之一的时间这是分片广播最直观的收益。分片广播的另一个好处是天然支持执行器的弹性扩缩容新加一台机器调度中心自动把分片总数加一下一次任务触发时就自动按新数量重新分片不需要人工干预。4.5 调度日志与任务告警别等线上出了问题再去看XXL-JOB的调度日志功能覆盖了每个任务的完整生命周期什么时候触发、选中的哪台机器、执行器是否成功接收、执行结果是什么。这个日志是排查问题的第一入口比业务日志要前置得多。我在实际项目里要求每个执行器代码里用XxlJobHelper.log来输出关键步骤日志而不要用普通的logger.info。因为调度中心的日志查看界面是从执行器本地拉取日志的通过普通日志打印的内容不会被收集到调度日志里排查问题时查不到关键业务信息。这个细节在很多文档里都不起眼但遇到线上问题时就特别重要。告警方面任务执行失败后调度中心支持配置任务告警联系人通过邮件或者企业微信机器人推送告警消息。我把告警和分片任务结合使用分片任务中某一片执行失败能通过告警及时暴露。对于没有专职运维的团队来讲告警配置就是那条兜底的安全绳。5. JDK版本选择与常见兼容性问题5.1 JDK 8正确使用XXL-JOB的姿势XXL-JOB在JDK 8环境下最流行的版本是2.2.x到2.3.x之间。官方源码的编译级别默认就是JDK 8所以直接用这系列版本配合JDK 8运行几乎不会遇到编译问题。需要特别注意的是如果你用Spring Boot 2.7以上的版本来集成xxl-job-coreSpring Boot 2.7默认兼容的是JDK 8到JDK 17但xxl-job-core对Servlet API的传递依赖有时候会和Spring Boot的新版本产生冲突。我遇到过的典型报错是ClassNotFoundException涉及javax.servlet还是jakarta.servlet的包名差异。这种问题本质上是Spring Boot 3.x之后把javax换成了jakarta而xxl-job-core老版本还是基于旧包名编译的。所以不要拿着JDK 8就跑Spring Boot 3.x这两者的搭配本身就是矛盾的。如果你确实需要在JDK 11或JDK 17环境下跑调度中心建议先确认两个前提调度中心应用本身能正常编译启动且执行器SDK的HTTP回调接口能正常被访问。JDK 11和JDK 17对XXL-JOB的兼容性比JDK 8要差一些主要体现在某些网络库的反射调用和模块化限制上没有充分测试前不要直接上生产。5.2 日志和内存相关的坑XXL-JOB调度中心在运行一段时间后内存占用会缓慢增长。原因有两方面一是调度日志表的数据累积导致查询变慢容易引起接口超时二是执行器注册信息在内存中的缓存正常情况下很稳定但如果执行器频繁上下线注册中心的缓存清理不及时会导致内存碎片。建议对调度中心所在的JVM设置合理的堆内存并在部署层面加一个日志归档策略。数据库层面也要定期清理过期日志官方提供了一个日志自动清理的接口和界面入口可以配置日志保留天数。我一向建议生产环境保留7天以内的调度日志更长时间的日志导出归档不要长期堆在业务数据库里。5.3 常见的NoClassDefFoundError和版本冲突集成xxl-job-core到自己的业务工程时常见的问题是依赖版本冲突。XXL-JOB内部用了一个比较老的Jetty版本做执行器的内嵌HTTP服务器如果你的业务工程里已经引入了更高版本的Jetty或者引入了Netty等其他网络框架可能会在启动时出现类冲突。这里我的处理经验是一定要用mvn dependency:tree查看依赖树把xxl-job-core相关的冲突依赖排除干净。尤其是xxl-job-core传递依赖的javax.servlet-api和Spring Boot内嵌Tomcat自带的Servlet API保持同一版本即可不要私自升级否则调度回调接口几乎必然报错。6. 常见问题与排查技巧实录6.1 执行器一直显示离线这是最常被问的问题。遇到执行器离线我的排查顺序是先看调度中心的日志确认是否收到执行器的注册请求再看执行器和调度中心之间的网络是否能通尤其是执行器所在服务器防火墙是否放行了执行器端口最后看执行器配置的AppName是否和调度中心创建的执行器AppName一致。这里还有一个很容易被忽略的细节如果你的执行器部署在Docker容器里有可能会因为容器网络模式导致执行器上报的IP是容器内部IP调度中心访问不到。解决方法是给执行器显式指定注册IP用宿主机IP或者在Docker启动时加上--networkhost参数让容器直接使用宿主机网络。6.2 任务触发成功但执行器没有反应任务在调度日志里显示调度成功但执行器侧没有日志输出多半是JobHandler名称匹配出了问题。检查执行器代码里XxlJob注解的名称和任务配置里JobHandler的填写是否完全一致。这里不存在模糊匹配名称错一个字都不可能触发。另外如果执行器应用是多实例部署并且路由策略是“第一个”在所有实例负载均衡的场景下某个实例因为线程池繁忙而拒绝了调度请求也会表现为“没有反应”。这时候需要去任务列表里看看调度结果详情一般会有明确的错误码提示不用从零排查。6.3 任务偶发重复执行XXL-JOB在设计上保证了调度记录不会丢失但在某些极端场景下比如执行器处理完成后回调调度中心时网络中断调度中心超时后会重新触发一次这会导致业务逻辑被重复执行。所以业务侧一定要做幂等处理。我的经验是凡是涉及金额计算、状态流转、外部接口调用的任务在代码里必须设计幂等机制。最简单的做法是给任务处理记录加一个业务唯一键处理前先查重处理成功后再写入记录。有些团队把幂等期望寄托在调度平台的“防重复”能力上这是不现实的所有分布式调度平台都只能保证尽量不重复不能绝对保证不重复。6.4 调度日志表膨胀导致调度中心性能下降在没有配置自动清理的情况下调度日志表会持续膨胀。我遇到过一张表几千万行数据任务列表打开要十几秒的情况。解决办法是启用调度中心自带的日志清理功能在系统管理里配置一个清理周期比如每天凌晨4点执行一次保留最近7天的日志。如果想手动清理也可以直接操作数据库。但注意不要删除正在处理中的调度日志对应的记录否则任务列表的调度状态会不同步。7. 附表XXL-JOB核心配置项速查手册配置项作用推荐配置xxl.job.admin.addresses调度中心地址列表生产环境配置完整地址如http://ip:8080/xxl-job-adminxxl.job.executor.appname执行器AppName与调度中心创建的执行器保持一致xxl.job.executor.ip执行器注册IP多网卡或Docker环境必填避免注册错误xxl.job.executor.port执行器HTTP端口同一台机器多实例时避免端口冲突xxl.job.executor.logpath执行器日志目录务必配置独立目录方便日志收集xxl.job.executor.logretentiondays日志保留天数建议7天看业务诉求调整xxl.job.accessToken调度中心与执行器通信令牌生产环境务必开启防止恶意调度这些配置项在官方示例工程里都有完整注释第一次接入时对着抄就行。需要注意的是accessToken一旦配置调度中心和执行器两边的值必须一致否则任务调度时会被直接拒绝。8. 结尾我踩过的那些坑希望你绕开文章写到这里我不打算做什么总结了就分享几条我个人的实操习惯。第一XXL-JOB真正跑得稳靠的是任务设计而不是平台参数。拿到一个业务任务先分析它是不是允许跳过、允许重复、允许堆积再决定路由策略和阻塞策略这个顺序不能反。如果你的任务代码本身执行耗时超过调度周期那再完美的调度平台也救不了你。第二执行器的日志必须用XxlJobHelper.log输出。刚开始接入时我图省事沿用业务系统的日志框架打印了什么“开始处理订单”“处理完成”这类信息结果线上任务失败后在调度中心看到的日志只有一句“执行成功”本质上什么业务信息都没有排查靠猜效率极低。后来统一改成XxlJobHelper.log输出任务执行的关键节点一目了然。第三新版本固然好但XXL-JOB的老版本在稳定性上已经经过了大量生产环境验证对于大多数团队在新版本发布后至少等待一两个补丁版本再上生产是一个更稳的策略。最后如果你团队里还没有任何分布式任务调度的沉淀XXL-JOB应该是性价比最高的一条入门路径。它不会像很多重量级框架那样把一个简单问题复杂化它的每个功能点都对应着一个真实生产场景。把这篇文章里的配置和排查思路吃透你的分布式定时任务体系大概率能安安稳稳跑很久。
