202 lines
5.0 KiB
Markdown
202 lines
5.0 KiB
Markdown
# XXL-Job Starter
|
||
|
||
一个基于XXL-Job的Spring Boot Starter，提供自动配置、服务发现和容器部署支持。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ Spring Boot自动配置，简化XXL-Job集成
|
||
- ✅ 支持Nacos服务发现，自动获取XXL-Job Admin地址
|
||
- ✅ 容器部署支持，自动处理IP和端口映射
|
||
- ✅ 执行器地址自动补全协议前缀(http://)
|
||
- ✅ 环境变量动态配置，灵活适配不同部署环境
|
||
- ✅ 完善的日志记录和错误处理
|
||
|
||
## 快速开始
|
||
|
||
### 1. 添加依赖
|
||
|
||
在你的Spring Boot项目中添加以下依赖：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.tacit</groupId>
|
||
<artifactId>xxljob</artifactId>
|
||
<version>1.0.0-SNAPSHOT</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2. 启用XXL-Job
|
||
|
||
在Spring Boot主类上添加`@EnableXxlJob`注解：
|
||
|
||
```java
|
||
@SpringBootApplication
|
||
@EnableXxlJob
|
||
public class Application {
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(Application.class, args);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 配置XXL-Job
|
||
|
||
在`application.yml`或`bootstrap.yml`中添加XXL-Job配置：
|
||
|
||
```yaml
|
||
xxl:
|
||
job:
|
||
admin:
|
||
# XXL-Job Admin地址，多个地址用逗号分隔
|
||
addresses: http://localhost:8080/xxl-job-admin
|
||
# 可选，调度中心通讯TOKEN
|
||
access-token: default_token
|
||
executor:
|
||
# 执行器AppName，默认使用spring.application.name
|
||
appname: my-xxl-job-executor
|
||
# 执行器IP，默认为空表示自动获取
|
||
ip:
|
||
# 执行器端口，默认9099
|
||
port: 9999
|
||
# 执行器通讯TOKEN
|
||
access-token: default_token
|
||
# 执行器日志路径
|
||
log-path: logs/applogs/xxl-job/jobhandler
|
||
# 执行器日志保存天数
|
||
log-retention-days: 30
|
||
```
|
||
|
||
### 4. 创建JobHandler
|
||
|
||
```java
|
||
@Component
|
||
public class MyJobHandler {
|
||
|
||
@XxlJob("myJobHandler")
|
||
public ReturnT<String> execute(String param) throws Exception {
|
||
XxlJobLogger.log("XXL-Job, Hello World.");
|
||
System.out.println("执行任务: " + param);
|
||
return ReturnT.SUCCESS;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 核心配置项
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|-------|------|-------|
|
||
| xxl.job.admin.addresses | XXL-Job Admin地址 | - |
|
||
| xxl.job.admin.access-token | 调度中心通讯TOKEN | - |
|
||
| xxl.job.executor.appname | 执行器AppName | spring.application.name |
|
||
| xxl.job.executor.ip | 执行器IP | 自动获取 |
|
||
| xxl.job.executor.port | 执行器端口 | 9099 |
|
||
| xxl.job.executor.access-token | 执行器通讯TOKEN | - |
|
||
| xxl.job.executor.log-path | 执行器日志路径 | logs/applogs/xxl-job/jobhandler |
|
||
| xxl.job.executor.log-retention-days | 日志保存天数 | 30 |
|
||
|
||
### 容器部署环境变量
|
||
|
||
| 环境变量 | 说明 |
|
||
|---------|------|
|
||
| XXL_JOB_EXECUTOR_IP | 容器真实IP（宿主机IP） |
|
||
| XXL_JOB_EXECUTOR_PORT | 容器映射后的真实端口 |
|
||
| XXL_JOB_ADMIN_ADDRESSES | XXL-Job Admin地址 |
|
||
|
||
## 高级特性
|
||
|
||
### 自动服务发现
|
||
|
||
如果未配置`xxl.job.admin.addresses`，Starter会自动从Nacos注册中心发现XXL-Job Admin服务（服务名包含"xxl-job-admin"）。
|
||
|
||
### 容器部署支持
|
||
|
||
在Docker或Kubernetes环境中，执行器会自动处理IP和端口映射：
|
||
|
||
```yaml
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: my-executor
|
||
spec:
|
||
replicas: 1
|
||
template:
|
||
spec:
|
||
containers:
|
||
- name: my-executor
|
||
image: my-executor:latest
|
||
ports:
|
||
- containerPort: 9999
|
||
env:
|
||
- name: XXL_JOB_EXECUTOR_IP
|
||
valueFrom:
|
||
fieldRef:
|
||
fieldPath: status.hostIP
|
||
- name: XXL_JOB_EXECUTOR_PORT
|
||
value: "30099" # Kubernetes节点端口
|
||
- name: spring.application.name
|
||
value: my-executor
|
||
```
|
||
|
||
### 自定义执行器地址
|
||
|
||
```yaml
|
||
xxl:
|
||
job:
|
||
executor:
|
||
# 完整的执行器地址，会自动补全协议前缀
|
||
address: 192.168.3.67:9999
|
||
ip: 192.168.3.67
|
||
port: 9999
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 执行器注册失败
|
||
|
||
- 检查`xxl.job.admin.addresses`配置是否正确
|
||
- 检查网络连接是否正常
|
||
- 检查防火墙设置
|
||
|
||
### 2. 任务执行失败，提示"no protocol"
|
||
|
||
这是因为执行器地址缺少协议前缀导致的，请确保配置的地址包含`http://`前缀，或使用Starter的自动补全功能。
|
||
|
||
### 3. 容器环境下执行器地址不正确
|
||
|
||
请配置`XXL_JOB_EXECUTOR_IP`和`XXL_JOB_EXECUTOR_PORT`环境变量，指定宿主机的IP和映射后的端口。
|
||
|
||
## 开发和贡献
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
mvn clean install -DskipTests
|
||
```
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
src/
|
||
├── main/
|
||
│ ├── java/
|
||
│ │ └── com/tacit/starter/xxljob/
|
||
│ │ ├── annotation/ # 注解类
|
||
│ │ ├── properties/ # 配置属性类
|
||
│ │ └── XxlJobAutoConfiguration.java # 自动配置类
|
||
│ └── resources/
|
||
│ └── META-INF/
|
||
│ └── spring.factories # Spring Boot自动配置入口
|
||
```
|
||
|
||
## 版本依赖
|
||
|
||
- Spring Boot 2.x
|
||
- XXL-Job Core 2.5.0
|
||
- Spring Cloud Alibaba Nacos Discovery
|
||
|
||
## 许可证
|
||
|
||
MIT License
|