单机版 Xxl-Job 分布式定时任务调度的部署和使用

Xxl-Job 是一个分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线，开箱即用。本篇博客主要介绍如何进行单机版部署和使用，并在博客最后提供源代码下载。

Gitee 地址：https://gitee.com/xuxueli0323/xxl-job

GitHub 地址：https://github.com/xuxueli/xxl-job

官网帮助文档地址：https://www.xuxueli.com/index.html

一、部署 xxl-job-admin 调度平台

访问 GitHub 地址 https://github.com/xuxueli/xxl-job/releases 下载最新版的源代码 zip 包：

本篇博客在编写时，最新版本的 xxl-job 版本是 2.4.0，下载完成后的 zip 包名称为 xxl-job-2.4.0.zip

之所以要下载源码包，主要是在其源码中，有 mysql 的初始化脚本，以及 springboot 代码样例。

有关 mysql 的安装部署，这里不再赘述，我的 CentOS7 虚拟机上已经部署了 mysql ，因此直接使用。

解压缩源码包 xxl-job-2.4.0.zip 后，在其 doc 目录下的 db 目录中，有个 tables_xxl_job.sql 脚本，内容如下：

#
# XXL-JOB v2.4.0
# Copyright (c) 2015-present, xuxueli.

CREATE database if NOT EXISTS `xxl_job` default character set utf8mb4 collate utf8mb4_unicode_ci;
use `xxl_job`;

SET NAMES utf8mb4;

CREATE TABLE `xxl_job_info` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `job_group` int(11) NOT NULL COMMENT '执行器主键ID',
  `job_desc` varchar(255) NOT NULL,
  `add_time` datetime DEFAULT NULL,
  `update_time` datetime DEFAULT NULL,
  `author` varchar(64) DEFAULT NULL COMMENT '作者',
  `alarm_email` varchar(255) DEFAULT NULL COMMENT '报警邮件',
  `schedule_type` varchar(50) NOT NULL DEFAULT 'NONE' COMMENT '调度类型',
  `schedule_conf` varchar(128) DEFAULT NULL COMMENT '调度配置，值含义取决于调度类型',
  `misfire_strategy` varchar(50) NOT NULL DEFAULT 'DO_NOTHING' COMMENT '调度过期策略',
  `executor_route_strategy` varchar(50) DEFAULT NULL COMMENT '执行器路由策略',
  `executor_handler` varchar(255) DEFAULT NULL COMMENT '执行器任务handler',
  `executor_param` varchar(512) DEFAULT NULL COMMENT '执行器任务参数',
  `executor_block_strategy` varchar(50) DEFAULT NULL COMMENT '阻塞处理策略',
  `executor_timeout` int(11) NOT NULL DEFAULT '0' COMMENT '任务执行超时时间，单位秒',
  `executor_fail_retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '失败重试次数',
  `glue_type` varchar(50) NOT NULL COMMENT 'GLUE类型',
  `glue_source` mediumtext COMMENT 'GLUE源代码',
  `glue_remark` varchar(128) DEFAULT NULL COMMENT 'GLUE备注',
  `glue_updatetime` datetime DEFAULT NULL COMMENT 'GLUE更新时间',
  `child_jobid` varchar(255) DEFAULT NULL COMMENT '子任务ID，多个逗号分隔',
  `trigger_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '调度状态：0-停止，1-运行',
  `trigger_last_time` bigint(13) NOT NULL DEFAULT '0' COMMENT '上次调度时间',
  `trigger_next_time` bigint(13) NOT NULL DEFAULT '0' COMMENT '下次调度时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_log` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `job_group` int(11) NOT NULL COMMENT '执行器主键ID',
  `job_id` int(11) NOT NULL COMMENT '任务，主键ID',
  `executor_address` varchar(255) DEFAULT NULL COMMENT '执行器地址，本次执行的地址',
  `executor_handler` varchar(255) DEFAULT NULL COMMENT '执行器任务handler',
  `executor_param` varchar(512) DEFAULT NULL COMMENT '执行器任务参数',
  `executor_sharding_param` varchar(20) DEFAULT NULL COMMENT '执行器任务分片参数，格式如 1/2',
  `executor_fail_retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '失败重试次数',
  `trigger_time` datetime DEFAULT NULL COMMENT '调度-时间',
  `trigger_code` int(11) NOT NULL COMMENT '调度-结果',
  `trigger_msg` text COMMENT '调度-日志',
  `handle_time` datetime DEFAULT NULL COMMENT '执行-时间',
  `handle_code` int(11) NOT NULL COMMENT '执行-状态',
  `handle_msg` text COMMENT '执行-日志',
  `alarm_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '告警状态：0-默认、1-无需告警、2-告警成功、3-告警失败',
  PRIMARY KEY (`id`),
  KEY `I_trigger_time` (`trigger_time`),
  KEY `I_handle_code` (`handle_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_log_report` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `trigger_day` datetime DEFAULT NULL COMMENT '调度-时间',
  `running_count` int(11) NOT NULL DEFAULT '0' COMMENT '运行中-日志数量',
  `suc_count` int(11) NOT NULL DEFAULT '0' COMMENT '执行成功-日志数量',
  `fail_count` int(11) NOT NULL DEFAULT '0' COMMENT '执行失败-日志数量',
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `i_trigger_day` (`trigger_day`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_logglue` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `job_id` int(11) NOT NULL COMMENT '任务，主键ID',
  `glue_type` varchar(50) DEFAULT NULL COMMENT 'GLUE类型',
  `glue_source` mediumtext COMMENT 'GLUE源代码',
  `glue_remark` varchar(128) NOT NULL COMMENT 'GLUE备注',
  `add_time` datetime DEFAULT NULL,
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_registry` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `registry_group` varchar(50) NOT NULL,
  `registry_key` varchar(255) NOT NULL,
  `registry_value` varchar(255) NOT NULL,
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `i_g_k_v` (`registry_group`,`registry_key`,`registry_value`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_group` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `app_name` varchar(64) NOT NULL COMMENT '执行器AppName',
  `title` varchar(12) NOT NULL COMMENT '执行器名称',
  `address_type` tinyint(4) NOT NULL DEFAULT '0' COMMENT '执行器地址类型：0=自动注册、1=手动录入',
  `address_list` text COMMENT '执行器地址列表，多地址逗号分隔',
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_user` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `username` varchar(50) NOT NULL COMMENT '账号',
  `password` varchar(50) NOT NULL COMMENT '密码',
  `role` tinyint(4) NOT NULL COMMENT '角色：0-普通用户、1-管理员',
  `permission` varchar(255) DEFAULT NULL COMMENT '权限：执行器ID列表，多个逗号分割',
  PRIMARY KEY (`id`),
  UNIQUE KEY `i_username` (`username`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `xxl_job_lock` (
  `lock_name` varchar(50) NOT NULL COMMENT '锁名称',
  PRIMARY KEY (`lock_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO `xxl_job_group`(`id`, `app_name`, `title`, `address_type`, `address_list`, `update_time`) VALUES (1, 'xxl-job-executor-sample', '示例执行器', 0, NULL, '2018-11-03 22:21:31' );
INSERT INTO `xxl_job_info`(`id`, `job_group`, `job_desc`, `add_time`, `update_time`, `author`, `alarm_email`, `schedule_type`, `schedule_conf`, `misfire_strategy`, `executor_route_strategy`, `executor_handler`, `executor_param`, `executor_block_strategy`, `executor_timeout`, `executor_fail_retry_count`, `glue_type`, `glue_source`, `glue_remark`, `glue_updatetime`, `child_jobid`) VALUES (1, 1, '测试任务1', '2018-11-03 22:21:31', '2018-11-03 22:21:31', 'XXL', '', 'CRON', '0 0 0 * * ? *', 'DO_NOTHING', 'FIRST', 'demoJobHandler', '', 'SERIAL_EXECUTION', 0, 0, 'BEAN', '', 'GLUE代码初始化', '2018-11-03 22:21:31', '');
INSERT INTO `xxl_job_user`(`id`, `username`, `password`, `role`, `permission`) VALUES (1, 'admin', 'e10adc3949ba59abbe56e057f20f883e', 1, NULL);
INSERT INTO `xxl_job_lock` ( `lock_name`) VALUES ( 'schedule_lock');

commit;

在 mysql 数据库中，运行以上脚本，创建了 xxl_job 数据库，并创建了 8 张表。

下面我们开始部署 xxl-job-admin，在虚拟机上创建目录 /app/xxljob 并在其内部文件夹和文件，具体结果如下：

编写 docker-compose.yml 文件内容如下：

version: "3.5"
services:
  xxl-job-admin:
    restart: always
    image: xuxueli/xxl-job-admin:2.4.0
    container_name: xxl-job-admin
    volumes:
      - /app/xxljob/logs:/data/applogs
    ports:
      # 端口映射
      - "8989:8080"
    environment:
      # xxl-job-admin 本身就是一个 springboot 程序，因此可以覆盖其参数进行启动
      # 覆盖的参数有：数据库连接字符串，连接数据库的账号密码，连接 xxl-job-admin 的 accessToken
      PARAMS: "
      --spring.datasource.url=jdbc:mysql://192.168.136.128:3306/xxl_job?characterEncoding=utf8&allowMultiQueries=true&useSSL=false
      --spring.datasource.username=root
      --spring.datasource.password=root
      --xxl.job.accessToken=mytest123"

最后在 docker-compose.yml 文件所在目录下，运行 docker-compose up -d 启动服务即可。

上面对外映射的端口是 8989，因此我们访问 http://192.168.136.128:8989/xxl-job-admin 进入登录页面

对于 xxl-job-admin 默认的登录账号是 admin 密码是 123456 ，登录成功后进入首页。

二、添加执行器和任务

我们需要添加一个自定义的执行器，以及 4 个任务，用于下面 SpringBoot 代码演示。

执行器可以简单理解为是对定时任务的分组名称。在左侧菜单中选择【执行器管理】菜单，系统默认有一个 xxl-job-executor-sample 的示例执行器，我们创建一个自己的测试执行器：mytest-executor ，创建成功后界面如下：

然后在左侧选择【任务管理】菜单，添加 4 个任务，添加后的效果如下：

具体每个任务的配置细节，后面会跟代码一起进行展示，这样比较容易理解代码细节。

三、代码细节展示

新建一个 springboot 工程，名称为 springboot_xxljob，具体结构如下所示：

首先看一下 pom 文件中的依赖包：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.jobs</groupId>
    <artifactId>springboot_xxljob</artifactId>
    <version>1.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.5</version>
    </parent>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--引入 xxl-job 的依赖-->
        <dependency>
            <groupId>com.xuxueli</groupId>
            <artifactId>xxl-job-core</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>

然后看一下 application.yml 中的配置文件内容，主要参考了源码包中的 properties 配置文件。

server:
  port: 8080

xxl:
  job:
    # 连接 xxl-job-admin 的 token 字符串
    accessToken: mytest123
    admin:
      addresses: http://192.168.136.128:8989/xxl-job-admin
    executor:
      appname: mytest-executor
      port: 18989

有关 xxl job 的配置，是我们自己编写的，因此没有任何提示

• accessToken 必须与 docker-compose.yml 中配置的值一样
• addresses 配置为 xxl-job-admin 部署的地址即可
• appname 就是我们上面自己创建的执行器 mytest-executor，可以理解为是对多个定时任务的分组名称
• port 端口是当前 springboot 提供给 xxl-job-admin 调度平台的端口，可以随便自定义

然后我们读取配置文件，对执行器进行配置，并放入 Spring 容器中：

package com.jobs.config;

import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Slf4j
@Configuration
public class XxlJobConfig {

    @Value("${xxl.job.accessToken}")
    private String accessToken;

    @Value("${xxl.job.admin.addresses}")
    private String adminAddresses;

    @Value("${xxl.job.executor.appname}")
    private String appname;

    @Value("${xxl.job.executor.port}")
    private int port;

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        log.info("xxl-job 配置初始化...");
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
        xxlJobSpringExecutor.setAppname(appname);
        xxlJobSpringExecutor.setPort(port);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        return xxlJobSpringExecutor;
    }
}

然后编写 4 个被 xxl-job-admin 调用的定时任务的代码：

package com.jobs.jobhandler;

import com.xxl.job.core.context.XxlJobHelper;
import com.xxl.job.core.handler.annotation.XxlJob;
import org.springframework.stereotype.Component;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;

@Component
public class MyTestJobs {

    // 注解使用方法
    // @XxlJob(value="自定义jobhandler名称",
    // init = "JobHandler初始化方法",
    // destroy = "JobHandler销毁方法")

    //----------------------------------------

    //该 demo 展示日志记录，以及返回任务执行状态，可以在 web 界面中查看
    @XxlJob("JobHandler01")
    public void testJob1() {
        System.out.println("JobHandler01 每 3 秒执行一次...");

        //通过 XxlJobHelper.log 记录的日志，可在 web 界面中进行查看
        XxlJobHelper.log("我自定义的日志："
                + LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));

        //通过 XxlJobHelper.handleSuccess 方法，在 web 界面中会展示任务执行成功状态
        //默认情况下，任务执行都是成功状态，不需要刻意操作，
        //XxlJobHelper.handleSuccess("执行成功");

        //通过 XxlJobHelper.handleFail 方法，在 web 界面中会展示任务执行失败状态
        //如果任务执行过程中有异常，可以在 catch 方法中记录错误日志，让任务展示执行失败状态
        //XxlJobHelper.handleFail("错误日志");
    }

    //----------------------------------------

    //该 demo 展示如果获取 web 界面中配置的传入参数值
    @XxlJob("JobHandler02")
    public void testJob2() {
        //可以通过 XxlJobHelper.getJobParam() 方法获取 web 界面上配置的参数值
        //你可以传入 json 格式的参数值，方便在这里进行解析使用。
        String parm = XxlJobHelper.getJobParam();
        System.out.println("JobHandler02 每 5 秒执行一次，传入的 parm 参数为：" + parm);
    }

    //----------------------------------------

    //该 demo 展示 init 方法和 destory 方法的使用
    @XxlJob(value = "JobHandler03", init = "JobHandler03Init", destroy = "JobHandler03Destory")
    public void testJob3() {
        System.out.println("JobHandler03 每 2 秒执行一次，seq 为：" + seq);
        seq = seq + 1;
    }

    //定义一个变量
    private Integer seq;

    //自定义 init 方法，
    //当前的 Springboot 程序启动后，JobHandler03 第一次被调用之前执行，
    //该方法仅仅只会执行一次，除非重启了当前的 Springboot 程序
    public void JobHandler03Init() {
        seq = 0;
        System.out.println("everyFifteenJob 执行了初 init 方法...");
    }

    //当前的 spring 容器销毁时执行该方法，通常是 SprngBoot 停止的时候销毁 Spring 容器，
    //一般情况下我们看不到下面代码打印的日志，除非采用特殊的方案停止 spring 容器。
    public void JobHandler03Destory() {
        System.out.println("everyFifteenJob 执行了 destory 方法...");
    }

    //----------------------------------------

    //该 demo 演示如果获取分片信息
    @XxlJob("JobHandler04")
    public void testJobs4() {
        //获取该 springboot 程序的分片索引（索引从 0 开始）
        int shardIndex = XxlJobHelper.getShardIndex();
        //总分片数，springboot 执行器的实例总数
        int shardTotal = XxlJobHelper.getShardTotal();

        //获取所有的任务列表
        List<Integer> list = getList();
        //根据【列表索引】与【总分片数】的余数是否等于【分片索引】，确定当前 springboot 程序要执行的任务
        for (int i = 0; i < list.size(); i++) {
            if (i % shardTotal == shardIndex) {
                System.out.println("当前第" + shardIndex + "分片执行了，任务项为：" + list.get(i));
            }
        }
    }

    //表示 10000 个任务
    public List<Integer> getList() {
        List<Integer> list = new ArrayList<>();
        for (int i = 0; i < 10000; i++) {
            list.add(i);
        }
        return list;
    }
}

注意：代码中 @XxlJob 注解中配置的 value 值，必须与 web 界面中配置的 JobHandler 的值一致。

第一个定时任务，在调度平台的配置界面如下：

代码主要展示定时任务执行时，可以通过 XxlJobHelper.log 方法记录日志，该日志可以在 web 界面的日志界面中查看到。

第二个定时任务，在调度平台的配置界面如下：

代码主要展示如果获取 web 界面中配置的参数值，最好使用 json 的参数值，这样在代码中比较容易解析

第三个任务，在调度平台的配置界面如下：

代码主要展示 @XxlJob 注解中，有关 init 方法和 destory 方法的使用，这俩方法在 SpringBoot 整个生命周期中仅执行一次。

第四个任务，在调度平台的配置界面如下：

代码主要展示如果让每个 SpringBoot 程序，也就是执行器实例，分别执行不同的任务，而不是全部的任务，这样可以分散压力。

本篇博客编写了一个 SpringBoot 程序，如果是在同一台机器上运行多个程序的话，可以修改 application.yml 中的端口，这样就启动了执行器的集群，方便 xxl-job-admin 调度平台使用相关的路由器策略进行调度，比如上面配置的【轮询】、【随机】、【故障转移】、【分片广播】等。这里就不展示具体执行效果的界面了，大家可以下载代码自行验证，我已经测试没有问题了。

本篇博客的源代码下载地址为：https://files.cnblogs.com/files/blogs/699532/springboot_xxljob.zip