| name | xxl-job-xugudb-adapter |
| description | XXL-JOB 分布式任务调度框架与虚谷数据库（XuguDB）集成适配指南。当用户需要在 Spring Boot 项目中使用 XXL-JOB 连接 XuguDB 时使用此技能，包括任务调度配置、数据源设置、执行器配置、任务处理器编写、路由策略、分片任务等。适用于定时任务、批量数据处理、分布式计算、工作流编排等场景。 |
XXL-JOB 分布式任务调度 XuguDB 适配指南
概述
本指南详细介绍如何将 XXL-JOB 分布式任务调度框架与虚谷数据库（XuguDB）集成，包括完整的配置流程、使用示例和最佳实践。XXL-JOB 是一个轻量级分布式任务调度框架，支持动态任务管理、多种路由策略和故障转移。
快速开始
1. 获取适配版 XXL-JOB
由于官方 XXL-JOB 不支持 XuguDB，需要使用虚谷提供的适配版本：
2. 初始化数据库
在 XuguDB 中创建数据库：
CREATE DATABASE `xxl_job` CHARACTER SET 'utf8_bin' TIME ZONE 'GMT+08:00';
USE xxl_job;
CREATE USER `xxl_job` IDENTIFIED BY 'xxl_job';
GRANT DBA IN SCHEMA `xxl_job' TO 'xxl_job';
执行适配版提供的 SQL 初始化脚本 tables_xxl_job_xugu.sql。
3. 配置数据源
在 application.properties 中配置：
spring.datasource.driver-class-name=com.xugudb.jdbc.Driver
spring.datasource.url=jdbc:xugu://127.0.0.1:5138/xxl_job
spring.datasource.username=xxl_job
spring.datasource.password=xxl_job
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.maximum-pool-size=20
xxl.job.accessToken=default_token
4. 启动 XXL-JOB Admin
java -jar xxl-job-admin-2.3.1.jar --spring.config.location=file:./application.properties
5. 访问管理界面
- 地址：
http://localhost:8080/xxl-job-admin/toLogin
- 默认账号：
admin
- 默认密码：
123456
配置详解
数据源配置参数
| 参数 | 说明 | 推荐值 |
|---|
driver-class-name | XuguDB JDBC 驱动类 | com.xugudb.jdbc.Driver |
url | 数据库连接 URL | jdbc:xugu://host:port/db |
accessToken | 通信令牌 | default_token（建议修改） |
连接池配置
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.idle-timeout=30000
spring.datasource.hikari.max-lifetime=1800000
执行器集成
1. 添加 Maven 依赖
<dependencies>
<dependency>
<groupId>com.xuxueli</groupId>
<artifactId>xxl-job-core</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>com.xugudb</groupId>
<artifactId>xugu-jdbc</artifactId>
<version>12.3.4</version>
</dependency>
</dependencies>
2. 配置执行器
在 application.yml 中配置：
xxl:
job:
admin:
addresses: http://127.0.0.1:8080/xxl-job-admin
executor:
appname: my-executor
port: 9999
logpath: /data/applogs/xxl-job/jobhandler
logretentiondays: 30
accessToken: default_token
3. 配置执行器 Bean
@Configuration
public class XxlJobConfig {
@Value("${xxl.job.admin.addresses}")
private String adminAddresses;
@Value("${xxl.job.accessToken}")
private String accessToken;
@Value("${xxl.job.executor.appname}")
private String appname;
@Value("${xxl.job.executor.port}")
private int port;
@Value("${xxl.job.executor.logpath}")
private String logpath;
@Value("${xxl.job.executor.logretentiondays}")
private int logretentiondays;
@Bean
public XxlJobSpringExecutor xxlJobExecutor() {
XxlJobSpringExecutor executor = new XxlJobSpringExecutor();
executor.setAdminAddresses(adminAddresses);
executor.setAppname(appname);
executor.setPort(port);
executor.setLogPath(logpath);
executor.setLogRetentionDays(logretentiondays);
executor.setAccessToken(accessToken);
return executor;
}
}
任务处理器
Bean 模式任务处理器
@Component
public class MyJobHandler {
@XxlJob("myJobHandler")
public void myJobHandler() throws Exception {
String jobParam = XxlJobHelper.getJobParam();
XxlJobHelper.log("执行任务，参数：" + jobParam);
XxlJobHelper.handleSuccess("任务执行成功");
}
}
分片任务处理器
@Component
public class ShardingJobHandler {
@XxlJob("shardingJobHandler")
public void shardingJobHandler() throws Exception {
int shardIndex = XxlJobHelper.getShardIndex();
int shardTotal = XxlJobHelper.getShardTotal();
XxlJobHelper.log("分片参数：当前分片={}, 总分片={}", shardIndex, shardTotal);
List<Integer> items = getItemList();
for (int i = 0; i < items.size(); i++) {
if (i % shardTotal == shardIndex) {
processItem(items.get(i));
}
}
XxlJobHelper.handleSuccess("分片任务执行成功");
}
}
路由策略
XXL-JOB 支持多种路由策略：
- FIRST（第一个）：固定选择第一个机器执行
- LAST（最后一个）：固定选择最后一个机器执行
- ROUND（轮询）：按顺序轮流执行
- RANDOM（随机）：随机选择一台机器执行
- CONSISTENT_HASH（一致性 HASH）：每个任务按照 Hash 算法固定选择某一台机器执行
- LEAST_FREQUENTLY_USED（最不经常使用）：使用频率最低的机器优先执行
- LEAST_RECENTLY_USED（最近最久未使用）：最久未使用的机器优先执行
- FAILOVER（故障转移）：按照顺序依次进行心跳检测，第一个心跳检测成功的机器选定为目标执行器并发起调度
- BUSYOVER（忙碌转移）：按照顺序依次进行空闲检测，第一个空闲检测成功的机器选定为目标执行器并发起调度
- SHARDING_BROADCAST（分片广播）：广播触发对应集群中所有机器执行一次任务，同时系统自动传递分片参数
运行模式
XXL-JOB 支持多种运行模式：
- BEAN（Bean 模式）：任务以 Bean 方式注册到执行器，支持 @XxlJob 注解方式
- GLUE（GLUE 模式）：任务以 GLUE 代码方式运行，支持 Java、Shell、Python、Node.js、PHP、PowerShell 等
- GLUE_GROOVY（Groovy 模式）：任务以 Groovy 脚本方式运行
REST API 使用
XXL-JOB 提供完整的 REST API：
基础认证：使用管理员账号和密码
常用端点：
- 查询任务列表：
POST /api/jobinfo/pageList
- 创建任务：
POST /api/jobinfo/add
- 更新任务：
POST /api/jobinfo/update
- 删除任务：
POST /api/jobinfo/remove
- 启动任务：
POST /api/jobinfo/start
- 停止任务：
POST /api/jobinfo/stop
- 手动触发任务：
POST /api/jobinfo/trigger
数据库表结构
XXL-JOB 在 XuguDB 中自动创建以下表：
xxl_job_group：执行器信息表xxl_job_info：任务信息表xxl_job_lock：任务锁表xxl_job_log：任务日志表xxl_job_log_report：任务日志报表xxl_job_logglue：任务 GLUE 日志表xxl_job_registry：执行器注册表xxl_job_user：用户表
性能优化
1. 数据库索引
CREATE INDEX idx_job_info_job_group ON xxl_job_info(job_group);
CREATE INDEX idx_job_log_job_id ON xxl_job_log(job_id);
CREATE INDEX idx_job_log_trigger_time ON xxl_job_log(trigger_time);
2. 连接池调优
spring.datasource.hikari.minimum-idle=10
spring.datasource.hikari.maximum-pool-size=30
spring.datasource.hikari.idle-timeout=60000
3. 任务优化
- 合理设置任务超时时间
- 避免任务执行时间过长
- 合理使用分片任务
- 定期清理历史日志
故障排除
常见问题
- 数据库连接失败：检查 XuguDB 服务是否启动，JDBC 驱动版本是否兼容
- 执行器注册失败：检查调度中心地址、网络连接、访问令牌是否一致
- 任务执行失败：检查任务处理器代码，查看执行日志，确认执行器配置正确
- GLUE 模式任务失败：检查 GLUE 代码语法，确认运行环境正确
日志配置
<logger name="com.xuxueli" level="DEBUG"/>
<logger name="com.xugu" level="DEBUG"/>
最佳实践
- 使用清晰的任务描述
- 合理设置路由策略
- 避免任务执行时间过长
- 部署多个调度中心节点实现高可用
- 使用 Nginx 进行负载均衡
- 监控集群状态和任务执行情况
- 定期备份数据库
资源
注意：本指南基于 XXL-JOB v2.3.1 适配版本，确保使用正确的版本以避免兼容性问题。必须使用虚谷提供的适配版 XXL-JOB 和专用 SQL 初始化脚本。
