XXL-JOB - 集成 Python 执行器实战指南

1. 前言

在分布式系统中，XXL-JOB 是非常主流的 Java 任务调度平台。但在实际业务中，我们经常需要运行一些 Python 任务（如数据分析、AI 模型推理等）。本文将介绍如何通过开源库 pyxxl 快速实现 Python 与 XXL-JOB 的无缝对接，并重点讲解如何处理"每小时触发且自动覆盖旧任务"的调度逻辑。

2. 环境准备

在开始之前，请确保已安装以下环境：

XXL-JOB Admin: 2.x 以上版本

https://github.com/xuxueli/xxl-jobhttps://github.com/xuxueli/xxl-job

Python: 3.10+
pyxxl: 核心集成库

bash 复制代码

pip install pyxxl

3. 快速上手：编写 Python 执行器

我们使用 pyxxl 编写一个简单的执行器。其核心原理是启动一个长驻内存的异步服务，监听指定端口并等待调度中心（Admin）的指令。

3.1 核心代码逻辑 `app.py`

python 复制代码

import asyncio
from pyxxl import ExecutorConfig, PyxxlRunner
from pyxxl.ctx import g

# 1. 配置执行器参数
config = ExecutorConfig(
    # 调度中心地址，注意末尾通常需要 /api/
    xxl_admin_baseurl="http://127.0.0.1:8080/xxl-job-admin/api/",
    # 执行器名称，必须与 XXL-JOB 调度中心里配置的 AppName 一致
    executor_app_name="python-executor",
    # 本机监听 IP（调度中心需要能访问到这个 IP）
    executor_listen_host="127.0.0.1",
    # 本机监听端口
    executor_listen_port=9999,
    # 调度中心配置的 AccessToken
    access_token="default_token",
)

# 2. 初始化运行器
app = PyxxlRunner(config)

# 3. 注册任务 (JobHandler)
@app.register(name="simple_python_job")
async def simple_job():
    """
    获取参数并在控制台/调度中心打印日志
    """
    # 从全局对象 g 中获取调度中心传来的参数
    params = g.xxl_run_data.executor_params

    # 使用 g.logger 打印日志，这些日志会实时同步给 XXL-JOB 控制台
    g.logger.info("--- 任务开始运行 ---")
    g.logger.info(f"接收到的参数内容为: {params}")

    # 模拟业务耗时操作
    await asyncio.sleep(2)

    g.logger.info("--- 任务处理完成 ---")

    # 返回字符串作为任务执行结果
    return f"任务执行成功，参数是: {params}"

if __name__ == "__main__":
    print("Python XXL-JOB 执行器已启动，等待调度...")
    app.run_executor() # 启动执行器服务

4. 部署与维护脚本

为了保证 Python 执行器作为后台服务稳定运行，我们编写一个 Shell 脚本进行启停管理。

4.1 `run_job.sh` 启动脚本

该脚本会自动清理旧的执行器进程，激活 Conda 环境并启动新服务。

python 复制代码

#!/bin/bash

# 配置区
PYTHON_SCRIPT="/opt/xxl_job/app.py"
LOG_FILE="/opt/xxl_job/executor.log"
LISTEN_PORT=9999
CONDA_ENV_NAME="your_env"

# 1. 环境初始化
eval "$(/root/miniconda3/bin/conda shell.bash hook)"
conda activate $CONDA_ENV_NAME

# 2. 停止旧实例
OLD_PID=$(lsof -t -i:$LISTEN_PORT)
if [ -n "$OLD_PID" ]; then
    kill -9 $OLD_PID
    sleep 2
fi

# 3. 启动新实例
# -u 禁用缓冲，确保日志实时写入；>> 重定向避免产生 nohup.out
nohup python -u "$PYTHON_SCRIPT" >> "$LOG_FILE" 2>&1 &

echo "XXL-JOB 执行器启动成功，PID: $!"

PS：没有安装conda环境，可直接运行py脚本

5. XXL-JOB 后台配置指南

启动 Python 服务后，需要在 XXL-JOB 管理后台进行配置。

5.1 执行器管理

AppName : 必须填写 python-executor（与代码中一致）。
注册方式: 自动注册。

5.2 任务管理（核心关键）

针对"每小时执行且确保任务最新"的场景，配置细节如下：

JobHandler : 填写代码中注册的 simple_python_job。
Cron : 0/10 * * * * ? (每10秒触发)。
阻塞处理策略 : 覆盖之前调度（这是实现自动杀掉前一次旧任务的关键）。

6. 注意事项

CancelledError : 当"覆盖之前调度"生效时，旧任务会在 await 处抛出 asyncio.exceptions.CancelledError。这是 XXL-JOB 强制终止旧逻辑的正常反馈，无需惊慌。
日志原理 : pyxxl 采用"本地磁盘持久化 + Admin 按需读取"的架构。详细日志并不存入数据库，因此不会对数据库产生写压力。
超时时间: 建议设置合理的任务超时时间（非 0），防止进程陷入死循环。