XXL-JOB部署与使用流程指南

最新推荐文章于 2025-12-05 17:02:52 发布

原创最新推荐文章于 2025-12-05 17:02:52 发布 · 1.1k 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring boot #中间件

最近项目里把一多半的定时任务放到了xxl-job上，还是挺好用的，特来记录一下如何使用的。

1.前置条件准备

项目	推荐版本	说明
JDK	1.8 或 11 （部分新版支持 JDK 17）	运行 Admin 与 Executor 必须的 Java 环境
Maven	3.6 以上	用于源码编译
MySQL	5.7 或 8.0	存储调度中心元数据，需提前建库并执行初始化脚本
操作系统	Linux（推荐）/ Windows	皆可，Linux 更适合生产环境
可选：Docker / Docker‑Compose	最新版	一键部署方案，适合快速验证或容器化部署

说明：若使用 Docker，MySQL 也可以通过容器一起启动，省去手动建库步骤。

2.下载 XXL‑JOB 源码或镜像

源码方式

git clone https://github.com/xuxueli/xxl-job.git
cd xxl-job

官方仓库提供完整的 Admin 与 Executor 示例项目。

Docker 镜像
官方已发布 xuxueli/xxl-job-admin、xuxueli/xxl-job-executor 镜像，可直接拉取使用。

3. 数据库初始化

在 MySQL 中创建库（如 xxl_job）并授权用户。

CREATE DATABASE xxl_job CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xxl'@'%' IDENTIFIED BY '123456';
GRANT ALL ON xxl_job.* TO 'xxl'@'%';
FLUSH PRIVILEGES;

执行 xxl-job 提供的 SQL 脚本（位于 xxl-job-admin/doc/sql/xxl_job.sql），完成表结构和默认数据的创建。

4. 配置调度中心（Admin）

在 xxl-job-admin 项目的 application.yml（或 application.properties）中填写关键配置：

server:
  port: 8080                     # 调度中心访问端口
spring:
  datasource:
    url: jdbc:mysql://<IP>:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&useSSL=false
    username: xxl
    password: 123456
xxl:
  job:
    accessToken: yourToken        # 调度中心与执行器通信的密钥
    logpath: /data/applogs/xxl-job # 任务执行日志存放目录
    logretentiondays: 30          # 日志保留天数

要点：accessToken 必须在执行器配置中保持一致；日志路径需保证对应目录有写权限。

5. 编译并启动 Admin

cd xxl-job-admin
mvn clean package -DskipTests   # 生成 xxl-job-admin-*.jar
java -jar target/xxl-job-admin-2.4.0.jar &
# 或使用 nohup
nohup java -jar target/xxl-job-admin-2.4.0.jar > admin.log 2>&1 &

启动成功后，访问 http://:8080/xxl-job-admin，默认账号/密码均为 admin，首次登录后建议立即修改密码。
说明：若使用 Docker‑Compose，只需 docker-compose up -d，容器会自动拉取镜像并启动 Admin 与 MySQL。

6.配置执行器（Executor）

6.1 新建 SpringBoot 项目并引入依赖

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

6.2 在 application.yml 中配置

xxl:
  job:
    admin:
      addresses: http://<admin-host>:8080/xxl-job-admin
    accessToken: yourToken               # 与 Admin 保持一致
    executor:
      appname: demo-executor             # 同一类执行器的唯一标识
      address: http://<executor-host>:9999/xxl-job-executor
      ip: 127.0.0.1
      port: 9999
      logpath: /data/applogs/xxl-job
      logretentiondays: 30

6.3 编写 JobHandler

@Component
public class DemoJobHandler extends IJobHandler {
    @Override
    public ReturnT<String> execute(String param) throws Exception {
        // 业务逻辑
        System.out.println("Hello XXL‑JOB, param = " + param);
        return SUCCESS;
    }
}

6.4 启动 Executor

java -jar target/xxl-job-executor-sample-2.4.0.jar &

启动后，Executor 会向 Admin 注册，登录 Admin 控制台可在“执行器管理”页面看到已上线的节点。若需要高可用，可在多台机器上部署相同 appname 的 Executor，实现集群模式。

7. 在控制台创建任务（使用流程）

登录调度中心 → “任务管理”。
新建任务 → 填写任务名称、Cron 表达式（如 0 0/5 * * * ?），选择对应的执行器 appname。
任务参数（可选） → 在 “JobHandler” 中填写业务参数。
调度方式 → 手动、自动或混合。
保存并立即执行 → 系统会把调度请求发送给对应 Executor，Executor 调用 JobHandler 执行业务代码。
查看日志 → 在任务详情页可实时查看执行日志，日志文件保存在前面配置的 logpath 目录。