XXL-JOB 3.1.0 搭建指南

Java

XXL-JOB 3.1.0 搭建指南

📌 本文将介绍如何基于最新版本 XXL-JOB 3.1.0 搭建分布式任务调度系统，涵盖调度中心与执行器的搭建、配置、部署运维及升级流程。

调度中心配置(部署成功后配置)

访问 https://www.twenhub.com/archives/xxl-job-pei-zhi-xuan-xiang-xiang-jie

项目结构与关系架构

XXL-JOB 项目由三个主要模块组成，它们的名称和职责如下：

模块名称	项目名称	职责
xxl-job-admin	调度中心	负责管理调度信息，发起调度请求，监控任务执行状态，提供Web管理界面
xxl-job-core	核心依赖包	提供调度中心和执行器的通信接口、任务处理接口等核心功能
my_springboot_job1/2/3	执行器项目	实际业务系统中集成了xxl-job-core的执行器项目

系统架构关系

调度中心和执行器的关系是典型的一对多关系：

调度中心(XXL-JOB-ADMIN)：
- 连接专用的 xxl_job 数据库（用于存储任务配置、执行记录等信息）
- 提供Web界面进行任务管理
- 按照调度策略向多个执行器发送调度请求
执行器(my_springboot_job1/2/3)：
- 每个执行器连接自己的业务数据库（与xxl-job无关）
- 接收调度中心的调度请求
- 执行具体的任务逻辑
- 将执行结果回调给调度中心

调度中心和执行器之间通过HTTP协议通信，执行器需要注册到调度中心，调度中心根据任务配置调度执行器执行任务。

核心概念

XXL-JOB 是一个轻量级分布式任务调度平台，其核心设计思想是将调度行为抽象形成调度中心平台，平台本身不承担业务逻辑，而是负责发起调度请求，由执行器接收调度请求并执行任务。这种设计实现了调度与任务的解耦，提高了系统的稳定性和可扩展性。

系统组成

组件	职责
调度中心	负责管理调度信息，按照调度配置发出调度请求，监控任务执行状态
执行器	负责接收调度请求并执行对应任务逻辑

环境要求

基于 XXL-JOB 3.1.0 版本，推荐以下环境配置：

JDK：Java 17 或以上
Maven：3.3.1 或以上
MySQL：5.7 或以上（支持 UTF8mb4 字符集）
项目框架：Spring Boot 3.x

搭建调度中心

1. 初始化调度数据库

首先需要创建 XXL-JOB 的数据库并导入初始化 SQL 脚本：

# 创建数据库
CREATE database if NOT EXISTS `xxl_job` default character set utf8mb4 collate utf8mb4_unicode_ci;
use `xxl_job`;

# 导入表结构和初始数据
# 可从官方仓库获取最新SQL脚本：https://github.com/xuxueli/xxl-job/blob/master/doc/db/tables_xxl_job.sql

可以通过以下方式获取并执行 SQL 脚本：

SQL脚本可以从GitHub仓库获取：

访问 https://github.com/xuxueli/xxl-job/blob/master/doc/db/tables_xxl_job.sql
点击"Raw"按钮查看原始文件
将内容保存为本地文件 tables_xxl_job.sql

然后导入到MySQL：

# 导入到 MySQL
mysql -u用户名 -p密码 xxl_job < tables_xxl_job.sql

2. 部署调度中心项目

部署调度中心项目通常分为两个环境：开发环境（通常是Windows）和生产环境（通常是Linux）。

开发环境构建（Windows）

访问 XXL-JOB Tags页面
找到3.1.0版本的标签
下载对应版本的源码（点击"zip"或"tar.gz"）

下载完成后，在Windows环境中进行配置和构建：

解压源码包：

方式1：使用Windows资源管理器右键点击zip文件，选择"解压到..."
方式2：使用解压软件如WinRAR、7-Zip等解压

进入项目目录：

cd xxl-job-3.1.0

【重要】修改数据库配置（在构建之前）：

使用记事本或其他编辑器打开 xxl-job-admin\src\main\resources\application.properties 文件，主要修改以下数据库配置项：

# 服务端口
server.port=8080
server.servlet.context-path=/xxl-job-admin

# 数据库配置（调度中心专用数据库，即初始化的xxl_job库）
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=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# 邮件配置（可选）
spring.mail.host=smtp.qq.com
spring.mail.port=25
[email protected]
spring.mail.password=xxx
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
spring.mail.properties.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

# 调度中心通讯TOKEN，非空时启用
xxl.job.accessToken=default_token

# 国际化配置（默认中文）
spring.messages.basename=i18n/messages

完成配置后，使用Maven打包（跳过测试）：

确保已安装Maven并配置环境变量。

mvn clean package -Dmaven.test.skip=true

构建完成后，jar包位于 xxl-job-admin\target\xxl-job-admin-3.1.0.jar

Windows环境下源码构建注意事项：

在Windows环境下进行源码构建时，请注意以下事项：

路径分隔符：Windows使用反斜杠"\"作为路径分隔符，而不是Linux的正斜杠"/"

Maven环境：确保已安装Maven并添加到系统环境变量PATH中

JDK版本：确保使用JDK 17或以上版本，可通过java -version命令检查

权限问题：如遇权限问题，可尝试以管理员身份运行命令提示符

Maven依赖下载失败：可在Maven的settings.xml中配置国内镜像源加速下载

编码问题：确保文本编辑器使用UTF-8编码修改配置文件，避免中文乱码

直接启动调度中心进行测试：

# 进入目标目录
cd xxl-job-admin\target

# 启动调度中心
java -jar xxl-job-admin-3.1.0.jar

生产环境部署（Linux）

在生产环境中，通常将在Windows开发环境构建好的jar包部署到Linux服务器上运行。步骤如下：

1. 将构建好的jar包传输到Linux服务器

使用SCP、SFTP等工具将xxl-job-admin-3.1.0.jar传输到Linux服务器上。

# 示例：使用scp从本地传输到服务器
scp xxl-job-admin-3.1.0.jar user@server:/path/to/deploy/

2. 创建Linux环境下的启动脚本

在jar包所在目录创建以下启动脚本：

#!/bin/bash
# xxl-job-admin 管理脚本（CentOS 7/8/Stream）
# 交互：1=启动 2=停止 3=重启 q=退出

APP_NAME="xxl-job-admin-3.1.0.jar"             # JAR 包名
JAVA_OPTS="-Xms256m -Xmx256m"                  # JVM 参数
LOG_DIR="./log"               # 日志目录（可按需修改）
mkdir -p "$LOG_DIR"

# ──────────────────────────── 内部函数 ──────────────────────────── #
get_pid() { 
    pgrep -f "$APP_NAME"; 
}

start() {
    local pid
    pid=$(get_pid)
    if [[ -n $pid ]]; then
        echo "→ 服务已在运行 (PID=$pid)"
        return
    fi

    local log_file="${LOG_DIR}/$(date +%F).log"
    echo "→ 启动中，日志写入 ${log_file} …"

    # 说明：
    # 1) ( ... ) &      ：子 shell 后台运行，避免阻塞当前脚本交互菜单
    # 2) tee -a         ：同时写终端与日志文件（追加）
    ( nohup java ${JAVA_OPTS} -jar "${APP_NAME}" 2>&1 | tee -a "$log_file" ) &

    # 等待进程起来再获取真实 PID
    sleep 1
    pid=$(get_pid)
    if [[ -n $pid ]]; then
        echo "√ 已启动 (PID=$pid)"
    else
        echo "× 启动失败，查看日志排查"
    fi
}

stop() {
    local pid
    pid=$(get_pid)
    if [[ -z $pid ]]; then
        echo "→ 服务未运行"
    else
        kill -9 "$pid" && echo "√ 已停止 (PID=$pid)"
    fi
}

restart() {
    stop
    sleep 2
    start
}

# ──────────────────────────── 主菜单 ──────────────────────────── #
while true; do
    echo -e "\n===== xxl-job-admin 管理 ====="
    echo "1) 启动"
    echo "2) 停止"
    echo "3) 重启"
    echo "q) 退出"
    read -rp "请选择操作: " choice
    case "$choice" in
        1) start   ;;
        2) stop    ;;
        3) restart ;;
        q|Q) exit 0;;
        *) echo "× 无效选项";;
    esac
done

将此脚本保存为 manage-xxl-job.sh，并赋予执行权限：

chmod +x manage-xxl-job.sh

3. 启动服务

使用脚本启动调度中心服务：

./manage-xxl-job.sh
# 然后在菜单中选择"1"启动服务

调度中心启动后，可通过 http://localhost:8080/xxl-job-admin 访问控制台，默认账号密码：admin/123456

搭建执行器项目

注意：以下所有步骤均在执行器项目(my_springboot_job1/2/3)中操作，而非调度中心项目。

1. 创建 Spring Boot 项目

创建一个标准的 Spring Boot 项目作为执行器(my_springboot_job1/2/3)，推荐使用 Spring Initializr 或 IDE 创建。

2. 添加 XXL-JOB 依赖

在执行器项目的 pom.xml 中添加 XXL-JOB 核心依赖：

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

3. 配置执行器

在执行器项目的 application.yml 或 application.properties 中添加执行器配置：

# 应用名称和端口
spring:
  application:
    name: my_springboot_job1  # 实际业务系统名称

server:
  port: 8081  # 业务系统端口，与执行器端口不同

# XXL-JOB 执行器配置
xxl:
  job:
    admin:
      # 调度中心地址，多个地址用逗号分隔
      # 格式为：http://调度中心IP:调度中心端口/调度中心context-path
      addresses: http://localhost:8080/xxl-job-admin
    # 执行器配置
    executor:
      # 执行器名称，与调度中心配置的执行器名称一致
      # 这是执行器的唯一标识，调度中心通过此标识找到对应执行器
      appname: my_springboot_job1
      # 执行器注册方式：0=自动注册，1=手动录入
      address: 
      # 执行器IP，默认为空表示自动获取
      # 如果执行器部署在内网，调度中心无法直接访问，则需要手动指定IP
      ip: 
      # 执行器端口，默认为9999
      # 这是执行器启动的端口，调度中心通过此端口发送HTTP请求
      # 单机部署多个执行器时，必须避免端口冲突
      port: 9999
      # 执行器日志路径
      logpath: /data/applogs/xxl-job/jobhandler
      # 执行器日志保留天数，最小为3天
      logretentiondays: 30
    # 与调度中心通信的访问令牌，安全验证用
    # 调度中心和执行器必须配置相同的accessToken才能通信
    accessToken: default_token

关键参数说明：

以下参数是执行器与调度中心通信和自身运行的关键配置，请务必根据实际环境进行设置：

xxl.job.admin.addresses: 调度中心地址，执行器通过此地址注册并接收调度请求。支持配置多个调度中心地址，用逗号分隔。

xxl.job.executor.appname: 执行器标识，调度中心通过此唯一标识找到对应的执行器。建议与Spring Boot应用名称保持一致。

xxl.job.executor.port: 执行器启动的端口，调度中心通过此端口发送HTTP请求。在单机部署多个执行器时，请确保端口不冲突。

xxl.job.accessToken: 通信令牌，用于调度中心和执行器之间的安全验证。调度中心和所有执行器必须配置相同的值才能正常通信。

4. 创建执行器配置类

在执行器项目中创建 XxlJobConfig 配置类：

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

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

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

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

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

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

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

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

    @Bean
    public XxlJobSpringExecutor xxlJobExecutor() {
        XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
        xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
        xxlJobSpringExecutor.setAppname(appName);
        xxlJobSpringExecutor.setIp(ip);
        xxlJobSpringExecutor.setPort(port);
        xxlJobSpringExecutor.setAccessToken(accessToken);
        xxlJobSpringExecutor.setLogPath(logPath);
        xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);
        
        return xxlJobSpringExecutor;
    }
}

5. 开发任务处理器

创建一个简单的任务处理器：

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

@Component
public class SampleXxlJob {
    private static Logger logger = LoggerFactory.getLogger(SampleXxlJob.class);

    /**
     * 简单示例任务
     */
    @XxlJob("demoJobHandler")
    public void demoJobHandler() throws Exception {
        XxlJobHelper.log("XXL-JOB, Hello World.");
        
        // 获取任务参数
        String param = XxlJobHelper.getJobParam();
        
        // 业务逻辑
        for (int i = 0; i < 5; i++) {
            XxlJobHelper.log("beat at:" + i);
            Thread.sleep(2000);
        }
        
        // 任务结果
        XxlJobHelper.handleSuccess("任务执行成功");
    }
}

6. 启动执行器项目

启动 Spring Boot 应用，执行器将自动注册到调度中心。

配置调度任务

1. 登录调度中心

访问 http://localhost:8080/xxl-job-admin，使用默认账号密码（admin/123456）登录。

2. 配置执行器

如果执行器设置为自动注册（address_type=0），则会自动出现在执行器管理列表中。

如果需要手动配置：

进入"执行器管理"页面
点击"新增"按钮
填写执行器信息：
- AppName：与执行器配置中的 appname 一致
- 名称：执行器显示名称
- 注册方式：选择"手动录入"
- 机器地址：填写执行器地址，如 "http://localhost:9999"

3. 配置任务

进入"任务管理"页面
点击"新增"按钮
填写任务信息：
- 执行器：选择已配置的执行器
- 任务描述：任务的描述信息
- 调度类型：选择调度方式（CRON、固定速度等）
- Cron：如 "0 0/1 * * * ?"（每分钟执行一次）
- 运行模式：选择"BEAN"模式
- JobHandler：填写任务处理器的名称，如 "demoJobHandler"
- 路由策略：选择执行器路由策略
- 阻塞处理策略：选择阻塞处理策略
- 任务超时时间：单位秒，0表示不限制
- 失败重试次数：任务失败重试次数，0表示不重试

4. 启动任务

在任务列表中，点击"操作"列的"启动"按钮，启动任务调度。

5. 查看日志

任务执行后，可以在"调度日志"中查看任务的调度和执行情况。

部署与运维

1. 生产环境部署脚本

在生产环境中，建议使用在"搭建调度中心"章节中提供的 manage-xxl-job.sh 脚本来管理调度中心服务。该脚本可用于启动、停止或重启服务。

chmod +x manage-xxl-job.sh
./manage-xxl-job.sh
# 然后在菜单中选择"1"启动服务

2. 运维建议

监控：

定期检查调度中心和执行器的日志
配置系统监控，关注调度中心和执行器的CPU、内存使用情况
设置任务失败告警，及时发现问题

备份：

定期备份xxl_job数据库
备份调度中心和执行器的配置文件

高可用：

调度中心可以集群部署，通过Nginx等进行负载均衡
执行器也可以集群部署，通过调度中心的路由策略进行任务分发

安全：

修改默认的admin/123456登录密码
配置非默认的accessToken
限制调度中心的访问IP

后续升级

XXL-JOB 的版本迭代较为频繁，定期升级可以获得新功能和安全修复。以下是升级的核心流程：

1. 升级调度中心

升级调度中心是整个系统升级的第一步：

备份关键数据：

备份数据库（xxl_job 库）

# 备份数据库示例
mysqldump -u用户名 -p密码 xxl_job > xxl_job_backup_$(date +%Y%m%d).sql

备份配置文件（application.properties）

# 备份配置文件示例
cp application.properties application.properties.backup

备份日志文件（如有需要）

获取新版本：

从 GitHub Releases 页面下载最新版本的调度中心 jar 包
- 官方下载地址：https://github.com/xuxueli/xxl-job/releases
或从源码仓库拉取最新代码并编译

# 从源码构建示例
git clone https://github.com/xuxueli/xxl-job.git
cd xxl-job
git checkout v3.1.0  # 切换到目标版本
mvn clean package -Dmaven.test.skip=true

执行升级操作：

停止运行中的调度中心服务

# 如果使用了管理脚本
./manage-xxl-job.sh  # 选择"2"停止服务

# 或者直接终止进程
kill -9 $(pgrep -f xxl-job-admin)

执行数据库升级脚本（官方通常会在发布说明中提供）
- 升级脚本通常位于：https://github.com/xuxueli/xxl-job/tree/master/doc/db
使用新版本 jar 包替换旧版本，保留原配置文件
检查配置文件是否需要新增配置项（参考官方文档）

启动与验证：

启动新版本调度中心服务

# 使用管理脚本启动
./manage-xxl-job.sh  # 选择"1"启动服务

# 或者直接启动
nohup java -jar xxl-job-admin-新版本.jar > xxl-job-admin.log 2>&1 &

检查服务日志确认启动正常
登录管理界面验证功能是否正常

2. 升级执行器

执行器升级通常更为简单：

更新依赖版本：

修改执行器项目(my_springboot_job1/2/3)的 pom.xml 中的 xxl-job-core 依赖版本。推荐使用Maven属性变量统一管理版本号（最佳实践）

首先在pom.xml的properties部分定义版本变量：

<properties>
    <!-- 其他属性 -->
    <xxl-job.version>3.1.0</xxl-job.version>
</properties>

然后在依赖部分引用该变量：

<dependency>
    <groupId>com.xuxueli</groupId>
    <artifactId>xxl-job-core</artifactId>
    <version>${xxl-job.version}</version>
</dependency>

升级时，只需修改properties中的版本号即可。最新版本可在Maven中央仓库查询：https://mvnrepository.com/artifact/com.xuxueli/xxl-job-core

检查配置兼容性：

查看官方发布说明，了解配置类是否有变更
检查 XxlJobConfig 配置类是否需要调整
检查 application.yml 中的配置项是否需要更新

重新构建与部署：

重新编译打包项目
停止旧版本执行器服务
部署新版本执行器
启动服务并检查日志

验证功能：

检查执行器是否正常注册到调度中心
测试现有任务是否能正常执行
验证新功能是否可用

3. 兼容性与最佳实践

升级过程中需要注意以下几点：

版本一致性：调度中心和执行器的版本应保持一致，避免兼容性问题
渐进式升级：大版本跨度较大时（如从 2.x 升级到 3.x），建议先升级到中间版本，再逐步升级到目标版本
测试验证：先在测试环境完成升级并验证功能，确认无误后再在生产环境升级
关注发布说明：每次升级前仔细阅读官方发布说明（Release Notes），了解新特性、修复问题和潜在的不兼容变更
备份回滚：准备回滚方案，确保升级失败时能快速恢复到之前的稳定版本
分批升级：在多执行器环境中，可以考虑分批升级执行器，降低风险

总结

通过以上步骤，我们完成了 XXL-JOB 3.1.0 分布式任务调度平台的完整搭建，包括调度中心和执行器的部署与配置。XXL-JOB 提供了简单易用的任务调度解决方案，可以满足大多数分布式任务调度场景的需求。

在实际应用中，可以根据业务需求进一步扩展，如配置集群部署、实现自定义告警、开发更复杂的任务处理逻辑等。XXL-JOB 在微服务架构中也具有广泛的应用前景。

参考资料

XXL-JOB 官方文档 - 详细的中文使用文档
XXL-JOB GitHub 仓库 - 源码和最新版本发布
Maven 中央仓库 xxl-job-core - 最新依赖版本查询
XXL-JOB Releases 页面 - 官方发布包下载
XXL-JOB 数据库脚本 - 初始化数据库脚本
XXL-JOB 升级日志 - 版本更新说明
Spring Boot 官方文档 - Spring Boot 项目创建指南

如果觉得文章对你有用，请随意赞赏

XXL_JOB Java

XXL-JOB 3.1.0 搭建指南

https://www.twenhub.com/archives/xxl-job-3.1.0-da-jian-zhi-nan

作者

Administrator

发布于

2025-06-10

更新于

2025-06-10

许可协议

CC BY 4.0