建立完應用後,需要接入執行器才能執行任務。
普通應用接入執行器
高代碼方式通過SDK接入
高代碼方式通過整合XXL-JOB SDK,開發人員需在代碼中實現任務處理邏輯,並註冊對應的Bean名稱,控制台僅需配置該Bean名稱即可觸發執行,適用於複雜商務邏輯情境,支援Java、Go和Python。
支援自動註冊與手動錄入。
自動註冊
自動註冊需要業務方依賴XXL-JOB SDK,進行接入配置,應用啟動成功將自動註冊。
查看接入配置
在頁面左上方選擇目標地區。
單擊目標執行個體ID,在左側導覽列選擇应用管理。
單擊目標應用執行器數量列下的接入按鈕。
接入方式選擇自動接入,並根據接入方式修改配置。
引入SDK接入執行器
Java SDK
在pom中引入“xxl-job-core”的maven依賴。
初始化執行器。
@Configuration public class XxlJobConfig { private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class); @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.address}") private String address; @Value("${xxl.job.executor.ip}") private String ip; @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() { logger.info(">>>>>>>>>>> xxl-job config init."); XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor(); xxlJobSpringExecutor.setAdminAddresses(adminAddresses); xxlJobSpringExecutor.setAppname(appname); xxlJobSpringExecutor.setAddress(address); xxlJobSpringExecutor.setIp(ip); xxlJobSpringExecutor.setPort(port); xxlJobSpringExecutor.setAccessToken(accessToken); xxlJobSpringExecutor.setLogPath(logPath); xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays); return xxlJobSpringExecutor; } }
Go SDK
執行以下命令,使用最新的tag拉取Go版本的XXLJOB SDK。
go get github.com/xxl-job/xxl-job-executor-go@{最新的tag}編寫業務代碼。
package main import ( "context" "fmt" xxl "github.com/xxl-job/xxl-job-executor-go" "github.com/xxl-job/xxl-job-executor-go/example/task" "log" ) func main() { exec := xxl.NewExecutor( xxl.ServerAddr("xxxxxx"), //請求地址,控制台應用管理接入配置擷取 xxl.AccessToken("xxxxxxx"), //請求令牌,控制台應用管理接入配置擷取 xxl.ExecutorPort("9999"), //預設9999(非必填) xxl.RegistryKey("golang-jobs"), //執行器名稱 xxl.SetLogger(&logger{}), //自訂日誌 ) exec.Init() exec.Use(customMiddleware) //設定日誌查看handler exec.LogHandler(customLogHandle) //註冊任務handler exec.RegTask("task.test", task.Test) exec.RegTask("task.test2", task.Test2) exec.RegTask("task.panic", task.Panic) log.Fatal(exec.Run()) } // 自訂Tlog器 func customLogHandle(req *xxl.LogReq) *xxl.LogRes { return &xxl.LogRes{Code: xxl.SuccessCode, Msg: "", Content: xxl.LogResContent{ FromLineNum: req.FromLineNum, ToLineNum: 2, LogContent: "這個是自訂日誌handler", IsEnd: true, }} } // xxl.Logger介面實現 type logger struct{} func (l *logger) Info(format string, a ...interface{}) { fmt.Println(fmt.Sprintf("自訂日誌 - "+format, a...)) } func (l *logger) Error(format string, a ...interface{}) { log.Println(fmt.Sprintf("自訂日誌 - "+format, a...)) } // 自訂中介軟體 func customMiddleware(tf xxl.TaskFunc) xxl.TaskFunc { return func(cxt context.Context, param *xxl.RunReq) string { log.Println("I am a middleware start") res := tf(cxt, param) log.Println("I am a middleware end") return res } }
Python SDK
拉取依賴。
pip install pyxxl # 如果日誌需要寫入redis pip install "pyxxl[redis]" # 如果需要從.env載入配置 pip install "pyxxl[dotenv]" # 安裝所有功能 pip install "pyxxl[all]"編寫業務代碼。
import asyncio import time from pyxxl import ExecutorConfig, PyxxlRunner from pyxxl.ctx import g config = ExecutorConfig( xxl_admin_baseurl="http://xxljob-1b3fd8196eb.schedulerx.mse.aliyuncs.com/api/", executor_app_name="xueren-test", access_token="default_token", # executor_listen_host="0.0.0.0", # 如果xxl-admin可以直連executor的ip,可以不填寫executor_listen_host ) app = PyxxlRunner(config) @app.register(name="demoJobHandler") async def test_task(): # you can get task params with "g" g.logger.info("get executor params: %s" % g.xxl_run_data.executorParams) for i in range(10): g.logger.warning("test logger %s" % i) await asyncio.sleep(5) return "成功..." @app.register(name="sync_func") def test_task4(): # 如果要在xxl-admin上看到執行日誌,列印日誌的時候務必用g.logger來列印,預設只列印info及以上的日誌 n = 1 g.logger.info("Job %s get executor params: %s" % (g.xxl_run_data.jobId, g.xxl_run_data.executorParams)) # 如果同步任務裡面有迴圈,為了支援cancel操作,必須每次都判斷g.cancel_event. while n <= 10 and not g.cancel_event.is_set(): # 如果不需要從xxl-admin中查看日誌,可以用自己的logger g.logger.info( "log to {} logger test_task4.{},params:{}".format( g.xxl_run_data.jobId, n, g.xxl_run_data.executorParams, ) ) time.sleep(2) n += 1 return "成功3" if __name__ == "__main__": app.run_executor()
手動錄入
手動錄入可以人工維護執行器的地址資訊,地址格式參考http://192.168.0.1:9999/。
在頁面左上方選擇目標地區。
單擊目標執行個體ID,在左側導覽列選擇应用管理。
單擊目標應用執行器數量列下的接入按鈕。
接入方式選擇手動錄入,並輸入執行器地址。
低代碼方式通過Agent接入
低代碼方式通過手動部署Agent接入執行器,使用者可在控制台直接編寫商務邏輯,適用於指令碼任務、巨量資料任務、SQL任務及AI任務等情境。
支援通過安裝包部署、通過Docker啟動以及通過Kubernetes啟動。
安裝包部署
部署前提
已安裝JDK17及以上版本。
下載安裝包
wget https://schedulerx3.oss-cn-hangzhou.aliyuncs.com/xxljob/schedulerx3-agent-1.0.0-bin.tar.gz解壓與配置:
# 解壓 tar -zxvf schedulerx3-agent-1.0.0-bin.tar.gz cd schedulerx3-agent-1.0.0-bin解壓後的目錄結構:
schedulerx3-agent-1.0.0-bin/ ├── bin/ # 啟動指令碼目錄 ├── conf/ # 設定檔目錄 │ ├── application.yml # 應用配置 │ └── logback-spring.xml # 日誌配置 ├── lib/ # 依賴 jar 包目錄 └── logs/ # 日誌目錄(運行時自動建立) ├── stdout.log # 標準輸出日誌 ├── stderr.log # 標準錯誤日誌 ├── worker.log # 應用日誌 ├── error.log # 錯誤記錄檔 ├── gc.log # GC 日誌 └── archive/ # 歸檔日誌目錄編輯設定檔
conf/application.yml,根據XXL-JOB執行個體配置如下參數:xxl: job: admin-addresses: {服務接入地址} access-token: {應用AccessToken} executor: appname: {應用AppName}啟動服務
Linux/Mac
# 後台啟動 ./bin/start.sh # 前台啟動(調試) ./bin/start.sh -f # 停止 ./bin/stop.sh # 重啟 ./bin/restart.sh # 查看狀態 ./bin/status.sh # 查看日誌 tail -f logs/worker.logWindows
REM 後台啟動 .\bin\start.cmd REM 前台啟動(調試) .\bin\start.cmd -f REM 停止 .\bin\stop.cmd REM 重啟 .\bin\restart.cmd REM 查看狀態 .\bin\status.cmd REM 查看日誌 type logs\worker.log
(可選)日誌配置
主要記錄檔位於
logs/目錄,任務執行日誌預設位於${user.home}/applogs/xxl-job/jobhandler。記錄檔
說明
滾動策略
stdout.log標準輸出日誌(開機記錄)
指令碼重新導向
stderr.log標準錯誤日誌(異常堆棧)
指令碼重新導向
worker.log應用日誌(INFO 及以上)
100MB/檔案,保留 30 天
error.log錯誤記錄檔(ERROR 層級)
50MB/檔案,保留 60 天
gc.logGC 日誌
JVM 參數配置
heap_dump.hprof堆轉儲檔案(OOM 時產生)
-
archive/歸檔日誌目錄(自動壓縮 .gz)
-
編輯
conf/logback-spring.xml可調整日誌的列印輸出。<!-- 修改根記錄層級 --> <root level="INFO"> <appender-ref ref="STDOUT" /> <appender-ref ref="FILE" /> </root> <!-- 修改特定包的記錄層級 --> <logger name="com.aliyun.schedulerx" level="DEBUG" /> <logger name="com.xxl.job" level="DEBUG" />
(可選)JVM參數配置,根據實際負載調整 JVM 記憶體大小。
# Linux/Mac - 臨時指定 JAVA_OPTS="-Xms2g -Xmx4g" ./bin/start.sh # Linux/Mac - 永久修改 vim bin/start.sh # 編輯 JAVA_OPTS 變數 # Windows - 臨時指定 set JAVA_OPTS=-Xms2g -Xmx4g .\bin\start.cmd # Windows - 永久修改 notepad bin\start.cmd # 編輯 JAVA_OPTS 變數
通過Docker啟動
方式一:使用公開鏡像部署
公用鏡像提供了常規指令碼的運行能力,系統預裝了python、nodejs、go環境。可直接從鏡像倉庫拉取並運行,無需構建。
# 拉取鏡像
docker pull schedulerx-registry.cn-hangzhou.cr.aliyuncs.com/schedulerx3/schedulerx3-agent:1.0.0
# 自訂配置運行
docker run -d \
--name schedulerx3-agent \
-p 9999:9999 \
// 按需配置JVM參數
-e JAVA_OPTS="-Xms1g -Xmx2g" \
-e SCHEDULERX3_ADMIN_ADDRESSES="{服務接入地址}" \
-e SCHEDULERX3_EXECUTOR_APPNAME="{應用AppName}" \
-e SCHEDULERX3_ACCESS_TOKEN="{應用AccessToken}" \
-v $(pwd)/logs:/opt/schedulerx3-agent/logs \
--restart unless-stopped \
schedulerx-registry.cn-hangzhou.cr.aliyuncs.com/schedulerx3/schedulerx3-agent:1.0.0方式二:基於tar包自行構建鏡像
業務有額外的外部組件依賴或自訂基礎鏡像,可基於下載的 tar 包自行構建鏡像,並發布到自有的鏡像倉庫。
# 下載安裝包
wget https://schedulerx3.oss-cn-hangzhou.aliyuncs.com/xxljob/schedulerx3-agent-1.0.0-bin.tar.gz
# Docker 鏡像構建
docker build -t schedulerx3-agent:1.0.0 -f Dockerfile .對應Dockerfile參考如下:
############################################
### 當前Dockerfile根據各自業務需要安裝所需的組件
############################################
# 自行配置基礎鏡像
FROM hub.docker.xxx.com/library/openjdk:17.0.1-jdk-bullseye
LABEL maintainer="SchedulerX Team"
LABEL description="SchedulerX3 Agent - XXL-Job Executor"
LABEL version="2.4.2"
# 配置阿里雲鏡像源
RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list && \
sed -i 's|security.debian.org/debian-security|mirrors.aliyun.com/debian-security|g' /etc/apt/sources.list
# 安裝基礎工具、Python3、Node.js 和 Go
RUN apt-get update && \
apt-get install -y python3 python3-distutils curl wget ca-certificates nodejs npm golang-go && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
# 使用官方指令碼安裝 pip
RUN curl https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py && \
python3 /tmp/get-pip.py && \
rm -f /tmp/get-pip.py && \
ln -sf /usr/bin/python3 /usr/bin/python
# 設定 Go 環境變數
ENV GOPATH=/root/go
ENV PATH=$GOPATH/bin:$PATH
ENV GO111MODULE=on
# 複製 tar 包到鏡像
COPY schedulerx3-agent-*-bin.tar.gz /tmp/schedulerx3-agent.tar.gz
# 解壓 tar 包到指定目錄(去掉頂層目錄)
RUN mkdir -p /opt/schedulerx3-agent && \
tar -xzf /tmp/schedulerx3-agent.tar.gz --strip-components=1 -C /opt/schedulerx3-worker && \
chmod +x /opt/schedulerx3-agent/bin/*.sh && \
mkdir -p /opt/schedulerx3-agent/logs && \
rm -f /tmp/schedulerx3-agent.tar.gz
# 設定工作目錄
WORKDIR /opt/schedulerx3-agent
# 暴露連接埠
EXPOSE 9999
# 啟動命令(使用 start.sh 的前台模式)
CMD ["bin/start.sh", "-f"]
通過Kubernetes啟動
建立
schedulerx3-agent.yaml檔案通過Deployment部署。apiVersion: apps/v1 kind: Deployment metadata: name: schedulerx3-agent labels: app: schedulerx3-agent spec: replicas: 1 selector: matchLabels: app: schedulerx3-agent template: metadata: labels: app: schedulerx3-agent spec: containers: - name: schedulerx3-agent image: schedulerx-registry.cn-hangzhou.cr.aliyuncs.com/schedulerx3/schedulerx3-agent:1.0.0 imagePullPolicy: Always ports: - containerPort: 9999 env: - name: "SCHEDULERX3_ADMIN_ADDRESSES" value: "{服務接入地址}" - name: "SCHEDULERX3_EXECUTOR_APPNAME" value: "{應用AppName}" - name: "SCHEDULERX3_ACCESS_TOKEN" value: "{應用AccessToken}" livenessProbe: tcpSocket: port: 9999 timeoutSeconds: 30 initialDelaySeconds: 30部署至Kubernetes。
# 部署 kubectl apply -f schedulerx3-agent.yaml
HTTP應用接入執行器
不需要SDK接入,通過佈建網域名或K8s服務自動探索後端節點,使用HTTP協議調度。
接入K8s服務
如果HTTP應用部署在阿里雲Container ServiceACK中,推薦使用“接入K8s服務”方式。
(若已完成可跳過)將應用部署在阿里雲Container ServiceACK上,支援如下叢集類型:
ACK託管叢集,網路外掛程式為Terway
ACK Serverless叢集
ACS叢集
(若已完成可跳過)在ACK中為應用建立Service,支援服務類型:
ClusterIP
LoadBalancer
在頁面左上方選擇目標地區。
單擊目標執行個體ID,在左側導覽列選擇应用管理。
單擊目標應用執行器數量列下的接入按鈕。
在接入執行器頁面,接入方式選擇接入K8s服務,並完成接入K8s服務參數配置,單擊確定完成接入。
接入成功後,執行期數量會發生改變,點擊查看,可以看到後端Pod列表。
手動錄入網域名稱
如果應用沒有部署在ACK上(比如使用ECS部署),也可以通過內網網域名稱調度HTTP任務。
(若已完成可跳過)為HTTP應用建立一個網關,會自動產生一個內網網域名稱,比如使用NLB。
在頁面左上方選擇目標地區。
單擊目標執行個體ID,在左側導覽列選擇应用管理。
單擊目標應用執行器數量列下的接入按鈕。
在接入執行器頁面,接入方式選擇錄入網域名稱,並配置內網網域名稱。