XXL-JOB搭建并使用

docker搭建xxl-job-admin

初始化配置

# 从官方下载初始配置文件模板并修改为自己的配置信息，其中也可以通过docker启动时指定环境变量PARAMS设置
wget https://raw.githubusercontent.com/xuxueli/xxl-job/master/xxl-job-admin/src/main/resources/application.properties

# 下载初始化数据库脚本并执行
wget https://raw.githubusercontent.com/xuxueli/xxl-job/master/doc/db/tables_xxl_job.sql

# 执行脚本
mysql -u* -p* < tables_xxl_job.sql

docker-compose配置

version: "3"

services:
  xxl-job-admin:
    image: xuxueli/xxl-job-admin:3.1.1
    container_name: xxl-job-admin
    restart: always
    volumes:
      - /docker-data/xxl-job-admin/data:/data/applogs
      - /docker-data/xxl-job-admin/application.properties:/application.properties
    ports:
      - "8080:8080"
    environment:
      PARAMS: "--spring.config.location=/application.properties"
      TZ: Asia/Shanghai
    network_mode: bridge
    hostname: xxl-job-admin

通过 --spring.config.location=/application.properties指定 xxl-job-admin启动配置文件

启动命令 docker compose up -d然后访问 http://ip:8080/xxl-job-admin进入调度中心，修改初始密码和用户

springboot接入任务调度中心

pom.xml

<!-- https://mvnrepository.com/artifact/com.xuxueli/xxl-job-core -->
<dependency>
  <groupId>com.xuxueli</groupId>
  <artifactId>xxl-job-core</artifactId>
  <version>3.1.1</version>
</dependency>

application.yml

xxl:
  job:
    enabled: true
    admin:
      address: http://192.168.1.5:8080/xxl-job-admin
      timeout: 3
    accessToken: ******
    executor:
      appName: youcats-mgt
      address: http://192.168.1.5:9999
      ip:
      port: 9999
      logPath: /opt/logs/YCM
      logRetentionDays: 60

程序内配置

XxlJobConfig可通过 application.yml中的 xxl.job.enabled控制是否使用 xxl-job

package cn.youcats.youcatsmgt.config.XxlJob;

import com.xxl.job.core.executor.impl.XxlJobSpringExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @program: YouCats
 * @description: xxl-job配置
 * @author: LuoSong
 * @create: 2025-07-24 17:20:04
 **/
@Configuration
@ConditionalOnProperty(prefix = "xxl.job", name = "enabled", havingValue = "true")
public class XxlJobConfig {
    private static final Logger LOGGER = LoggerFactory.getLogger(XxlJobConfig.class);

    private final XxlJobAdminProperties xxlJobAdminProperties;
    private final XxlJobExecutorProperties xxlJobExecutorProperties;
    private final XxlJobTokenProperties xxlJobTokenProperties;

    public XxlJobConfig(XxlJobAdminProperties xxlJobAdminProperties, XxlJobExecutorProperties xxlJobExecutorProperties,
                        XxlJobTokenProperties xxlJobTokenProperties) {
        this.xxlJobAdminProperties = xxlJobAdminProperties;
        this.xxlJobExecutorProperties = xxlJobExecutorProperties;
        this.xxlJobTokenProperties = xxlJobTokenProperties;
    }

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(xxlJobAdminProperties.getAddress());
        xxlJobSpringExecutor.setTimeout(xxlJobAdminProperties.getTimeout());
        xxlJobSpringExecutor.setAppname(xxlJobExecutorProperties.getAppName());
        xxlJobSpringExecutor.setAddress(xxlJobExecutorProperties.getAddress());
        xxlJobSpringExecutor.setIp(xxlJobExecutorProperties.getIp());
        xxlJobSpringExecutor.setPort(xxlJobExecutorProperties.getPort());
        xxlJobSpringExecutor.setAccessToken(xxlJobTokenProperties.getAccessToken());
        xxlJobSpringExecutor.setLogPath(xxlJobExecutorProperties.getLogPath());
        xxlJobSpringExecutor.setLogRetentionDays(xxlJobExecutorProperties.getLogRetentionDays());
        LOGGER.info("********************** xxl-job init success **********************");
        return xxlJobSpringExecutor;
    }
}

XxlJobAdminProperties

package cn.youcats.youcatsmgt.config.XxlJob;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * @program: YouCats
 * @description: 管理中心配置
 * @author: LuoSong
 * @create: 2025-07-24 17:26:22
 **/
@Configuration
@ConfigurationProperties(prefix = "xxl.job.admin")
@Data
public class XxlJobAdminProperties {
    /**
     * 调度中心部署跟地址 [选填]：如调度中心集群部署存在多个地址则用逗号分隔。执行器将会使用该地址进行"执行器心跳注册"和"任务结果回调"；为空则关闭自动注册；
     */
    private String address;

    // 调度中心通讯超时时间[选填]，单位秒；默认3s；
    private Integer timeout;
}

XxlJobExecutorProperties

package cn.youcats.youcatsmgt.config.XxlJob;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * @program: YouCats
 * @description: 执行器配置
 * @author: LuoSong
 * @create: 2025-07-24 17:28:32
 **/
@Configuration
@ConfigurationProperties(prefix = "xxl.job.executor")
@Data
public class XxlJobExecutorProperties {
    /**
     * 执行器AppName [选填]：执行器心跳注册分组依据；为空则关闭自动注册
     */
    private String appName;

    /**
     * 执行器注册 [选填]：优先使用该配置作为注册地址，为空时使用内嵌服务 ”IP:PORT“ 作为注册地址。从而更灵活的支持容器类型执行器动态IP和动态映射端口问题。
     */
    private String address;

    /**
     * 执行器IP [选填]：默认为空表示自动获取IP，多网卡时可手动设置指定IP，该IP不会绑定Host仅作为通讯实用；地址信息用于 "执行器注册" 和 "调度中心请求并触发任务"
     */
    private String ip;

    /**
     * 执行器端口号 [选填]：小于等于0则自动获取；默认端口为9999，单机部署多个执行器时，注意要配置不同执行器端口；
     */
    private int port;

    /**
     * 执行器运行日志文件存储磁盘路径 [选填] ：需要对该路径拥有读写权限；为空则使用默认路径；
     */
    private String logPath;

    /**
     * 执行器日志文件保存天数 [选填] ： 过期日志自动清理, 限制值大于等于3时生效; 否则, 如-1, 关闭自动清理功能
     */
    private int logRetentionDays;
}

XxlJobTokenProperties

package cn.youcats.youcatsmgt.config.XxlJob;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * @program: YouCats
 * @description: xxl-job接入密钥
 * @author: LuoSong
 * @create: 2025-07-24 17:29:55
 **/
@Configuration
@ConfigurationProperties(prefix = "xxl.job")
@Data
public class XxlJobTokenProperties {
    /**
     * 执行器通讯TOKEN [选填]：非空时启用；
     */
    private String accessToken;
}

使用(示例)

@XxlJob("loginStatusChange")
public ReturnT<String> changeLoginStatus(String param) {
    String transId = getTransId();
    try {
        LOGGER.info("[{}] Start user login status clean.", transId);
        webUserService.changeLoginStatus(transId);
        xcxUserService.changeLoginStatus(transId);
        LOGGER.info("[{}] Clean user login status peer hour success.", transId);
    } catch (Exception e) {
        LOGGER.error("[{}] Clean user login status peer hour fail, error detail [{}].", transId, e.getMessage());
        return ReturnT.FAIL;
    }
    return ReturnT.SUCCESS;
}

执行器和任务

执行器注册

在管理中心中注册执行器，手动注册，地址填 http://ip:port/这里是 xxl.job.executor.address相等的

任务添加

在相应的执行器上添加任务，如果是 BEAN模式，使用的 JobHandler就是当时使用 @XxlJob注解后括号内的值，配置好其他参数后，便可以启动或执行一次

其他

如果报错500，按照相应的错误详情去修改，需要放通 xxl-job-admin到执行器的网络

参考官方文档：xxl-job