XXL-JOB v2.5.0 详细使用指南：从零搭建到任务开发

XXL-JOB 是一个轻量级分布式任务调度平台核心设计是调度中心Admin与执行器Executor分离调度中心负责任务的管理和触发执行器负责接收调度请求并执行业务代码。下面从零开始一步步说明如何使用 v2.5.0。一、部署调度中心Admin1.1 获取源码从官方仓库下载源码# GitHubgitclone https://github.com/xuxueli/xxl-job.git# 或 Gitee国内更快gitclone https://gitee.com/xuxueli0323/xxl-job.git项目结构说明xxl-job-admin调度中心需要部署xxl-job-core公共核心依赖执行器引入xxl-job-executor-samples执行器示例代码doc/db/tables_xxl_job.sql数据库初始化脚本1.2 初始化数据库执行doc/db/tables_xxl_job.sql脚本会生成 8 张表表名用途xxl_job_lock任务调度锁表分布式调度协调xxl_job_group执行器信息表xxl_job_info任务扩展信息表xxl_job_log调度日志表xxl_job_log_report调度日志报表xxl_job_logglueGLUE 模式日志版本回溯xxl_job_registry执行器注册表xxl_job_user系统用户表1.3 修改配置文件编辑xxl-job-admin/src/main/resources/application.properties必须修改以下配置# 1. 数据库连接必须修改 spring.datasource.urljdbc:mysql://your-host:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/ShanghaiuseSSLfalse spring.datasource.usernameyour-username spring.datasource.passwordyour-password spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver # 2. AccessToken生产环境必须修改为复杂随机字符串 xxl.job.accessTokenyour-production-token # 3. 可选日志保留天数 xxl.job.logretentiondays30 # 4. 可选线程池大小 xxl.job.triggerpool.fast.max200 xxl.job.triggerpool.slow.max1001.4 启动调度中心直接运行XxlJobAdminApplication类的 main 方法。访问http://localhost:8080/xxl-job-admin默认用户名/密码admin/123456。登录后可以看到以下功能模块运行报表调度中心首页整体运行情况任务管理配置任务的地方最常用调度日志所有任务调度记录执行器管理管理注册上来的执行器用户管理多账号管理二、搭建执行器Executor2.1 引入依赖在业务项目的pom.xml中添加dependencygroupIdcom.xuxueli/groupIdartifactIdxxl-job-core/artifactIdversion2.5.0/version/dependency2.2 配置执行器在application.yml或application.properties中配置# 调度中心地址集群用逗号分隔多个 xxl.job.admin.addresseshttp://localhost:8080/xxl-job-admin # 执行器名称唯一标识 xxl.job.executor.appnamexxl-job-executor-demo # 执行器端口默认9999生产建议修改 xxl.job.executor.port9999 # AccessToken必须与调度中心一致 xxl.job.accessTokenyour-production-token # 日志路径 xxl.job.executor.logpath/data/applogs/xxl-job/jobhandler # 日志保留天数 xxl.job.executor.logretentiondays302.3 初始化执行器 Bean创建配置类初始化XxlJobSpringExecutorimportcom.xxl.job.core.executor.impl.XxlJobSpringExecutor;importorg.slf4j.Logger;importorg.slf4j.LoggerFactory;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;ConfigurationpublicclassXxlJobConfig{privateLoggerloggerLoggerFactory.getLogger(XxlJobConfig.class);Value(${xxl.job.admin.addresses})privateStringadminAddresses;Value(${xxl.job.executor.appname})privateStringappname;Value(${xxl.job.executor.port})privateintport;Value(${xxl.job.accessToken})privateStringaccessToken;Value(${xxl.job.executor.logpath})privateStringlogPath;Value(${xxl.job.executor.logretentiondays})privateintlogRetentionDays;BeanpublicXxlJobSpringExecutorxxlJobExecutor(){logger.info( xxl-job config init.);XxlJobSpringExecutorexecutornewXxlJobSpringExecutor();executor.setAdminAddresses(adminAddresses);executor.setAppname(appname);executor.setPort(port);executor.setAccessToken(accessToken);executor.setLogPath(logPath);executor.setLogRetentionDays(logRetentionDays);returnexecutor;}}2.4 启动执行器启动业务应用后执行器会自动向调度中心注册。登录调度中心后台在执行器管理页面应该能看到注册上来的执行器信息。三、编写任务代码BEAN 模式生产环境强烈推荐使用 BEAN 模式而不是 GLUE 模式。BEAN 模式的代码在业务项目中可以进行版本控制和 Code Review更加安全可控。3.1 简单任务示例importcom.xxl.job.core.context.XxlJobHelper;importcom.xxl.job.core.handler.annotation.XxlJob;importorg.slf4j.Logger;importorg.slf4j.LoggerFactory;importorg.springframework.stereotype.Component;ComponentpublicclassSampleXxlJob{privatestaticLoggerloggerLoggerFactory.getLogger(SampleXxlJob.class);/** * 简单任务示例 * 注解中的 demoJobHandler 是任务标识在调度中心配置时需要用到 */XxlJob(demoJobHandler)publicvoiddemoJobHandler()throwsException{XxlJobHelper.log(XXL-JOB, Hello World.);// 获取任务参数在调度中心配置时填写StringjobParamXxlJobHelper.getJobParam();XxlJobHelper.log(任务参数: {},jobParam);for(inti0;i5;i){XxlJobHelper.log(beat at: {},i);Thread.sleep(2000);}// 默认返回 SUCCESS}}3.2 分片广播任务示例当执行器集群部署时使用分片广播路由策略可以让每个节点处理一部分数据提高处理效率。importcom.xxl.job.core.context.XxlJobHelper;importcom.xxl.job.core.handler.annotation.XxlJob;importorg.springframework.stereotype.Component;ComponentpublicclassShardingJob{XxlJob(shardingJobHandler)publicvoidshardingJobHandler()throwsException{// 获取分片参数intshardIndexXxlJobHelper.getShardIndex();// 当前分片序号从0开始intshardTotalXxlJobHelper.getShardTotal();// 总分片数XxlJobHelper.log(分片参数当前分片序号 {}, 总分片数 {},shardIndex,shardTotal);// 业务逻辑根据分片参数查询数据// 例如从数据库查询 order_id % shardTotal shardIndex 的数据// 每个节点只处理自己分片的数据避免重复处理for(inti0;ishardTotal;i){if(ishardIndex){XxlJobHelper.log(第 {} 片命中分片开始处理,i);// 执行具体业务逻辑...}else{XxlJobHelper.log(第 {} 片忽略,i);}}}}分片广播适用场景海量数据处理、日志分析、订单批量处理等需要并行提升效率的场景。四、在调度中心配置任务登录调度中心后台进入任务管理页面点击新增。4.1 填写任务信息配置项说明示例执行器选择注册上来的执行器xxl-job-executor-demo任务描述任务名称测试任务负责人任务负责人admin调度类型CRON / 固定速度CRONCron 表达式定时调度规则0/10 * * * * ?每10秒执行一次Cron 表达式常用示例0 0 0 * * ?每天0点触发0 30 10 * * ?每天10点30分触发0 0/5 * * * ?每5分钟触发0 0/10 * * * ?每10分钟触发4.2 配置执行参数配置项说明运行模式选择BEAN模式生产推荐JobHandler填写XxlJob注解中的名称如demoJobHandler任务参数执行时传入的参数代码中通过XxlJobHelper.getJobParam()获取路由策略见下文路由策略说明阻塞处理策略调度超时或任务执行过慢时的处理方式4.3 路由策略说明执行器集群部署时需要选择路由策略决定任务由哪个节点执行路由策略说明适用场景FIRST固定选择第一个执行器不推荐生产使用LAST固定选择最后一个执行器不推荐生产使用ROUND轮询选择在线执行器无状态任务负载均衡RANDOM随机选择在线执行器无状态任务CONSISTENT_HASH一致性 HASH同一任务固定同一台机器有状态任务需缓存本地数据FAILOVER故障转移按顺序心跳检测第一个成功的执行关键任务高可用BUSYOVER忙碌转移按顺序空闲检测第一个空闲的执行高负载场景SHARDING_BROADCAST分片广播所有执行器执行传递分片参数海量数据并行处理五、测试与查看日志5.1 手动触发任务在任务管理页面点击任务的操作列选择执行一次。在弹出的对话框可以填写执行参数也可以指定某台 IP 执行方便 Debug。5.2 查看执行日志执行完成后点击查看日志可以查看调度记录和任务执行日志。日志会显示调度时间、调度结果执行器地址、执行结果代码中通过XxlJobHelper.log()输出的业务日志六、生产环境检查清单检查项说明☐ AccessToken 已配置且非默认值生产必须修改☐ 调度中心与执行器 Token 一致否则注册失败☐ 数据库连接信息已修改使用生产数据库☐ 执行器端口非默认 9999避免冲突☐ 使用 BEAN 模式而非 GLUE 模式安全可控☐ 路由策略已按业务需求选择集群环境必须考虑☐ 阻塞处理策略已配置防止任务堆积参考资料官方文档https://www.xuxueli.com/xxl-job/源码地址https://github.com/xuxueli/xxl-job国内镜像https://gitee.com/xuxueli0323/xxl-job发布日期2026-08-10