XXL-Job 分布式任务调度平台从零到一完整配置与集成指南

在分布式系统中定时任务的管理一直是个痛点。传统的单机定时任务在应用水平扩展时容易导致任务重复执行而分散在各服务中的任务又难以统一监控和管理。XXL-Job 作为一款开源的分布式任务调度平台以其轻量级、易用和强大的调度能力成为许多开发者的首选。本文将手把手带你完成 XXL-Job 从零到一的完整配置与集成涵盖调度中心部署、执行器接入、任务配置以及生产环境的最佳实践让你能快速在项目中落地一个稳定可靠的分布式任务调度方案。1. XXL-Job 核心概念与架构解析在开始配置之前理解 XXL-Job 的基本工作原理至关重要这能帮助你在后续遇到问题时快速定位。XXL-Job 是什么XXL-Job 是一个分布式任务调度平台其核心设计目标是开发迅速、学习简单、轻量级、易扩展。它将任务的调度决定何时、在哪个执行器上运行任务与任务的执行具体的业务逻辑代码分离开来通过一个中心化的“调度中心”来管理所有任务的调度逻辑而具体的任务则部署在分布式的“执行器”集群中。核心角色与架构整个系统主要由两部分组成调度中心Admin一个独立部署的 Web 管理平台。负责管理任务信息根据配置的 Cron 表达式发出调度请求并监控执行器的状态和任务的执行结果。它不执行任何业务代码。执行器Executor嵌入到各个业务应用中的组件。它负责接收调度中心的调度请求加载并执行对应的任务处理器JobHandler并将执行结果日志返回给调度中心。一个应用可以包含多个执行器一个执行器下可以注册多个任务处理器。工作流程简述任务配置在调度中心 Web 界面上添加一个任务配置其 Cron 表达式、路由策略、执行器等信息。任务触发调度中心的调度线程根据 Cron 表达式在预定时间触发一次调度。下发请求调度中心通过 RPC默认使用 HTTP向该任务指定的执行器集群中的一台机器发起“执行任务”的请求。执行任务执行器接收到请求后在其线程池中找到一个空闲线程调用对应的JobHandler的execute方法。回调日志任务执行完毕后执行器将执行结果和日志主动回调给调度中心。结果查看用户可以在调度中心的管理界面查看每次调度的执行日志、状态和结果。这种中心化调度、分布式执行的架构完美解决了任务重复执行、统一管理和横向扩展的问题。2. 环境准备与版本说明本文将基于最经典和稳定的组合进行演示。请确保你的开发环境满足以下要求。基础运行环境操作系统Windows 10/11 Linux (如 CentOS 7 Ubuntu 18.04) macOS 均可。本文命令行示例以 Linux/Mac 为主Windows 用户请使用 Git Bash 或 WSL 以获得相似体验。JavaJDK 1.8 或更高版本。推荐使用 JDK 8 或 JDK 11LTS版本。通过java -version命令验证。Maven3.6 版本用于项目构建。通过mvn -v命令验证。IDEIntelliJ IDEA 或 Eclipse本文示例使用 IDEA。数据库调度中心必需MySQL5.7 或 8.0 版本。XXL-Job 调度中心需要数据库来存储任务、日志等元数据。请确保已安装并启动 MySQL 服务并创建一个专用数据库如xxl_job。XXL-Job 版本本文基于XXL-Job 2.4.0版本进行配置。这是目前非常稳定且广泛使用的版本。你可以通过其 GitHub Release 页面获取最新版本但核心配置方式基本一致。项目结构预览我们将创建两个独立的 Spring Boot 项目或模块xxl-job-admin调度中心。xxl-job-executor-sample示例执行器你的业务应用。3. 调度中心部署与配置调度中心是管理后台需要独立部署。我们通过下载官方源码并修改配置来运行。3.1 获取源码与初始化数据库首先从官方仓库获取源码并初始化数据库表。步骤 1下载源码访问 XXL-Job 的 GitHub 仓库https://github.com/xuxueli/xxl-job下载 Release 版本的源码包如xxl-job-2.4.0.zip或直接 Clone 仓库。步骤 2导入数据库脚本解压后在/doc/db目录下找到数据库初始化脚本tables_xxl_job.sql。登录你的 MySQL创建一个数据库例如xxl_job然后执行该 SQL 脚本。-- 登录 MySQL mysql -u root -p -- 创建数据库 CREATE DATABASE IF NOT EXISTS xxl_job DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 使用数据库 USE xxl_job; -- 执行脚本注意替换脚本路径 SOURCE /your/path/to/xxl-job/doc/db/tables_xxl_job.sql;执行成功后会创建以xxl_job_为前缀的若干张表用于存储任务、日志、执行器信息等。3.2 配置调度中心项目源码中的xxl-job-admin模块即是调度中心。我们需要修改其配置文件以连接我们自己的数据库。步骤 1修改 application.properties找到/xxl-job-admin/src/main/resources/application.properties文件关键配置如下# 服务器端口默认为 8080请确保端口未被占用 server.port8080 # 应用上下文路径访问地址会变为 http://ip:port/xxl-job-admin server.servlet.context-path/xxl-job-admin # 数据库连接配置修改为你自己的数据库信息 spring.datasource.urljdbc:mysql://127.0.0.1:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/Shanghai spring.datasource.usernameroot spring.datasource.passwordyour_password spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver # 数据库连接池配置使用HikariCP spring.datasource.typecom.zaxxer.hikari.HikariDataSource spring.datasource.hikari.minimum-idle10 spring.datasource.hikari.maximum-pool-size20 spring.datasource.hikari.auto-committrue spring.datasource.hikari.idle-timeout30000 spring.datasource.hikari.pool-nameHikariCP spring.datasource.hikari.max-lifetime900000 spring.datasource.hikari.connection-timeout30000 spring.datasource.hikari.connection-test-querySELECT 1 # 调度中心通讯TOKEN执行器配置需要与此一致非必填但建议设置以增强安全性 xxl.job.accessTokendefault_token # 国际化默认中文 xxl.job.i18nzh_CN重点说明server.port和context-path决定了调度中心的访问地址。spring.datasource必须修改为你的 MySQL 连接信息。xxl.job.accessToken调度中心和执行器之间的认证令牌如果设置执行器配置必须相同。生产环境建议设置一个复杂的令牌。3.3 编译与启动调度中心配置完成后可以通过 Maven 打包并运行。方式一在 IDE 中直接运行在 IDEA 中找到XxlJobAdminApplication这个启动类直接运行即可。方式二打包成 JAR 部署在项目根目录下执行 Maven 打包命令mvn clean package -Dmaven.test.skiptrue打包完成后在xxl-job-admin/target/目录下会生成xxl-job-admin-2.4.0.jar。通过以下命令启动cd xxl-job-admin/target java -jar xxl-job-admin-2.4.0.jar步骤 4访问与登录启动成功后打开浏览器访问http://localhost:8080/xxl-job-admin。 默认登录账号admin默认登录密码123456登录后你将看到 XXL-Job 的管理后台。首先进入“执行器管理”菜单这是我们下一步配置执行器的关键。4. 执行器集成与配置执行器需要集成到你的业务应用中。我们创建一个新的 Spring Boot 项目来演示。4.1 创建 Spring Boot 项目并引入依赖使用 Spring Initializr 创建一个新项目或直接在现有项目中添加依赖。核心依赖是xxl-job-core。Maven 依赖dependency groupIdcom.xuxueli/groupId artifactIdxxl-job-core/artifactId version2.4.0/version /dependency确保你的项目中已经包含了 Spring Boot Web 等相关基础依赖。4.2 配置执行器参数在application.yml或application.properties中配置执行器。这里以 YAML 为例# application.yml server: port: 8081 # 执行器应用端口 xxl: job: admin: # 调度中心地址多个地址用逗号分隔。非常重要 addresses: http://127.0.0.1:8080/xxl-job-admin # 执行器通讯TOKEN需和调度中心配置的accessToken一致 accessToken: default_token executor: # 执行器AppName在调度中心配置执行器时使用必须唯一 appname: xxl-job-executor-sample # 执行器注册方式address为手动录入ip为自动注册。推荐自动注册。 address: ip: port: 9999 # 执行器端口用于接收调度中心RPC请求。需保证此端口不被占用且可访问。 # 执行器日志路径用于存储任务执行日志 logpath: /data/applogs/xxl-job/jobhandler # 日志保留天数 logretentiondays: 30配置项详解xxl.job.admin.addresses必须正确配置为你的调度中心地址。如果调度中心集群部署这里可以配置多个用逗号分隔。xxl.job.executor.appname执行器的唯一标识调度中心通过这个名称来找到对应的执行器集群。xxl.job.executor.port执行器内置的 Netty 服务端口用于接收调度命令。确保该端口开放且未被占用。xxl.job.executor.logpath任务执行日志的本地存储路径。调度中心查看日志时执行器会从此路径读取文件返回。4.3 编写 XxlJobConfig 配置类需要创建一个配置类将上述配置文件中的属性注入到 XXL-Job 的 Spring Bean 中。package com.yourcompany.executor.config; import com.xxl.job.core.executor.impl.XxlJobSpringExecutor; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class XxlJobConfig { private Logger logger LoggerFactory.getLogger(XxlJobConfig.class); Value(${xxl.job.admin.addresses}) private String adminAddresses; Value(${xxl.job.accessToken}) private String accessToken; Value(${xxl.job.executor.appname}) private String appname; Value(${xxl.job.executor.address}) private String address; Value(${xxl.job.executor.ip}) private String ip; Value(${xxl.job.executor.port}) private int port; Value(${xxl.job.executor.logpath}) private String logPath; Value(${xxl.job.executor.logretentiondays}) private int logRetentionDays; Bean public XxlJobSpringExecutor xxlJobExecutor() { logger.info( xxl-job config init.); XxlJobSpringExecutor xxlJobSpringExecutor new XxlJobSpringExecutor(); xxlJobSpringExecutor.setAdminAddresses(adminAddresses); xxlJobSpringExecutor.setAppname(appname); xxlJobSpringExecutor.setAddress(address); xxlJobSpringExecutor.setIp(ip); xxlJobSpringExecutor.setPort(port); xxlJobSpringExecutor.setAccessToken(accessToken); xxlJobSpringExecutor.setLogPath(logPath); xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays); return xxlJobSpringExecutor; } }这个类的作用是将配置文件中的属性值设置到XxlJobSpringExecutor这个核心执行器 Bean 中。当 Spring 容器启动时这个执行器会自动向配置的调度中心地址进行注册。4.4 开发第一个任务处理器JobHandler任务处理器是具体执行业务逻辑的地方。我们创建一个简单的示例。package com.yourcompany.executor.jobhandler; import com.xxl.job.core.context.XxlJobHelper; import com.xxl.job.core.handler.annotation.XxlJob; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; import java.util.concurrent.TimeUnit; Component public class SampleXxlJob { private static Logger logger LoggerFactory.getLogger(SampleXxlJob.class); /** * 1. 简单示例任务 * 通过 XxlJob 注解声明一个任务处理器。 * 注解 value 对应调度中心新增任务时填写的 “JobHandler” 字段。 */ XxlJob(demoJobHandler) public void demoJobHandler() throws Exception { // 通过 XxlJobHelper 获取任务参数 String param XxlJobHelper.getJobParam(); XxlJobHelper.log(XXL-JOB, Hello World. Param: {}, param); for (int i 0; i 5; i) { XxlJobHelper.log(beat at: i); TimeUnit.SECONDS.sleep(2); } // 默认返回成功无需调用 setXxlJobCode // 若需失败可调用 XxlJobHelper.handleFail(失败信息); } /** * 2. 分片广播任务示例 * 适用于需要处理大量数据且可以并行分片处理的场景。 */ XxlJob(shardingJobHandler) public void shardingJobHandler() throws Exception { // 分片参数 int shardIndex XxlJobHelper.getShardIndex(); // 当前分片序号从0开始 int shardTotal XxlJobHelper.getShardTotal(); // 总分片数 XxlJobHelper.log(分片参数当前分片序号 {}, 总分片数 {}, shardIndex, shardTotal); // 模拟处理数据实际业务中可根据分片参数查询不同范围的数据 // 例如SELECT * FROM order WHERE status0 LIMIT 100 OFFSET {shardIndex * 100} // 每个分片处理自己那部分数据 ListOrder orderList orderService.findPendingOrders(shardIndex, shardTotal); for (Order order : orderList) { // 处理订单... processOrder(order); } XxlJobHelper.log(分片【{}】处理完成共处理 {} 条数据, shardIndex, orderList.size()); } }关键点解析XxlJob(“demoJobHandler”)注解定义任务处理器的名称调度中心通过此名称关联。XxlJobHelper工具类用于在任务内部获取参数、分片信息、记录日志、设置执行结果。XxlJobHelper.log()记录的执行日志可以在调度中心的“调度日志”中查看非常重要是排查任务执行情况的主要依据。分片广播这是 XXL-Job 的高级特性。当你在调度中心对一个任务选择“分片广播”路由策略时调度中心会向集群中的所有执行器实例发送调度请求并通过getShardIndex()和getShardTotal()告知每个实例其分片信息从而实现数据的并行处理。5. 调度中心任务配置实战执行器启动并成功注册后可以在调度中心“执行器管理”页面看到在线机器地址就可以在调度中心配置任务了。5.1 配置执行器进入调度中心 Web 控制台点击进入“执行器管理”。点击“新增”按钮。填写表单AppName必须与执行器配置文件中的xxl.job.executor.appname完全一致例如xxl-job-executor-sample。名称执行器的展示名称可自定义例如“示例业务执行器”。注册方式自动注册执行器启动后自动向调度中心注册其 IP 和端口。推荐此方式只需填写AppName即可。手动录入需要手动填写执行器的地址如127.0.0.1:9999适用于网络隔离等特殊场景。机器地址如果选择“手动录入”在此填写。自动注册则留空。点击保存。稍等片刻如果执行器已启动且网络连通在下方“OnLine 机器地址”列表中应该能看到你的执行器实例例如127.0.0.1:9999。5.2 创建并配置任务进入“任务管理”菜单点击“新增”。填写任务配置信息这是核心步骤执行器选择上一步创建的执行器xxl-job-executor-sample。任务描述自定义如“测试简单任务”。路由策略当执行器集群部署时决定任务被下发到哪台机器。常用策略FIRST第一个选择第一个注册的执行器。ROUND轮询依次选择。RANDOM随机随机选择。CONSISTENT_HASH一致性哈希根据任务ID哈希选择。SHARDING_BROADCAST分片广播向所有执行器广播用于并行处理。需要任务代码支持分片逻辑。Cron任务的触发时间表达式如0/30 * * * * ?表示每30秒执行一次。运行模式选择BEAN。JobHandler必须与XxlJob注解中定义的 value完全一致例如demoJobHandler。任务参数可选字符串类型。可以在任务代码中通过XxlJobHelper.getJobParam()获取。阻塞处理策略当同一个任务在前一次调度未执行完时本次调度的处理策略。SERIAL_EXECUTION单机串行排队等待。DISCARD_LATER丢弃后续调度直接忽略本次调度。COVER_EARLY覆盖之前调度终止正在运行的任务执行新的。子任务ID可选本任务执行成功后会自动触发对应ID的子任务。任务超时时间单位秒超时未完成则标记为失败。失败重试次数任务失败后自动重试的次数。点击保存。5.3 启动与测试任务在任务列表的操作列点击对应任务的“操作”按钮选择“启动”。任务状态变为“运行中”。等待 Cron 表达式触发或直接点击“执行一次”进行手动测试。点击任务右侧的“日志”按钮可以查看该任务的历史调度记录和每次执行的详细日志即代码中XxlJobHelper.log()输出的内容。如果日志显示执行成功并且能看到你代码中打印的 “XXL-JOB, Hello World” 等信息恭喜你第一个 XXL-Job 任务已经配置成功6. 常见问题与排查思路在实际配置和使用过程中你可能会遇到以下问题。这里提供一个排查清单。问题现象可能原因排查步骤与解决方案调度中心无法启动1. 端口被占用。2. 数据库连接失败。3. 数据库表未初始化。1. 检查server.port使用netstat -an | grep 8080查看端口占用。2. 检查application.properties中的数据库 URL、用户名、密码。3. 确认已执行tables_xxl_job.sql脚本。查看启动日志中的错误信息。执行器启动后调度中心“执行器管理”看不到在线机器1. 网络不通。2.appname不匹配。3. 执行器配置的调度中心地址错误。4. 执行器端口被占用或防火墙拦截。1. 互相 ping 或 telnet 检查网络。2. 核对执行器配置文件中的appname和调度中心录入的是否完全一致包括大小写。3. 核对执行器配置的admin.addresses地址是否正确、完整包含上下文路径/xxl-job-admin。4. 检查执行器配置的port默认9999是否被其他进程占用防火墙是否放行。查看执行器启动日志看是否有注册成功的消息。任务触发后调度日志显示“任务结果丢失任务标记为失败”1. 执行器未启动或宕机。2. 执行器处理任务超时。3. 网络问题导致回调失败。4.JobHandler名称不匹配。1. 确认执行器应用正在运行。2. 检查任务代码是否有死循环或长时间阻塞适当调整任务超时时间。3. 检查网络连通性。4.重点检查调度中心任务配置的 “JobHandler” 字段是否与执行器代码中XxlJob(“xxx”)注解内的名称完全一致。任务执行日志为空或看不到自定义日志1. 执行器logpath配置错误或目录无权限。2. 任务代码中未使用XxlJobHelper.log()打印日志。1. 检查执行器配置的logpath目录是否存在应用是否有读写权限。2. 确保业务代码中使用XxlJobHelper.log()而非仅用System.out.println或logger.info后者只在执行器本地控制台输出不会回传调度中心。分片广播任务不生效1. 路由策略未选择“分片广播”。2. 任务代码中未获取分片参数进行逻辑处理。1. 在调度中心任务配置中将“路由策略”改为“SHARDING_BROADCAST”。2. 在任务处理器方法中必须调用XxlJobHelper.getShardIndex()和getShardTotal()来实现分片逻辑。通用排查命令查看日志这是最重要的手段。仔细查看调度中心和执行器应用的控制台输出或日志文件。检查注册表在调度中心数据库的xxl_job_registry表中可以看到所有在线的执行器实例。手动触发测试在调度中心对任务点击“执行一次”观察日志流比等待 Cron 触发更高效。7. 生产环境最佳实践与进阶配置将 XXL-Job 用于生产环境需要考虑更多关于高可用、安全、性能和可维护性的因素。7.1 高可用部署调度中心集群调度中心是无状态的可以部署多个实例通过 Nginx 等负载均衡器对外提供统一服务。多个调度中心实例连接同一个数据库即可。执行器配置的admin.addresses应填写负载均衡器的地址或所有调度中心地址逗号分隔。执行器集群业务应用执行器可以水平部署多个实例。调度中心会根据配置的路由策略将任务下发到集群中的某一台或全部分片广播机器上执行从而实现负载均衡和故障转移。7.2 安全与权限修改默认密码部署后第一时间修改调度中心 admin 用户的默认密码。配置 AccessToken在生产环境中务必在调度中心和所有执行器中配置复杂且一致的accessToken防止未经授权的执行器注册和任务调度。网络隔离尽量将调度中心部署在内网通过防火墙限制外网访问。执行器与调度中心之间的通信默认9999端口和8080端口应保证网络通畅。数据库安全为 XXL-Job 数据库使用独立的、权限受限的用户并定期备份。7.3 任务配置与管理规范任务描述清晰在创建任务时填写清晰的任务描述、负责人信息便于后续维护。合理设置超时与重试根据任务实际执行时间设置合理的“任务超时时间”。对于可能因网络抖动等短暂失败的任务设置“失败重试次数”通常1-3次。谨慎使用“阻塞处理策略”对于执行时间不确定的长任务慎重选择COVER_EARLY覆盖早期调度策略以免导致数据不一致。对于核心任务SERIAL_EXECUTION串行更安全。启用任务告警在调度中心“任务管理”中可以为任务配置“告警邮箱”。当任务调度失败时会自动发送邮件通知负责人。7.4 监控与运维关注调度日志定期查看调度中心的“调度日志”关注失败的任务。监控执行器状态在“执行器管理”页面监控执行器的在线状态。机器地址变红表示失联。日志文件管理配置合理的logretentiondays日志保留天数定期清理或归档旧的执行日志文件防止磁盘占满。数据库性能xxl_job_log表会随着时间增长数据量过大可能影响查询速度。可以考虑对旧日志进行归档或清理。XXL-Job 调度中心提供了“日志报告”功能可以自动清理。7.5 配置文件分离在生产环境中不应将数据库密码等敏感信息硬编码在application.properties中。应使用 Spring Boot 的 Profile 功能或配置中心如 Apollo、Nacos来管理不同环境dev/test/prod的配置。示例使用 application-prod.yml# application-prod.yml xxl: job: admin: addresses: http://prod-scheduler.yourcompany.com/xxl-job-admin accessToken: ${XXL_JOB_ACCESS_TOKEN:your_strong_prod_token} # 从环境变量读取 executor: appname: order-service-prod port: 19999 logpath: /opt/app/logs/xxl-job通过java -jar your-app.jar --spring.profiles.activeprod来激活生产环境配置。完成以上全部配置和优化后你的 XXL-Job 分布式任务调度平台就已经具备了在生产环境稳定运行的能力。从简单的定时任务到复杂的分片数据处理它都能提供可靠的支持。记住清晰的日志、合理的监控和规范的配置管理是保障任何中间件稳定运行的基石。