XXL-JOB - 分布式任务调度平台新手入门指南

项目概览

* 项目名称* ：XXL-JOB 组织：xuxueli0323

语言：Java Gitee仓库 ：https://gitee.com/xuxueli0323/xxl-job^\[1\]^ 官网：https://www.xuxueli.com/xxl-job/^\[2\]^ 开源协议：GPLv3

项目简介

XXL-JOB 是一个分布式任务调度平台，其核心设计目标是 开发迅速、学习简单、轻量级、易扩展 。现已开放源代码并接入多家公司线上产品线，开箱即用。

核心价值

简单：支持通过 Web 页面对任务进行 CRUD 操作，一分钟上手 - 动态：支持动态修改任务状态、启动/停止任务，即时生效 - 高可用 ：调度中心支持集群部署，执行器支持分布式部署 - 易扩展 ：支持分片广播、故障转移等高级特性

核心功能特性

1. 调度管理

✅ Cron 触发 - ✅ 固定间隔触发 - ✅ 固定延时触发 - ✅ API（事件）触发 - ✅ 父子任务触发

2. 执行器管理

✅ 自动注册 - ✅ 手动录入 - ✅ 弹性扩容缩容 - ✅ 故障转移

3. 任务类型

✅ Bean 模式任务 - ✅ GLUE 模式任务（在线编辑代码） - ✅ 脚本任务（Shell、Python、PHP等） - ✅ 命令行任务

4. 高级特性

✅ 分片广播任务 - ✅ 任务超时控制 - ✅ 任务失败重试 - ✅ 任务失败告警 - ✅ 任务进度监控

5. 运维管理

✅ Rolling 实时日志 - ✅ 运行报表 - ✅ 用户管理 - ✅ 权限控制 - ✅ 审计日志

6. AI 任务

✅ 原生提供 AI 执行器 - ✅ 内置多个 AI 任务 Handler - ✅ 支持 spring-ai、ollama、dify 集成

技术架构

go 复制代码

┌─────────────────────────────────────────────────────────────┐│                      XXL-JOB                              │├─────────────────────────────────────────────────────────────┤│  调度中心 (Admin)                                          ││  ├── 任务管理                                              ││  ├── 执行器管理                                            ││  ├── 日志管理                                              ││  └── 用户管理                                              │├─────────────────────────────────────────────────────────────┤│  执行器 (Executor)                                         ││  ├── Bean 模式                                            ││  ├── GLUE 模式                                            ││  ├── 脚本模式                                             ││  └── 命令行模式                                           │├─────────────────────────────────────────────────────────────┤│  通信协议                                                  ││  └── RESTful API + 数据加密                               │└─────────────────────────────────────────────────────────────┘

适用场景

🌟 典型应用场景

🎯 目标用户

Java 后端开发者 - 需要定时任务调度的系统 - 微服务架构团队

学习曲线

难度评估

简单 ⭐

•一分钟上手，文档详细

优势

文档完善

•官方文档详细 2. 社区活跃 •多家公司使用 3. 开箱即用 •部署简单 4. 功能丰富•满足大部分场景

前置知识

Java 基础 - Spring Boot 基础 - Cron 表达式

快速开始

1. 环境要求

依赖	版本要求
JDK	1.8+
Maven	3.6+
MySQL	5.7+

2. 下载与初始化

bash 复制代码

## 克隆项目gitclonehttps://gitee.com/xuxueli0323/xxl-job.git
## 初始化数据库## 执行 doc/db/tables_xxl_job.sql

3. 配置调度中心

修改 xxl-job-admin/src/main/resources/application.properties ：

properties 复制代码

## 数据库配置spring.datasource.url=jdbc:mysql://localhost:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghaispring.datasource.username=rootspring.datasource.password=password
## 调度中心通讯TOKEN [选填]：非空时启用；xxl.job.accessToken=

4. 启动调度中心

bash 复制代码

## 编译mvncleanpackage
## 启动java-jarxxl-job-admin/target/xxl-job-admin.jar

5. 访问调度中心

打开浏览器访问： http://localhost:8080/xxl-job-admin

默认账号： admin / 123456

6. 创建执行器项目

xml 复制代码

<!-- Maven 依赖 --><dependency><groupId>com.xuxueli</groupId><artifactId>xxl-job-core</artifactId><version>2.4.2</version></dependency>

7. 配置执行器

properties 复制代码

## 执行器通讯TOKEN [选填]：非空时启用；xxl.job.accessToken=
## 执行器注册 [选填]：优先使用该配置作为注册地址；xxl.job.executor.address=
## 执行器APPNAME [选填]：执行器心跳注册分组依据；xxl.job.executor.appname=xxl-job-executor-sample
## 执行器注册 [选填]：优先使用该配置作为注册地址；xxl.job.executor.ip=
## 执行器端口号 [选填]：小于等于0则自动获取；xxl.job.executor.port=9999
## 执行器运行日志文件存储路径 [选填]；xxl.job.executor.logpath=/data/applogs/xxl-job/jobhandler
## 执行器日志文件保存天数 [选填]；xxl.job.executor.logretentiondays=30

8. 开发任务

java 复制代码

@ComponentpublicclassSampleXxlJob {
    @XxlJob("demoJobHandler")publicvoiddemoJobHandler() throwsException {XxlJobHelper.log("XXL-JOB, Hello World.");
// 业务逻辑for (inti=0; i <5; i++) {XxlJobHelper.log("beat at:"+ i);TimeUnit.SECONDS.sleep(2);        }
// 默认返回成功    }}

分片广播任务

java 复制代码

@XxlJob("shardingJobHandler")publicvoidshardingJobHandler() throws Exception {// 分片参数intshardIndex=XxlJobHelper.getShardIndex();intshardTotal=XxlJobHelper.getShardTotal();
XxlJobHelper.log("分片参数：当前分片序号 = {}, 总分片数 = {}", shardIndex, shardTotal);
// 业务逻辑// 根据 shardIndex 和 shardTotal 处理数据}

常见问题

Q1: 如何处理任务执行失败？

解决方案 ： 1. 配置失败重试次数 2. 配置失败告警邮件 3. 在代码中捕获异常并处理

Q2: 如何动态调整任务执行时间？

解决方案 ：通过调度中心 Web 界面修改 Cron 表达式

Q3: 如何查看任务执行日志？

解决方案 ：通过调度中心「执行日志」菜单查看

Q4: 如何实现任务链？

解决方案 ：配置子任务依赖，父任务执行成功后自动触发子任务

学习资源

官方资源

🌐 官网：https://www.xuxueli.com/xxl-job/^\[3\]^ - 📖 文档：https://www.xuxueli.com/xxl-job/^\[4\]^ - 💬 社区：https://www.xuxueli.com/page/community.html^\[5\]^ - 🐳 Docker： docker pull xuxueli/xxl-job-admin

项目推荐指数

维度	评分
易用性	⭐⭐⭐⭐⭐
活跃度	⭐⭐⭐⭐⭐
实用性	⭐⭐⭐⭐⭐

学习价值
⭐⭐⭐⭐⭐	提高开发效率

社区支持
⭐⭐⭐⭐⭐	文档完善，社区活跃

综合推荐指数 ：⭐⭐⭐⭐⭐ 强烈推荐！

适用人群总结

✅ 最适合

需要定时任务调度的系统 - 微服务架构团队 - 需要分布式任务调度

⚠️ 不适合

简单的单机定时任务（推荐使用 Spring @Scheduled）

结语

XXL-JOB 是一款非常优秀的分布式任务调度平台，功能丰富，使用简单，是 Java 开发者必备的工具之一。

对于需要定时任务调度的系统来说，XXL-JOB 是一个非常值得推荐的选择！

报告生成时间：2026年5月 数据来源：Gitee 官方数据

References

[1]: https://gitee.com/xuxueli0323/xxl-job
[2]: https://www.xuxueli.com/xxl-job/
[3]: https://www.xuxueli.com/xxl-job/
[4]: https://www.xuxueli.com/xxl-job/
[5]: https://www.xuxueli.com/page/community.html

XXL-JOB - 分布式任务调度平台新手入门指南