轻量级分布式任务调度平台XXL-JOB入门指南

XXL-JOB是一个轻量级分布式任务调度平台，核心设计目标是开发迅速、学习简单、轻量级、易扩展。支持通过Web界面动态管理任务，具备任务分片（Task Sharding）、故障转移、弹性扩容等特性，已广泛应用于电商、大数据、金融等领域。作为一款开箱即用的开源工具，它能帮助开发者轻松实现分布式环境下的任务调度需求。

一、核心价值解析

1.1 为什么选择XXL-JOB？

XXL-JOB提供了一站式的任务调度解决方案，相比传统定时任务（如Spring Task）具有以下优势：

• 分布式架构：支持集群部署，避免单点故障
• 动态管理：通过Web界面实时操作任务，无需重启服务
• 丰富特性：内置任务失败重试、超时控制、任务依赖等功能
• 监控告警：完善的任务执行监控和失败告警机制
• 高可用性：支持任务故障转移和负载均衡

图1：XXL-JOB运行报表界面，展示任务数量、调度次数和执行器数量等关键指标

1.2 核心功能特性

• 任务调度：支持CRON表达式、固定频率等多种调度方式
• 任务管理：提供Web界面进行任务创建、修改、删除、启停等操作
• 执行器管理：支持多执行器集群部署，动态发现和注册
• 日志管理：详细记录任务执行日志，支持在线查看和下载
• 权限控制：基于角色的访问控制，保障系统安全

二、环境准备指南

2.1 基础环境要求

[!TIP] XXL-JOB对环境要求较低，主流开发环境均能满足需求

• JDK：1.8+（推荐JDK8，JDK11完全兼容，JDK17需做部分配置调整）
• MySQL：5.7+（8.0版本也支持，需注意驱动适配）
• Maven：3.0+（用于源码编译）
• Git：用于获取源码

2.2 环境检查命令

# 检查JDK版本
java -version
# 输出示例: java version "1.8.0_301"

# 检查MySQL版本
mysql -V
# 输出示例: mysql  Ver 14.14 Distrib 5.7.35, for Linux (x86_64) using  EditLine wrapper

# 检查Maven版本
mvn -v
# 输出示例: Apache Maven 3.6.3

三、多元部署方案

3.1 源码编译安装 [本地开发]

📥 步骤1：获取源码

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

🔧 步骤2：初始化数据库

# 登录MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE xxl_job CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 执行初始化脚本
use xxl_job;
source /data/web/disk1/git_repo/xuxueli/xxl-job/doc/db/tables_xxl_job.sql;

⚙️ 步骤3：配置修改

# 文件路径: xxl-job-admin/src/main/resources/application.properties

# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=数据库用户名
spring.datasource.password=数据库密码

# 端口配置
server.port=8080

▶️ 步骤4：编译启动

# 编译项目
mvn clean package -DskipTests

# 启动管理端
java -jar xxl-job-admin/target/xxl-job-admin-*.jar

3.2 Docker快速部署 [生产环境]

[!TIP] Docker部署方式适合生产环境，简化环境配置和版本管理

📦 步骤1：拉取镜像

docker pull xuxueli/xxl-job-admin

▶️ 步骤2：启动容器

docker run -d -p 8080:8080 \
  -e PARAMS="--spring.datasource.url=jdbc:mysql://数据库IP:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai \
  --spring.datasource.username=数据库用户名 \
  --spring.datasource.password=数据库密码" \
  --name xxl-job-admin \
  xuxueli/xxl-job-admin

3.3 部署验证

启动成功后，访问 http://localhost:8080/xxl-job-admin 进入管理界面，使用默认账号密码（admin/123456）登录。

图2：XXL-JOB调度日志界面，展示任务执行记录和结果

四、运维工具箱

4.1 启停脚本

Bash版本（Linux/Mac）

#!/bin/bash
# 文件路径: xxl-job-admin.sh
APP_NAME="xxl-job-admin"
JAR_FILE="xxl-job-admin/target/xxl-job-admin-*.jar"

case $1 in
start)
  echo "Starting $APP_NAME..."
  nohup java -jar $JAR_FILE >/dev/null 2>&1 &
  echo "$APP_NAME started successfully"
  ;;
stop)
  echo "Stopping $APP_NAME..."
  pid=$(ps -ef | grep $APP_NAME | grep -v grep | awk '{print $2}')
  if [ -n "$pid" ]; then
    kill -9 $pid
    echo "$APP_NAME stopped successfully"
  else
    echo "$APP_NAME is not running"
  fi
  ;;
restart)
  $0 stop
  sleep 2
  $0 start
  ;;
status)
  pid=$(ps -ef | grep $APP_NAME | grep -v grep | awk '{print $2}')
  if [ -n "$pid" ]; then
    echo "$APP_NAME is running with pid: $pid"
  else
    echo "$APP_NAME is not running"
  fi
  ;;
*)
  echo "Usage: $0 {start|stop|restart|status}"
  ;;
esac

PowerShell版本（Windows）

# 文件路径: xxl-job-admin.ps1
$appName = "xxl-job-admin"
$jarFile = Get-ChildItem -Path "xxl-job-admin/target" -Filter "xxl-job-admin-*.jar" | Select-Object -First 1

function Start-App {
    Write-Host "Starting $appName..."
    Start-Process java -ArgumentList "-jar", "`"$($jarFile.FullName)`"" -NoNewWindow -RedirectStandardOutput "NUL" -RedirectStandardError "NUL"
    Write-Host "$appName started successfully"
}

function Stop-App {
    Write-Host "Stopping $appName..."
    $process = Get-Process java | Where-Object { $_.CommandLine -like "*$appName*" }
    if ($process) {
        $process | Stop-Process -Force
        Write-Host "$appName stopped successfully"
    } else {
        Write-Host "$appName is not running"
    }
}

switch ($args[0]) {
    "start" { Start-App }
    "stop" { Stop-App }
    "restart" { Stop-App; Start-Sleep -Seconds 2; Start-App }
    "status" {
        $process = Get-Process java -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -like "*$appName*" }
        if ($process) {
            Write-Host "$appName is running with pid: $($process.Id)"
        } else {
            Write-Host "$appName is not running"
        }
    }
    default { Write-Host "Usage: .\xxl-job-admin.ps1 {start|stop|restart|status}" }
}

4.2 配置备份策略

#!/bin/bash
# 文件路径: backup-xxl-job-config.sh

# 备份目录
BACKUP_DIR="/data/backup/xxl-job"
# 配置文件路径
CONFIG_FILE="xxl-job-admin/src/main/resources/application.properties"
# 数据库配置
DB_NAME="xxl_job"
DB_USER="数据库用户名"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 备份配置文件
cp $CONFIG_FILE $BACKUP_DIR/application_$(date +%Y%m%d).properties

# 备份数据库
mysqldump -u $DB_USER -p $DB_NAME > $BACKUP_DIR/xxl_job_$(date +%Y%m%d).sql

# 保留最近30天的备份
find $BACKUP_DIR -type f -mtime +30 -delete

4.3 日志查看

# 实时查看日志
tail -f /data/applogs/xxl-job/xxl-job-admin.log

# 查看错误日志
grep -i "error" /data/applogs/xxl-job/xxl-job-admin.log

# 查看特定日期的日志
grep "2023-10-01" /data/applogs/xxl-job/xxl-job-admin.log

五、常见故障速查

5.1 数据库连接失败

问题现象：启动时报错"Could not get JDBC Connection" 解决方案：

1. 检查数据库服务是否正常运行
2. 验证数据库连接参数是否正确
3. 确认数据库用户权限是否足够
4. 检查网络是否通畅，防火墙是否开放端口

5.2 任务调度失败

问题现象：任务状态显示失败，执行日志为空 解决方案：

1. 检查执行器是否在线
2. 验证任务参数是否正确
3. 检查执行器日志是否有错误信息
4. 确认任务处理逻辑是否存在异常

5.3 管理界面无法访问

问题现象：访问http://localhost:8080/xxl-job-admin无响应 解决方案：

1. 检查服务是否启动成功
2. 确认端口是否被占用
3. 检查防火墙设置
4. 查看应用日志定位错误原因

5.4 执行器注册失败

问题现象：执行器列表显示离线状态 解决方案：

1. 检查执行器配置中的注册地址是否正确
2. 确认执行器服务是否正常运行
3. 检查执行器与管理端网络是否通畅
4. 查看执行器日志获取详细错误信息

六、扩展阅读

• 官方文档：项目根目录下的"XXL-JOB官方文档.md"
• 代码示例：
  • Spring Boot集成示例：xxl-job-executor-sample-springboot/
  • 无框架集成示例：xxl-job-executor-sample-frameless/
  • AI任务示例：xxl-job-executor-sample-springboot-ai/
• 架构设计：项目根目录下的"XXL-JOB架构图.key"