全部產品
Search
文件中心

:執行器管理

更新時間:Apr 21, 2026

建立完應用後,需要接入執行器才能執行任務。

普通應用接入執行器

高代碼方式通過SDK接入

高代碼方式通過整合XXL-JOB SDK,開發人員需在代碼中實現任務處理邏輯,並註冊對應的Bean名稱,控制台僅需配置該Bean名稱即可觸發執行,適用於複雜商務邏輯情境,支援Java、Go和Python。

支援自動註冊與手動錄入。

自動註冊

自動註冊需要業務方依賴XXL-JOB SDK,進行接入配置,應用啟動成功將自動註冊。

查看接入配置
  1. 登入MSE XXL-JOB控制台

  2. 在頁面左上方選擇目標地區

  3. 單擊目標執行個體ID,在左側導覽列選擇应用管理

  4. 單擊目標應用執行器數量列下的接入按鈕。

  5. 接入方式選擇自動接入,並根據接入方式修改配置。

引入SDK接入執行器
Java SDK
  1. 在pom中引入“xxl-job-core”的maven依賴。

  2. 初始化執行器。

    @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
  1. 執行以下命令,使用最新的tag拉取Go版本的XXLJOB SDK。

    go get github.com/xxl-job/xxl-job-executor-go@{最新的tag}
  2. 編寫業務代碼。

    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
  1. 拉取依賴。

    pip install pyxxl
    
    # 如果日誌需要寫入redis
    pip install "pyxxl[redis]"
    
    # 如果需要從.env載入配置
    pip install "pyxxl[dotenv]"
    
    # 安裝所有功能
    pip install "pyxxl[all]"
  2. 編寫業務代碼。

    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/

  1. 登入MSE XXL-JOB控制台

  2. 在頁面左上方選擇目標地區

  3. 單擊目標執行個體ID,在左側導覽列選擇应用管理

  4. 單擊目標應用執行器數量列下的接入按鈕。

  5. 接入方式選擇手動錄入,並輸入執行器地址

低代碼方式通過Agent接入

低代碼方式通過手動部署Agent接入執行器,使用者可在控制台直接編寫商務邏輯,適用於指令碼任務、巨量資料任務、SQL任務及AI任務等情境。

支援通過安裝包部署、通過Docker啟動以及通過Kubernetes啟動。

安裝包部署

部署前提

已安裝JDK17及以上版本。

  1. 下載安裝包

    wget https://schedulerx3.oss-cn-hangzhou.aliyuncs.com/xxljob/schedulerx3-agent-1.0.0-bin.tar.gz
  2. 解壓與配置:

    # 解壓
    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}
  3. 啟動服務

    • Linux/Mac

      # 後台啟動
      ./bin/start.sh
      
      # 前台啟動(調試)
      ./bin/start.sh -f
      
      # 停止
      ./bin/stop.sh
      
      # 重啟
      ./bin/restart.sh
      
      # 查看狀態
      ./bin/status.sh
      
      # 查看日誌
      tail -f logs/worker.log
    • Windows

      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
  4. (可選)日誌配置

    • 主要記錄檔位於logs/目錄,任務執行日誌預設位於${user.home}/applogs/xxl-job/jobhandler

      記錄檔

      說明

      滾動策略

      stdout.log

      標準輸出日誌(開機記錄)

      指令碼重新導向

      stderr.log

      標準錯誤日誌(異常堆棧)

      指令碼重新導向

      worker.log

      應用日誌(INFO 及以上)

      100MB/檔案,保留 30 天

      error.log

      錯誤記錄檔(ERROR 層級)

      50MB/檔案,保留 60 天

      gc.log

      GC 日誌

      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" />
  5. (可選)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啟動

  1. 建立 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
  2. 部署至Kubernetes。

    # 部署
    kubectl apply -f schedulerx3-agent.yaml

HTTP應用接入執行器

不需要SDK接入,通過佈建網域名或K8s服務自動探索後端節點,使用HTTP協議調度。

接入K8s服務

如果HTTP應用部署在阿里雲Container ServiceACK中,推薦使用“接入K8s服務”方式。

  1. (若已完成可跳過)將應用部署在阿里雲Container ServiceACK上,支援如下叢集類型:

    • ACK託管叢集,網路外掛程式為Terway

    • ACK Serverless叢集

    • ACS叢集

  2. (若已完成可跳過)在ACK中為應用建立Service,支援服務類型:

    • ClusterIP

    • LoadBalancer

  3. 登入MSE XXL-JOB控制台

  4. 在頁面左上方選擇目標地區

  5. 單擊目標執行個體ID,在左側導覽列選擇应用管理

  6. 單擊目標應用執行器數量列下的接入按鈕。

  7. 接入執行器頁面,接入方式選擇接入K8s服務,並完成接入K8s服務參數配置,單擊確定完成接入。

接入成功後,執行期數量會發生改變,點擊查看,可以看到後端Pod列表。

手動錄入網域名稱

如果應用沒有部署在ACK上(比如使用ECS部署),也可以通過內網網域名稱調度HTTP任務。

  1. (若已完成可跳過)為HTTP應用建立一個網關,會自動產生一個內網網域名稱,比如使用NLB。

  2. 在頁面左上方選擇目標地區

  3. 單擊目標執行個體ID,在左側導覽列選擇应用管理

  4. 單擊目標應用執行器數量列下的接入按鈕。

  5. 接入執行器頁面,接入方式選擇錄入網域名稱,並配置內網網域名稱。