首页教程行业资讯正文

XXL-JOB安装与使用详细教程

uncle 行业资讯 2025年08月6日

0 收藏 0 点赞 149 浏览 6834 个字

摘要 :

文章目录前言一、XXL-JOB安装教程 1.执行命令下载源码。 2.本地数据库执行sql 3. 修改application.properties配置文件 4.修改报警邮件和accessToken（可选配置） 5. ……

文
章
目
录

前言
一、XXL-JOB安装教程

1.执行命令下载源码。
2.本地数据库执行sql
3. 修改application.properties配置文件
4.修改报警邮件和accessToken（可选配置）
5. 启动xxl–job-admin
6. 打包成jar包上传服务器（按需使用，当前教程为本地部署）

二、客户端配置连接

1. 创建一个SpringBoot项目（此处自行创建）。
2. yaml文件配置
3. 创建启动配置文件
4. 在xxl-job-admin中创建执行器
5. 启动客户端项目

三、编写一个定时任务调度

1. 创建一个任务调度
2. xxl-job-admin中添加任务
3. 执行任务
4.定制化拦截器

四、总结

本文主要讲解关于XXL-JOB安装及使用教程（保姆级教程）相关内容，让我们来一起学习下吧！

前言

本文主要讲解分布式调度中心XXL-JOB的安装及使用教程，从0到1，图文并茂的保姆级教程。

XXL-JOB是一个可以在WEB界面配置执行定时任务中间件，支持分布式服务调用，XXL-JOB自身也可以部署多个节点组成集群，本身是一个基于SpringBoot的Java WEB程序，我们可以通过下载GitHub源码进行部署。

一、XXL-JOB安装教程

进入XXL-JOB官网，下方的README.md文件讲述了XXL的功能。

1.执行命令下载源码。

git clone git@github.com:xuxueli/xxl-job.git

通过idea打开后目录如下：

我们先打开doc/db/tables_xxl_job.sql文件，里面有创建数据库的建表语句。

2.本地数据库执行sql

执行后得到如下几张表

3. 修改application.properties配置文件

打开xxl-job-admin/src/main/resources下的application.properties配置文件。

修改数据库配置：

### xxl-job, datasource
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

将数据库信息配置为你本地的账户密码。

4.修改报警邮件和accessToken（可选配置）

spring.mail.host=smtp.qq.com
spring.mail.port=25
spring.mail.username=xxx@qq.com
spring.mail.from=xxx@qq.com
spring.mail.password=xxx

### xxl-job, access token
xxl.job.accessToken=c9%a16ft#pQoQH2X^ElMyzLyox9o2$dX

accessToken用于客户端连接时可配置的token。

5. 启动xxl-job-admin

运行xxl-job-admin/src/main/java包下的XxlJobAdminApplication的main()方法，实际为一个springboot项目，启动后即运行一个web程序。

启动成功后会打印日志：

11:45:13.937 logback [main] INFO  o.s.b.w.e.tomcat.TomcatWebServer - Tomcat started on port(s): 8080 (http) with context path \'/xxl-job-admin\'
11:45:13.947 logback [main] INFO  c.x.job.admin.XxlJobAdminApplication - Started XxlJobAdminApplication in 1.627 seconds (JVM running for 2.054)
11:45:18.005 logback [xxl-job, admin JobScheduleHelper#scheduleThread] INFO  c.x.j.a.c.thread.JobScheduleHelper - >>>>>>>>> init xxl-job admin scheduler success.

在浏览器中访问http://localhost:8080/xxl-job-admin/toLogin ，出现如下页面，默认登录账户：admin, 密码123456，第一次登录成功后请修改密码。

6. 打包成jar包上传服务器（按需使用，当前教程为本地部署）

在xxl-job根目录下创建自动化部署脚本，admin.sh（mac）,windows为admin.bat

git pull

mvn clean -U package -pl xxl-job-admin

scp -rp  xxl-job-admin/target/*.jar root@10.10.1.101:/opt/xxl-job

echo \"开始重启xxl-job\"
ssh root@10.10.1.101 \'bash -s\' <<ENDSSH
pgrep -f xxl-job | xargs --no-run-if-empty kill -9
sleep 5
nohup /usr/local/jdk11/bin/java -Xms512m -Xmx1024m -jar /opt/xxl-job/*.jar >/dev/null 2>&1 &
exit
ENDSSH

上述命令将打包xxl-job-admin为jar包并上传至10.10.1.101服务器下的/opt/xxl-job目录，并远程执行脚本，杀死原有进程并重新启动服务。

二、客户端配置连接

1. 创建一个SpringBoot项目（此处自行创建）。

引入maven依赖

<!-- xxl job -->
<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>2.4.0</version>
</dependency>

2. yaml文件配置

xxl:
  job:
    executor:
      appname: ${spring.application.name}
      logpath: ${spring.application.name}/xxl-job
      logretentiondays: 30
    admin:
      addresses: http://127.0.0.1:8080/xxl-job-admin
    accessToken: c9%a16ft#pQoQH2X^ElMyzLyox9o2$dX

将addresses修改为自己部署的xxl-job-admin地址，accessToken修改为服务端配置token，两端需保持一致才能注册成功。

3. 创建启动配置文件

因xxl-job没有使用spring-boot-starter，需自行将配置类注入到spring容器中。

@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(\"${server.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.setPort(port + 10000);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

        return xxlJobSpringExecutor;
    }
}

这里将客户端接收的端口设置为server.port+10000，也可指定为0，将自动获取系统可用端口。

4. 在xxl-job-admin中创建执行器

将appname替换为你的服务名，选择自动注册。

5. 启动客户端项目

启动你的客户端程序，将会自动注册到xxl-job-admin服务端中

2024-01-31 14:34:05.854  INFO 7806 --- [      Thread-10] com.xxl.job.core.server.EmbedServer      : >>>>>>>>>>> xxl-job remoting server start success, nettype = class com.xxl.job.core.server.EmbedServer, port = 18990

至此客户端和服务端配置均已完成，接下来我们创建一个任务执行。

三、编写一个定时任务调度

1. 创建一个任务调度

在客户端中编写如下代码，并重新启动客户端。

@Slf4j
@Component
public class XxlJobHandler {

    /**
     * 更新状态
     **/
    @XxlJob(\"UpdateStatus\")
    public void updateStatus() {
        String jobParam = XxlJobHelper.getJobParam();
        log.info(\"任务执行\" + jobParam);
    }

}

注意@XxlJob(“UpdateStatus”)注解中的UpdateStatus，即任务的唯一名称，之后执行任务调度将会使用。

XxlJobHelper.getJobParam();可以用来获取执行任务时传递的参数。

2. xxl-job-admin中添加任务

主要配置在Cron中配置任务调度的时间周期，可选择CRON或固定速度。JobHandler中需配置@XxlJob注解中的名称。

3. 执行任务

点击执行一次，任务执行成功将会打印日志

2024-01-31 14:50:20.199  INFO 10123 --- [Pool-1270998288] c.xxl.job.core.executor.XxlJobExecutor   : >>>>>>>>>>> xxl-job regist JobThread success, jobId:2, handler:com.xxl.job.core.handler.impl.MethodJobHandler@58aeccc[class com.example.demo.job.XxlJobHandler#updateStatus]
2024-01-31 14:50:20.201  INFO 10123 --- [2-1706683820199] com.example.demo.job.XxlJobHandler       : 任务执行第一次执行任务

点击启动任务，将会按照我们既定的调度周期执行任务。

这里可以查看我们的调度日志。

4.定制化拦截器

我们可以通过Spring Aop拦截@XxlJob注解，去处理一些通用业务逻辑。

@Slf4j
@Order(1)
@Aspect
@Component
public class XxlJobAspect {

    @Pointcut(\"@annotation(com.xxl.job.core.handler.annotation.XxlJob)\")
    public void pointCut() {
    }

    @Around(\"pointCut() && @annotation(xxlJob)\")
    public Object doAround(ProceedingJoinPoint point, XxlJob xxlJob) {
        String traceId = UUID.randomUUID().toString();
        MDC.put(\"traceId\", traceId);

        String jobName = xxlJob.value();
        StopWatch sw = new StopWatch();
        sw.start();
        log.info(\"定时任务[{}]开始，开始时间：{}，输入参数：{}\", jobName, LocalDateTime.now(), XxlJobHelper.getJobParam());
        Object proceed;
        try {
            proceed = point.proceed();
        } catch (Throwable e) {
            log.warn(\"定时任务[{}]执行失败\", jobName, e);
            failure(e, traceId);
            return null;
        }
        sw.stop();
        log.info(\"定时任务[{}]结束！执行时间：{} ms\", jobName, sw.getTotalTimeMillis());
        success(traceId);
        return proceed;
    }

    private void failure(Throwable e, String traceId) {
        XxlJobHelper.handleFail(\"traceId=\" + traceId + \",<br>exception=\" + ExceptionUtils.getStackTrace(e));
        MDC.remove(\"traceId\");
    }

    private void success(String traceId) {
        XxlJobHelper.handleSuccess(\"traceId=\" + traceId);
        MDC.remove(\"traceId\");
    }

}

上述代码将拦截在请求日志中串连traceId，用于查询单次任务执行的链路。

在logback配置文件中修改pattern包含%X{traceId}。

再次执行任务将打印日志

15:03:29.889 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.a.XxlJobAspect - [doAround,43] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 定时任务[UpdateStatus]开始，开始时间：2024-01-31T15:03:29.888977，输入参数：第一次执行任务
15:03:29.893 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.j.XxlJobHandler - [updateStatus,22] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 任务执行第一次执行任务
15:03:29.893 [xxl-job, JobThread-2-1706684609877] INFO  c.e.d.a.XxlJobAspect - [doAround,53] 720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca - 定时任务[UpdateStatus]结束！执行时间：8 ms

720a7fde-4b7b-4a2d-b5eb-e0f96c3d3dca即为当前请求中的traceId，在调度日志中也将打印此id。