XXL-Job 分布式调度：可视化任务管理 + MySQL 初始化 + 容器化部署

Wed, 15 Nov 2023 00:00:00 +0800

XXL-Job 是国内最流行的分布式任务调度平台——替代 cron / ScheduledExecutorService 的核心组件。本篇把 Docker 化部署、MySQL 初始化、调度中心 / 执行器接入、告警通知整理清楚。

阅读对象：Java 后端 / 运维工程师 覆盖范围：XXL-Job 调度中心部署 + MySQL 初始化表结构 + 执行器注册 + 任务路由策略（轮询 / 故障转移 / 分片广播）+ 告警邮件 + docker-compose 完整集成

一、为什么需要分布式调度

传统定时任务的痛点：

单机 cron：服务器挂了任务就没了
ScheduledExecutorService：分布式下会重复执行（3 台机器都跑）
手动控制：凌晨 3 点被叫起来手动跑批

XXL-Job 的解决方案：

能力	说明
可视化管理	Web 端配置任务、查看日志、触发重跑
分布式执行	任务在多台执行器中只跑一次（通过路由策略）
任务分片	1 个任务广播到 10 台机器并行处理（10x 提速）
失败重试	自动重试 N 次，指数退避
告警通知	任务失败邮件 / 钉钉 / 飞书通知
GLUE 模式	Web 端直接写 Java / Shell / Python 脚本
任务依赖	父任务完成触发子任务（DAG）

When to use XXL-Job：

替代 crontab（跨服务器去重 + 可视化）

跑批任务（日终结算、数据归档）

第三方接口同步（每 5 分钟拉一次数据）

定时清理（30 天前的日志）

订单超时关闭（每分钟扫描一次）

二、架构原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


┌──────────────────┐ ┌──────────────────┐
│ 调度中心 (Admin) │◄──────────────►│ 执行器 (Executor)│
│ - 任务配置 │ 注册 │ - 业务服务 │
│ - 触发调度 │ │ - 接收任务 │
│ - 日志收集 │ │ - 执行回调 │
│ - 告警通知 │ │ │
└────────┬─────────┘ └──────────────────┘
 │
 ▼
 ┌──────────┐
 │ MySQL │
 │ (元数据) │
 └──────────┘

调度中心（Admin）：独立部署，Web 管理界面
执行器（Executor）：嵌入到业务服务里，通过 jar 包依赖
MySQL：存任务配置 / 执行日志 / 调度锁

核心协议：执行器启动时主动注册到调度中心；调度中心触发后通过 RPC 调执行器。

三、MySQL 初始化

3.1 下载 SQL 脚本

1
2


# XXL-Job 2.4.0 表结构
wget https://github.com/xuxueli/xxl-job/blob/2.4.0/doc/db/tables_xxl_job.sql

完整表结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


CREATE DATABASE IF NOT EXISTS `xxl_job` DEFAULT CHARSET utf8mb4;

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,
 `alarm_email` varchar(255) DEFAULT NULL,
 `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',
 `executor_route_strategy` varchar(50) DEFAULT NULL,
 `executor_handler` varchar(255) DEFAULT NULL,
 `executor_param` varchar(512) DEFAULT NULL,
 `executor_block_strategy` varchar(50) DEFAULT NULL,
 `executor_timeout` int(11) NOT NULL DEFAULT '0',
 `executor_fail_retry_count` int(11) NOT NULL DEFAULT '0',
 `glue_type` varchar(50) NOT NULL COMMENT 'GLUE类型',
 `glue_source` mediumtext COMMENT 'GLUE源代码',
 `glue_remark` varchar(128) DEFAULT NULL,
 `glue_updatetime` datetime DEFAULT NULL,
 `child_jobid` varchar(255) DEFAULT NULL,
 `trigger_status` tinyint(4) NOT NULL DEFAULT '0',
 `trigger_last_time` bigint(13) NOT NULL DEFAULT '0',
 `trigger_next_time` bigint(13) NOT NULL DEFAULT '0',
 PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 还有：xxl_job_log, xxl_job_log_report, xxl_job_logglue, xxl_job_registry,
-- xxl_job_group, xxl_job_user, xxl_job_lock

8 张表：

表名	作用
`xxl_job_info`	任务配置
`xxl_job_log`	任务执行日志
`xxl_job_log_report`	日志报表
`xxl_job_logglue`	GLUE 源码历史
`xxl_job_registry`	执行器注册表
`xxl_job_group`	执行器分组
`xxl_job_user`	调度中心用户
`xxl_job_lock`	分布式锁

3.2 初始化用户

执行完 SQL 后，默认账号：admin / 123456（生产必改！）

四、调度中心部署

4.1 拉取镜像

1

docker pull xuxueli/xxl-job-admin:2.4.0

4.2 启动容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


docker run -d --restart=always --name xxl-job-admin \
 --net=host \
 -v /home/docker/xxl-job/data:/data \
 -e PARAMS=" \
 --spring.datasource.url=jdbc:mysql://10.0.1.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai \
 --spring.datasource.username=root \
 --spring.datasource.password={{DB_PASS}}" \
 -e JAVA_OPTS="-Xms2g -Xmx2g -Xmn1g -Xss1m \
 -XX:SurvivorRatio=8 \
 -XX:MetaspaceSize=256m \
 -XX:MaxMetaspaceSize=256m \
 -XX:NativeMemoryTracking=detail" \
 xuxueli/xxl-job-admin:2.4.0

关键参数：

--net=host：管理端口 8080 直接暴露
PARAMS：MySQL 连接信息
JAVA_OPTS：JVM 调优
数据卷 /data 持久化日志

4.3 访问调度中心

1
2


http://<IP>:8080/xxl-job-admin
默认账号：admin / 123456

4.4 docker-compose 完整版

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


version: "3"
services:
 mysql:
 image: mysql:8.0
 container_name: xxl-job-mysql
 restart: always
 environment:
 MYSQL_ROOT_PASSWORD: {{DB_ROOT_PASS}}
 volumes:
 - /home/xxl-job/mysql:/var/lib/mysql
 command: --default-authentication-plugin=mysql_native_password

 xxl-job-admin:
 image: xuxueli/xxl-job-admin:2.4.0
 container_name: xxl-job-admin
 restart: always
 depends_on:
 - mysql
 ports:
 - "8080:8080"
 volumes:
 - /home/xxl-job/logs:/data/applogs
 environment:
 PARAMS: >
 --spring.datasource.url=jdbc:mysql://mysql:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8
 --spring.datasource.username=root
 --spring.datasource.password={{DB_ROOT_PASS}}
 JAVA_OPTS: "-Xms1g -Xmx1g"

首次启动：

启动 MySQL 容器
手动导入 tables_xxl_job.sql
启动 xxl-job-admin

五、执行器接入（业务服务）

5.1 添加依赖

1
2
3
4
5


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

5.2 配置 application.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


xxl:
 job:
 admin:
 addresses: http://xxl-job-admin.internal.example.com:8080/xxl-job-admin
 executor:
 appname: my-service
 address:
 ip:
 port: 9999
 logpath: /app/logs/xxl-job/jobhandler
 logretentiondays: 30
 accessToken: {{XXL_JOB_TOKEN}}

5.3 写任务 Handler

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Component
@JobHandler(value = "demoJobHandler")
public class DemoJobHandler extends IJobHandler {

 @Override
 public ReturnT<String> execute(String param) throws Exception {
 // 业务逻辑
 log.info("XXL-JOB Hello, param: {}", param);
 return ReturnT.SUCCESS;
 }
}

或者注解方式：

1
2
3
4
5


@XxlJob("myJobHandler")
public ReturnT<String> myJobHandler() throws Exception {
 // 业务逻辑
 return ReturnT.SUCCESS;
}

5.4 启动服务

业务服务启动时自动注册到调度中心，30 秒内在 Admin 后台 → 执行器管理看到。

六、任务配置

6.1 创建执行器

Admin → 执行器管理 → 新增：

1
2
3
4


AppName：my-service
名称：我的服务
注册方式：自动注册
机器地址：（自动填入）

6.2 创建任务

Admin → 任务管理 → 新增：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


执行器：my-service
任务描述：每日订单结算
调度类型：CRON
Cron：0 0 2 * * ? # 每天凌晨 2 点
运行模式：BEAN
JobHandler：demoJobHandler
路由策略：第一个
阻塞处理策略：单机串行
失败重试：3 次
告警邮件：ops@example.com

6.3 路由策略详解

策略	行为	适用
第一个	固定选第一台	任务不能并行
轮询	1→2→3→1→2→3	负载均衡
随机	随机选一台	简单场景
一致性 HASH	同参数同机器	分片场景
最不经常使用	选使用最少的	性能均衡
故障转移	失败后切下一台	高可用
忙碌转移	跳过忙碌选空闲	实时任务
分片广播	所有机器都跑	并行处理

6.4 分片广播实战

场景：10 万条订单待结算，1 台机器跑要 1 小时。

配置：

1

路由策略：分片广播

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@XxlJob("settleOrdersJobHandler")
public ReturnT<String> settleOrdersJobHandler() throws Exception {
 // 分片参数
 int shardIndex = XxlJobHelper.getShardIndex(); // 当前分片（0 ~ shardTotal-1）
 int shardTotal = XxlJobHelper.getShardTotal(); // 总分片数

 // 假设有 10 万条待结算订单
 int total = 100000;
 int pageSize = total / shardTotal + 1;
 int from = shardIndex * pageSize;
 int to = Math.min(from + pageSize, total);

 // 处理 [from, to) 范围的订单
 List<Order> orders = orderDao.findPending(from, to);
 for (Order order : orders) {
 settle(order);
 }

 return ReturnT.SUCCESS;
}

效果：

5 台执行器 → 每台处理 2 万条 → 5x 提速

七、GLUE 模式

Web 端直接写代码——不用改业务服务：

7.1 GLUE Java

任务管理 → 选任务 → GLUE IDE → 写 Java：

1
2
3
4
5
6
7
8


public class GlueJobHandler extends IJobHandler {
 @Override
 public ReturnT<String> execute(String param) throws Exception {
 // 直接写业务逻辑
 // 注意：只能用 JDK 内置类，第三方类用不了
 return ReturnT.SUCCESS;
 }
}

适用：临时脚本（数据修复、临时跑批）。

7.2 GLUE Shell

1
2
3


#!/bin/bash
echo "xxl-job: hello shell"
echo "参数：$1"

7.3 GLUE Python

1
2
3
4
5
6


#!/usr/bin/env python
# -*- coding: UTF-8 -*-
import os
import sys
print("xxl-job: hello python")
print("参数：", sys.argv[1])

7.4 GLUE PHP / Node.js

类似，不展开。

八、告警通知

8.1 邮件告警

任务配置：

1

告警邮件：ops@example.com

Admin application.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


spring:
 mail:
 host: smtp.example.com
 port: 465
 username: noreply@example.com
 password: {{SMTP_PASS}}
xxl:
 job:
 triggerpool:
 fast:
 max: 200

8.2 钉钉告警

自定义告警实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Component
public class DingTalkJobAlarm implements JobAlarm {
 @Override
 public boolean doAlarm(XxlJobInfo info, XxlJobLog log) {
 // 调钉钉 Webhook
 String text = String.format("任务 [%s] 执行失败\n日志：%s", 
 info.getJobDesc(),
 log.getHandleMsg());
 DingTalk.send("{{DINGTALK_TOKEN}}", text);
 return true;
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Configuration
public class XxlJobConfig {
 @Bean
 public XxlJobSpringExecutor xxlJobExecutor() {
 XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
 executor.setAdminAddresses("http://xxl-job-admin:8080/xxl-job-admin");
 executor.setAppname("my-service");
 executor.setJobAlarm(new DingTalkJobAlarm()); // 自定义告警
 return executor;
 }
}

九、监控与日志

9.1 任务执行日志

任务管理 → 选任务 → 操作 → 日志 → 看每次执行：

触发时间
执行结果（成功 / 失败 / 调度失败）
耗时
失败原因（堆栈）
重试次数

日志保留：xxl.job.executor.logretentiondays=30（默认 30 天）。

9.2 调度报表

Admin → 调度报表：

1
2


成功 / 失败 / 调度失败 / 总数
按日 / 周 / 月 聚合

实战用法：每周一看上周的报表，任务成功率 < 99% 就要查问题。

9.3 告警指标

接入 Prometheus（自定义 exporter）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@Aspect
@Component
public class XxlJobMetricsAspect {
 @Around("@annotation(com.xxl.job.core.handler.annotation.XxlJob)")
 public void track(ProceedingJoinPoint pjp) throws Throwable {
 long start = System.currentTimeMillis();
 try {
 pjp.proceed();
 Metrics.counter("xxl_job_success", "name", pjp.getSignature().getName()).increment();
 } catch (Exception e) {
 Metrics.counter("xxl_job_failure", "name", pjp.getSignature().getName()).increment();
 } finally {
 Metrics.timer("xxl_job_duration", "name", pjp.getSignature().getName())
 .record(System.currentTimeMillis() - start, TimeUnit.MILLISECONDS);
 }
 }
}

十、典型坑位

10.1 任务执行但 Admin 看不到日志

症状：执行器跑完了任务，Admin 端日志查询不到。

原因：执行器 xxl.job.executor.logpath 路径配置错误。

修复：

1
2
3
4


xxl:
 job:
 executor:
 logpath: /data/applogs/xxl-job/jobhandler  # 必须是绝对路径

容器内注意：路径要在挂载卷内（否则容器重启日志丢）。

10.2 任务调度延迟

症状：任务应该 2 点跑，实际 2:05 才跑。

原因：

调度中心集群只 1 台，单点压力
任务太多（> 1000 个），调度中心处理不过来

修复：

调度中心集群部署
减少短间隔任务（每分钟 1 次的太多）
加大 xxl.job.triggerpool.fast.max

10.3 任务重复执行

症状：1 个任务在 2 台机器都跑了。

原因：路由策略选错（**不能用"分片广播"**用于只能跑 1 次的任务）。

修复：选 故障转移 或 第一个（默认）。

10.4 GLUE 模式不能用第三方类

修复：

1
2


GLUE Java 只能用 JDK 内置类
要用 Spring Bean，注解 @XxlJob

十一、生产部署清单

11.1 调度中心高可用

两台调度中心集群：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 调度中心 1
xxl-job-admin:
 ports: 8080
 environment:
 PARAMS: "--xxl.job.accessToken={{TOKEN}}"

# 调度中心 2
xxl-job-admin:
 ports: 8080
 environment:
 PARAMS: "--xxl.job.accessToken={{TOKEN}}"

执行器配置 2 个地址：

1
2
3
4


xxl:
 job:
 admin:
 addresses: http://admin1:8080/xxl-job-admin,http://admin2:8080/xxl-job-admin

任务触发时会轮询选一个调度中心。

11.2 数据库高可用

1
2
3
4
5
6


# MySQL 主从 + 读写分离
spring:
 datasource:
 url: jdbc:mysql://mysql-primary:3306/xxl_job
 # 读流量大的话可加：
 # url: jdbc:mysql:loadbalance://mysql-primary:3306,mysql-replica:3306/xxl_job

11.3 监控

Prometheus 抓 Admin metrics
告警规则：
- 任务失败率 > 5% → 告警
- 调度延迟 > 5 分钟 → 告警
- 调度中心内存 > 80% → 告警

十二、完整 docker-compose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


version: "3.8"
services:
 mysql:
 image: mysql:8.0
 container_name: xxl-job-mysql
 restart: always
 environment:
 MYSQL_ROOT_PASSWORD: {{DB_ROOT_PASS}}
 volumes:
 - /home/xxl-job/mysql:/var/lib/mysql
 networks:
 - xxl-net

 xxl-job-admin:
 image: xuxueli/xxl-job-admin:2.4.0
 container_name: xxl-job-admin
 restart: always
 depends_on:
 - mysql
 ports:
 - "8080:8080"
 volumes:
 - /home/xxl-job/logs:/data/applogs
 environment:
 PARAMS: >
 --spring.datasource.url=jdbc:mysql://mysql:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
 --spring.datasource.username=root
 --spring.datasource.password={{DB_ROOT_PASS}}
 --xxl.job.accessToken={{XXL_JOB_TOKEN}}
 JAVA_OPTS: "-Xms1g -Xmx1g -XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0"
 networks:
 - xxl-net

networks:
 xxl-net:
 driver: bridge

十三、最佳实践清单

MySQL 8.0 + utf8mb4——中文支持好
调度中心至少 2 台集群——避免单点
路由策略根据场景选：
- 跑批任务 → 故障转移（高可用）
- 同步任务 → 分片广播（并行）
- 普通定时 → 第一个（避免重复）
告警邮件必开——失败 5 分钟内收到
任务日志保留 30 天——logretentiondays=30
失败重试 3 次——临时网络抖动不报错
执行器 ip+port 唯一——xxl.job.executor.ip 显式指定
GLUE 用于临时脚本——生产任务用 @XxlJob 注解
JVM 调优：UseContainerSupport + MaxRAMPercentage
任务配置备份：MySQL 定期 dump

2024+ 视角补充

本文写于 2023-11，2024-2026 期间 XXL-Job / 分布式调度生态关键演进：

XXL-Job 2.4+ → 2.5+（2024-2025）：Spring Boot 3.x 兼容；JDK 17 强制；K8s 原生调度（不再依赖固定 IP）
XXL-Job 2.5+：内置 OpenTelemetry 集成；Web IDE 增强（GLUE Java 支持 Spring Bean）
PowerJob 5.x（2024-2025）：K8s 原生 Worker（动态注册）；DAG 工作流 2.0；MapReduce 性能 10x——vs XXL-JOB 更现代
DolphinScheduler 3.2+（2024-2026）：Apache 顶级项目；大数据集成（Spark / Flink / Hive）；K8s 调度原生；多租户 + 工作流 3.0
Airflow 2.10+（2024-2026）：Python 系首选；TaskFlow API（Pythonic DAG）；Kubernetes Executor 2.0
Temporal 1.25+（2024-2026）：Workflow-as-Code 之王——状态机 + 长期运行任务首选
KubeVela 1.10+：云原生应用编排——微服务编排 + 灰度发布
Serverless Cron：AWS EventBridge Scheduler / 阿里云定时任务 / GCP Cloud Scheduler 2024+ 仍是云端首选

实战建议（2025-2026 视角）：

Java 业务定时任务 → XXL-Job 2.5+（轻量、上手快）或 PowerJob 5.x（更现代）
大数据 / 离线数仓 → DolphinScheduler 3.2+（Apache 顶级项目）
Python 系 → Airflow 2.10+
复杂工作流 / 长期任务 → Temporal 1.25+（2024-2026 趋势）
Serverless / 简单定时 → 云厂商 EventBridge / 定时任务

下一步

想看 JDK 自建镜像实战（Alpine / Debian / Ubuntu）→ JDK 自建镜像实战
想看 Java 应用 Docker 化（Tomcat / Spring Boot 打包）→ Java 应用 Docker 化
想看 Java 微服务治理（Sentinel 限流 / Spring Boot Admin）→ Java 微服务治理
想看 Nginx 自建镜像实战（反代安全加固）→ Nginx 自建镜像实战

调度平台 on Liangweidong's blog