安装Agent以将执行器接入MSE-XXLJOB-微服务引擎-阿里云

本文介绍如何在ECS或者容器服务中安装Agent并接入MSE-XXLJOB。

方案概述

用户可在MSE控制台动态编写或修改脚本及SQL，以实现定时任务的调度与执行。

操作步骤

创建普通应用

登录XXL-JOB控制台，并在顶部菜单栏选择地域。
单击目标实例，进入实例详情页。
在左侧导航栏，选择应用管理，单击创建应用。
应用类型选择普通应用，其它参数根据实际情况填写，然后单击确定。

通过Agent接入执行器

支持通过安装包部署、通过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-worker-2.4.2-jdk17-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.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

（可选）日志配置

主要日志文件位于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" />

（可选）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

创建任务

脚本任务

在实例详情页左侧导航栏选择任务 > 任务管理。
单击创建任务，以Shell脚本为例完成以下配置，其它参数根据实际需求填写或保持默认：
说明
若Agent部署在Unix/Linux系统上，文件格式应选择Unix。
- 关联应用选择步骤一创建的应用。
- 任务类型选择Shell。
在任务管理页面，单击已创建任务操作列运行一次，进行测试。
在左侧菜单栏选择任务实例，查看任务执行记录，单击日志可查看该脚本执行的详细情况。