XXL-JOB：一次任务如何穿过调度中心与执行器

XXL-JOB 把分布式任务拆成两个长期运行的角色：调度中心保存任务配置、计算触发时间、选择执行器并汇总结果；执行器嵌入业务应用，真正调用 Java 方法、Groovy 或脚本。两者通过 HTTP 交接，MySQL 同时保存配置、注册信息和调度日志。业务代码因此留在自己的服务里，调度中心主要处理“何时执行、发给谁、结果怎样收回来”。

框架最有辨识度的部分，不是 Cron 表达式，而是整条异步链路的组合：数据库提前扫描未来 5 秒的任务，60 槽时间轮负责贴近秒级触发；路由器从执行器地址中选节点；每个任务进入自己的 JobThread；执行结果再通过回调写回调度中心。注册、回调、失败重试和告警也各自由后台线程推进，任何一个 HTTP 成功都只代表某一段交接完成。

这种结构的外部依赖很克制：调度中心依赖 MySQL，执行器依赖能够访问调度中心和业务资源的网络环境；邮件、Docker、Groovy、Shell 以及 AI 示例属于按需能力。代价也同样清楚：数据库既是状态中心又承担集群调度锁，多个线程池和任务队列的背压规则并不统一，共享令牌校验也不能代替传输加密与网络隔离。

下面以 3.5.0-SNAPSHOT 的固定源码快照为阅读对象，从目录地图进入两个进程的启动，再沿“扫描—触发—执行—回调”走完一次任务。路由、分片、阻塞、超时、重试、子任务和结果丢失恢复会作为同一条主线的分支展开，而不是孤立罗列功能。

GitHub 仓库信息

信息	内容
项目标题	XXL-JOB
项目描述	一个分布式任务调度框架，由调度中心统一管理任务，并由嵌入业务应用的执行器实际运行任务。
GitHub 仓库	xuxueli/xxl-job
官网地址	XXL-JOB 官方网站
主要开发语言	Java 99.85%、Dockerfile 0.15%
开源许可证	GPL-3.0
最近代码更新	2026-07-21（GitHub `pushed_at`，核对日期：2026-09-02）

仓库结构与模块职责

XXL-JOB 是一个 Maven 聚合工程，核心代码集中在三个模块。目录不多，但调度中心内部又分成 Web 管理、调度内核、持久化和后台线程几层；阅读时按运行角色分组，比顺着包名逐个翻更容易建立方向感。

text

xxl-job/
├── xxl-job-admin/                  # 调度中心：管理端、调度、路由、回调、告警
│   ├── business/controller/        # 任务、执行器、日志等管理入口
│   ├── business/scheduler/         # 调度运行时核心
│   │   ├── config/                 # 启停编排与远程执行器客户端
│   │   ├── thread/                 # 扫描、时间轮、注册、回调、告警线程
│   │   ├── trigger/                # 触发参数、路由交接和日志记录
│   │   ├── route/                  # 节点选择策略
│   │   ├── type/                   # CRON、固定频率等调度类型
│   │   └── complete/               # 执行完成和子任务衔接
│   ├── business/mapper/            # MyBatis Mapper 接口
│   └── src/main/resources/mapper/  # SQL、调度锁和日志查询
├── xxl-job-core/                   # 执行器 SDK 与内嵌 Netty HTTP 服务
│   ├── executor/                   # 普通执行器与 Spring 执行器生命周期
│   ├── openapi/                    # 调度中心、执行器双方的 HTTP 契约
│   ├── server/                     # /trigger、/beat、/kill、/log 等入口
│   ├── thread/                     # JobThread、注册、回调和日志清理
│   ├── handler/                    # IJobHandler、方法和脚本适配器
│   └── context/                    # 参数、分片、日志和执行结果上下文
├── xxl-job-executor-samples/
│   ├── xxl-job-executor-sample-springboot/     # Spring Boot 接入示例
│   ├── xxl-job-executor-sample-frameless/      # 无 Spring 示例
│   └── xxl-job-executor-sample-springboot-ai/  # Ollama、Dify 等 AI 示例
├── doc/db/tables_xxl_job.sql        # MySQL 表结构与初始化数据
├── docker/docker-compose.yml        # MySQL、Admin、示例执行器编排
└── pom.xml                          # Java 17 与依赖版本管理

模块或核心文件	负责什么	与上下游的关系
`xxl-job-admin`	任务管理、时间计算、集群扫描、路由、日志、回调、重试、告警	从 MySQL 读取状态，通过 HTTP 调用执行器，再接收执行器回调
`xxl-job-core`	执行器 SDK、任务处理器注册、Netty HTTP 服务、任务线程和本地日志	被业务应用依赖，对调度中心提供执行端点
`xxl-job-executor-samples`	展示 Spring、无框架和 AI 任务的接入方式	给出配置、`@XxlJob` 方法及 Docker 启动样例
`XxlJobAdminBootstrap`	按依赖顺序启动和停止调度中心后台组件	是 Spring 容器与调度内核之间的生命周期桥梁
`JobScheduleHelper`	数据库预读、误触发处理、时间轮投递和下次时间刷新	上游是任务表，下游是触发线程池
`JobTrigger`	创建调度日志、选择地址、构造请求并调用执行器	将“到点”转换成一次有日志编号的远程触发
`XxlJobSpringExecutor`	扫描 Spring Bean 中的 `@XxlJob` 方法	把业务方法注册成执行器可寻址的 Handler
`ExecutorBizImpl` 与 `JobThread`	处理触发、应用阻塞策略、排队、超时执行和生成回调	接收 `/trigger`，把最终结果交给回调队列
`tables_xxl_job.sql`	定义执行器组、注册表、任务、日志、统计、锁和用户表	MySQL 是调度中心的持久状态和集群协调点

核心能力与实现机制

时间驱动：数据库预读配合秒级时间轮

任务支持 NONE、CRON 和 FIX_RATE。Cron 使用仓库内的表达式解析器计算下一次时间，固定频率则在上一次计划时间上增加秒数并对齐到下一秒。源码中 FIX_DELAY 仍处于注释状态，完成器也保留了“on the way”标记，因此当前快照不能把“上次执行完成后再延迟”当成已实现能力。

调度中心不会每秒把所有任务都扫一遍。扫描线程先查询未来 5 秒会到期的任务，较远但即将发生的触发被放入 60 个秒槽；时间轮线程再按当前秒以及向前两个刻度取出任务。这是第一处关键转折：MySQL 决定“哪些任务即将发生”，内存时间轮负责“尽量贴近哪一秒发出”，二者承担不同粒度的工作。

执行器发现：心跳表代替独立注册中心

执行器每 30 秒向调度中心注册一次 appname + address。调度中心将心跳保存到 xxl_job_registry，超过 90 秒未更新的记录会被清除，然后按 appname 汇总地址并写回执行器组。这里没有 ZooKeeper 或 Nacos：注册发现就是数据库表、周期线程和一份本地缓存。

这种实现降低了组件数量，但执行器可见性、任务配置和调度锁都落在同一数据库上。MySQL 故障不只影响后台页面，也会影响新任务发现和调度推进。

路由与分片：先选节点，再发送任务

普通任务可以采用首个、末尾、轮询、随机、一致性哈希、LFU、LRU、故障转移或忙碌转移。故障转移逐个调用 /beat，选择第一个可达节点；忙碌转移调用 /idleBeat，选择当前任务没有运行且队列为空的节点。分片广播不调用普通路由器，而是对地址列表逐一触发，并传入 index/total。

路由发生在调度中心，阻塞发生在执行器。路由解决“这一次交给哪台机器”，阻塞策略解决“同一个任务已经在这台机器运行时怎么办”，两者不能互相替代。

执行隔离：一个任务对应一个 JobThread

执行器以 jobId 为键维护 JobThread。线程拥有自己的触发队列，并在 Handler 生命周期内只调用一次 init() 和 destroy()。三种阻塞策略改变队列处理方式：串行执行继续排队，丢弃后续会在已有运行或排队任务时拒绝，新任务覆盖旧任务则停止旧线程并创建新线程。

设置超时时间后，真正的 Handler 会放入 FutureTask 的独立线程；等待超过限制时，执行器写入超时结果并中断执行线程。Java 中断依赖业务代码配合，不能等同于操作系统层面的强制终止。

结果闭环：回调、补偿、子任务和告警

任务完成后，执行器把结果放进批量回调队列，每批最多 50 条。调度中心不可达时，回调内容按 MD5 命名写入本地文件，后台线程下次继续尝试。调度中心收到结果后更新日志；成功任务再触发子任务，失败任务进入重试和告警扫描。

第二处关键转折在这里：/trigger 返回成功，只说明执行器接受了触发请求。任务是否真正执行、是否超时、结果能否回传、调度中心是否完成落库，是后面几个独立阶段。排障时若只看“触发成功”，很容易忽略执行和回调故障。

管理入口：页面操作与 OpenAPI 汇入同一服务层

管理页面通过 JobInfoController 创建、启停和手动触发任务；/api/{uri} 还提供新增、更新、删除、启停、触发、注册和回调接口。OpenAPI 要求 POST，并校验执行器组对应的 appname 与 accessToken。任务管理实现以参数 100 和 30 秒创建令牌桶进行限流，最后进入与页面相同的 XxlJobService。

源码环境准备与本地运行

当前固定提交的根 pom.xml 声明 3.5.0-SNAPSHOT、Java 17、Spring Boot 4.1.0、Spring 7.0.8、MyBatis Spring Boot Starter 4.0.1、MySQL Connector/J 9.7.0 和 Netty 4.2.15.Final。最新公开 Release 是 2026 年 6 月 19 日发布的 3.4.2。阅读或复现时应明确自己使用的是 Release 还是快照，不能默认两者实现完全相同。

本次只完成固定提交的静态阅读，没有运行 Maven、测试、MySQL、Docker、调度中心或执行器。下面命令依据构建文件、SQL 和示例配置整理，成功信号来自源码中的日志文本，不是本次亲测结果。

1. 获取同一份源码

前置条件是 Git、JDK 17、Maven 和 MySQL 8.x。工作目录可自行选择；下面将仓库放到当前目录。

bash

git clone https://github.com/xuxueli/xxl-job.git
cd xxl-job
git checkout e74c784f68f81fa89cb350913ef15794865d7b12
git status --short --branch

最后一条应显示 detached HEAD 或固定提交附近的状态，并且没有意外改动。

2. 初始化数据库和调度中心配置

将 doc/db/tables_xxl_job.sql 导入 MySQL。脚本会创建 xxl_job 数据库、核心表、默认执行器组、示例任务、管理员和 schedule_lock 记录。

随后修改：

properties

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=<your-password>

样例文件中的 root_pwd、邮件账号和 default_token 都不应直接用于正式环境。若暂不使用邮件告警，也应确认邮件健康检查和告警行为符合预期。

3. 构建并启动调度中心

根 POM 默认设置 maven.test.skip=true。下面的打包命令会连同依赖模块一起构建，但不会证明测试通过。

bash

mvn -pl xxl-job-admin -am clean package
java -jar xxl-job-admin/target/xxl-job-admin-3.5.0-SNAPSHOT.jar

默认管理端口是 8080。源码中的关键成功信号是：

text

xxl-job admin start success.
init xxl-job admin scheduler success.

若希望真正执行测试，需要显式覆盖根 POM 的跳过设置，并观察 Maven 测试汇总，而不是只看到打包成功：

bash

mvn -Dmaven.test.skip=false test

4. 配置并启动示例执行器

执行器配置中的三项必须与调度中心的执行器组一致：

properties

xxl.job.admin.addresses=http://127.0.0.1:8080
xxl.job.executor.appname=xxl-job-executor-sample
xxl.job.executor.accessToken=<same-token-as-admin-group>
xxl.job.executor.port=9999

然后启动示例：

bash

mvn -pl xxl-job-executor-samples/xxl-job-executor-sample-springboot -am package
java -jar xxl-job-executor-samples/xxl-job-executor-sample-springboot/target/xxl-job-executor-sample-springboot-3.5.0-SNAPSHOT.jar

执行器先绑定 Netty 端口，随后才启动注册线程。可观察信号应包括远程服务启动、注册成功，以及管理端执行器组出现该地址。只看到业务应用的 Spring Boot 端口 8081，不能说明执行器端口 9999 已经可达。

5. 完成一次有价值的验证

在管理端确认 demoJobHandler 对应的示例任务，手动触发后至少检查四段结果：调度日志有地址和 triggerCode，执行器本地日志出现 XXL-JOB, Hello World.，日志最终获得 handleCode，调度中心不再停留在“运行中”。这四项分别覆盖路由、业务执行、回调和落库。

整体架构地图与功能分布

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    User[管理员 / OpenAPI] --> Web[Admin Web 与任务服务]
    Web --> DB[(MySQL)]

    subgraph Admin[xxl-job-admin 调度中心]
        Scheduler[预读扫描 + 60 槽时间轮]
        TriggerPool[快 / 慢触发线程池]
        Router[路由与分片]
        Complete[回调完成器]
        Alarm[失败重试与告警]
        Registry[注册监控与地址缓存]
        Scheduler --> TriggerPool --> Router
        Complete --> Alarm
        Registry --> Router
    end

    DB <--> Scheduler
    DB <--> Registry
    DB <--> Complete
    DB <--> Alarm

    Router -->|POST /trigger| Executor
    Executor -->|POST /api/registry| Registry
    Executor -->|POST /api/callback| Complete

    subgraph Executor[业务应用中的 xxl-job-core]
        Embed[Netty EmbedServer]
        Dispatch[ExecutorBizImpl]
        Queue[JobThread + 触发队列]
        Handler[@XxlJob / Groovy / Script]
        Callback[批量回调 + 本地失败文件]
        Embed --> Dispatch --> Queue --> Handler --> Callback
    end

    Handler --> Biz[(业务数据库 / HTTP API / 文件等)]
    Alarm --> Mail[邮件或自定义告警器]

想找的能力	源码入口	继续向下读
调度中心整体启停	`XxlJobAdminApplication`	`XxlJobAdminBootstrap`
到期扫描与时间轮	`JobScheduleHelper`	`XxlJobInfoMapper.xml`、`XxlJobLockMapper.xml`
Cron 与固定频率	`ScheduleTypeEnum`	`CronScheduleType`、`FixRateScheduleType`
路由和分片	`JobTrigger`	`ExecutorRouteStrategyEnum` 与各 Router
执行器 HTTP 服务	`EmbedServer`	`ExecutorBizImpl`
Spring 方法发现	`XxlJobSpringExecutor`	`MethodJobHandler`、`@XxlJob`
串行、丢弃、覆盖	`ExecutorBizImpl.trigger`	`JobThread`
心跳注册	`ExecutorRegistryThreadHelper`	`JobRegistryHelper`、`XxlJobRegistryMapper.xml`
回调补偿	`TriggerCallbackThreadHelper`	`JobCompleteHelper`、`JobCompleter`
失败重试和告警	`JobFailAlarmMonitorHelper`	`XxlJobLogMapper.xml`、`JobAlarmer`
数据表关系	`tables_xxl_job.sql`	group、registry、info、log、lock 表

两个进程怎样启动

角色入口

运行角色	进程入口	关键生命周期钩子	启动后的后台工作
调度中心	`XxlJobAdminApplication.main`	`XxlJobAdminBootstrap.afterPropertiesSet`	触发池、注册监控、失败告警、回调完成、日志报表、调度扫描
Spring 执行器	业务应用的 `main`	`XxlJobSpringExecutor.afterSingletonsInstantiated`	Handler 扫描、日志清理、回调队列、Netty 服务、注册心跳
无框架执行器	业务自行创建 `XxlJobExecutor`	显式 `start` / `destroy`	与 Spring 执行器共享核心运行时，但不依赖 Bean 扫描

调度中心启动链

Mermaid 流程图

正在准备渲染...

查看源码

sequenceDiagram
    participant Main as XxlJobAdminApplication
    participant Spring as SpringApplication
    participant Boot as XxlJobAdminBootstrap
    participant Pool as JobTriggerPoolHelper
    participant Registry as JobRegistryHelper
    participant Complete as JobCompleteHelper
    participant Schedule as JobScheduleHelper

    Main->>Spring: run()
    Spring->>Boot: afterPropertiesSet()
    Boot->>Pool: start()
    Boot->>Registry: start()
    Boot->>Boot: start failure alarm monitor
    Boot->>Complete: start()
    Boot->>Boot: start log report helper
    Boot->>Schedule: start()

这个顺序不是随意排列：回调完成和调度扫描都可能再次向触发池提交任务，所以触发池先启动、最后停止。停机时 XxlJobAdminBootstrap 按大致逆序关闭；时间轮若仍有任务，最多额外等待 10 秒，再中断时间轮线程。

Spring 执行器启动链

Mermaid 流程图

正在准备渲染...

查看源码

flowchart TD
    A[Spring 单例实例化完成] --> B[扫描非懒加载 Bean 的 @XxlJob 方法]
    B --> C[注册 MethodJobHandler]
    C --> D[XxlJobExecutor.start]
    D --> E{enabled?}
    E -- 否 --> Z[不启动执行器]
    E -- 是 --> F[校验 adminAddresses / appname / accessToken]
    F --> G[初始化日志目录和 AdminBiz HTTP 客户端]
    G --> H[启动日志清理与回调队列]
    H --> I[从 9999 起确定端口并启动 Netty]
    I --> J[端口绑定成功]
    J --> K[启动 30 秒注册心跳]

扫描器会跳过配置的包前缀和懒加载 Bean，避免为了找注解而过早实例化整个容器。方法名由 @XxlJob("handlerName") 映射到 Handler 仓库；重复名称、空名称或不存在的生命周期方法都会在启动期暴露。

核心链路矩阵

链路	入口	跨模块交接	外部依赖	最终状态
自动调度	`JobScheduleHelper`	MySQL → 时间轮 → 触发池	MySQL、系统时间	生成一条调度日志并发出触发
手动或 API 触发	页面 `/jobinfo/trigger` 或 `/api/triggerJob`	Controller → Service → 触发池	登录态或共享令牌	与自动调度汇入同一触发链
节点选择与远程触发	`JobTrigger`	Router → `ExecutorBiz` → `/trigger`	执行器网络地址	记录触发结果和选中地址
业务执行	`ExecutorBizImpl.trigger`	Handler 选择 → 阻塞策略 → `JobThread`	业务数据库、HTTP、文件等	产生执行结果和本地日志
注册发现	`ExecutorRegistryThreadHelper`	`/api/registry` → 注册表 → group 地址	MySQL、Admin 网络	调度中心缓存可用执行器
回调闭环	`TriggerCallbackThreadHelper`	`/api/callback` → 完成器	Admin 网络、MySQL、本地磁盘	更新 `handleCode`，可能触发子任务
失败恢复	`JobFailAlarmMonitorHelper`	失败日志 → 重试触发池 → 告警器	MySQL、邮件或扩展告警	消耗重试次数并更新告警状态

一次任务的完整主链

Mermaid 流程图

正在准备渲染...

查看源码

sequenceDiagram
    participant DB as MySQL
    participant S as JobScheduleHelper
    participant P as JobTriggerPoolHelper
    participant T as JobTrigger
    participant E as Executor EmbedServer
    participant J as JobThread
    participant C as TriggerCallbackThreadHelper
    participant A as JobCompleteHelper

    S->>DB: FOR UPDATE 获取 schedule_lock
    S->>DB: 查询未来 5 秒内的运行任务
    S->>S: 立即触发、处理 misfire 或放入时间轮
    S->>DB: 批量刷新 last/next/status
    S->>P: 提交 jobId
    P->>T: trigger(jobId, type, ...)
    T->>DB: 创建 xxl_job_log，获得 logId
    T->>T: 路由或分片选择地址
    T->>E: POST /trigger
    E->>J: 校验阻塞策略并入队
    E-->>T: 已接受或拒绝
    J->>J: 执行 Handler / 超时控制
    J->>C: 放入 CallbackData
    C->>A: POST /api/callback，批量最多 50
    A->>DB: 更新 handleCode / handleMsg
    A->>P: 成功时可触发子任务

扫描、误触发与时间轮

扫描线程启动时先对齐秒边界，然后在事务内执行 SELECT ... FOR UPDATE 锁住唯一的 schedule_lock 行。多实例调度中心因此会串行进入扫描区，避免同一批任务被同时读取和刷新。

查询只取 trigger_status = 1 且 trigger_next_time <= now + 5s 的任务，数量上限按快、慢触发池最大线程数乘以 10 计算。每个任务有三个分支：

计划时间已过期超过 5 秒：执行 DO_NOTHING 或 FIRE_ONCE_NOW，再计算下一次时间；
已到期但未超过 5 秒：立即提交触发，并计算下一次时间；若下一次仍在预读窗口内，再放入时间轮；
尚未到期：按秒数放入 60 槽时间轮，并把计划时间推进到下一次。

时间轮每秒同时取当前槽和向前两个槽，弥补处理耗时跨过刻度的情况，并在同一槽内按任务 ID 去重。扫描成功且足够快时约每秒继续一次；没有预读到任务时跳过当前 5 秒窗口，避免空轮询。

调度信息按 xxl.job.schedule.batchsize 分批写回，允许范围是 50 到 500，越界回落到 100。这里仍要看到数据库方案的代价：全局行锁把重复调度问题变简单，也把扫描吞吐和数据库可用性绑在了一起。

快慢触发池和队列拒绝

正常触发进入 fast pool。若同一任务在一分钟内超过 10 次触发耗时大于 500ms，后续触发转入 slow pool，让慢节点探测或网络调用少占用快速通道。fast 队列容量 2000，slow 队列容量 5000。

两个池的拒绝处理器只写错误日志，没有回退到调用线程、持久化补偿或自动重试。这意味着线程与队列同时耗尽时，本次“提交触发”可能丢失；调度日志甚至可能尚未创建，因为 JobTrigger 还没有运行。容量规划和拒绝日志监控不能省略。

路由、分片和远程触发

JobTrigger 读取任务与执行器组，先创建 xxl_job_log 获得唯一 logId，再构造包含 Handler、参数、超时、GLUE、分片和日志时间的请求。普通路由选择一个地址；分片广播为每个地址单独创建日志并发送一份请求。

调度中心通过动态 HTTP 客户端调用执行器 /trigger。客户端缓存键包含地址、令牌和 appname，缓存超过 1000 项时整体清空。执行器端只接受 POST，请求体最多由 Netty 聚合到 5MB，并要求令牌与应用名同时匹配。

选中地址和 /trigger 返回码会写入调度日志。触发失败、没有可用地址和路由探测异常停留在这一阶段；这些错误还没有进入业务 Handler。

Handler 选择、阻塞和超时

执行器根据 glueType 选择三条路径：BEAN 从 Handler 仓库按名称查找，Groovy 动态加载源码，脚本类型创建 ScriptJobHandler。配置 xxl.job.executor.glueenabled=false 可以整体关闭非 BEAN 任务，适合不希望执行中心下发动态代码的环境。

同一任务已有 JobThread 时，阻塞策略决定行为：

策略	条件	行为
`SERIAL_EXECUTION`	无论是否正在运行	新触发进入同一队列
`DISCARD_LATER`	正在运行或已有排队	立即返回失败，不进入队列
`COVER_EARLY`	正在运行或已有排队	停止旧线程，创建新线程接收本次触发

JobThread 在入队阶段用 logId 去重，避免同一条调度日志重复入队；开始消费后便移除去重标记。任务队列使用没有显式容量的 LinkedBlockingQueue，而外围触发池和 Netty 业务池都有容量。这种背压不一致意味着“串行执行 + 高频触发 + 长任务”可能在单个任务队列积压，而不是尽早向调度中心反馈拥塞。

空闲轮询超过 30 次、队列仍为空时，线程从仓库移除。执行器收到 kill、Handler 变化或覆盖策略时，正在运行的任务和尚未执行的队列项都会生成失败回调，但 Java 线程是否立即停止仍取决于业务代码如何响应中断。

注册发现的最终一致性

执行器的注册请求到达调度中心后，不会同步写完所有状态再响应。JobRegistryHelper.registry 把 save-or-update 放进线程池，然后先返回成功；后台监控线程再清理死亡地址、聚合在线地址、更新 xxl_job_group.address_list 并刷新本地缓存。

因此“注册接口成功”与“路由马上能看到地址”之间存在一个短暂窗口。注册线程池满时会退化为调用线程直接执行，避免静默丢注册；这与触发线程池只写错误日志的拒绝策略形成鲜明对比。

回调、结果丢失恢复和子任务

任务结果优先通过回调队列发送到多个调度中心地址中的第一个成功节点。全部失败时，数据写到执行器日志目录下的 callback 文件；重试线程每 30 秒读取、删除原文件并重新回调，若再次失败会按内容 MD5 重新落盘。

调度中心对已有 handleCode > 0 的日志拒绝重复回调，防止子任务被再次触发。完成器只在父任务成功时提交子任务；失败任务由 10 秒一次的监控线程抢占 alarm_status，有剩余次数则按原分片参数重试，随后执行告警。

还有一条兜底链：触发成功、日志停留运行中超过 10 分钟，而且对应执行器已不在注册表时，调度中心把日志标记为失败。这只能处理“执行器已离线且回调丢失”的情况；执行器仍在线但业务长期卡死，应依赖任务超时、业务监控或人工终止。

分支、失败与安全边界

阶段	常见失败	日志或状态入口	自动恢复
扫描	MySQL 不可用、锁等待、下次时间计算失败	Admin 调度线程日志、任务 `trigger_status`	下次扫描可继续；时间计算失败会停任务
路由	地址为空、探活失败、线程池拒绝	`trigger_code`、`trigger_msg`、触发池错误日志	失败日志可进入重试；池拒绝本身没有持久补偿
执行	Handler 不存在、阻塞拒绝、脚本失败、超时	执行器本地日志、`handleCode`	可配置失败重试；超时依赖线程中断
回调	Admin 不可达、重复回调、回调文件不可写	callback 文件、Admin 回调日志	本地文件周期重试；磁盘不可写时会丢补偿
注册	地址不可达、容器注册内网地址、心跳过期	`xxl_job_registry`、执行器注册日志	30 秒重试，90 秒过期清理
告警	邮件配置错误、扩展告警失败	`alarm_status`、告警日志	下一轮只处理默认状态；失败状态需运维关注

执行器和调度中心之间的校验是请求头中的共享 accessToken + appname，固定源码中直接比较字符串；没有看到请求签名、令牌轮换协议、重放保护或内建双向 TLS。地址可以配置为 HTTPS，但证书、反向代理和网络策略属于部署侧责任。管理端还包含 SSO 和执行器组权限，不能把后台登录权限与执行器 HTTP 鉴权混为一层。

动态 Groovy、Shell、Python、Node.js、PowerShell 等 GLUE 任务能够执行下发内容，运行权限等同于执行器进程权限。生产环境若不需要这类能力，应关闭 GLUE、限制执行器系统账号权限、隔离网络与文件系统，并避免把执行器端口直接暴露到不可信网络。

值得学习的设计与不足

值得学习

控制面与执行面分离。 调度中心不加载业务类，执行器不负责全局时间计算，业务发布和调度治理可以分开演进。
粗粒度扫描与细粒度触发分工。 5 秒预读减少数据库高频精确等待，时间轮把即将发生的任务收敛到秒槽，机制简单且容易沿日志追踪。
每段交接都留下状态。 triggerCode 和 handleCode 把“发送是否成功”与“执行是否成功”分开，回调失败还能落本地文件。
策略落在清晰边界。 路由器、调度类型、误触发处理、阻塞策略、Handler 和告警器都能从单一入口定位，阅读和定向扩展成本较低。

需要带着条件看

MySQL 是简化器，也是集中风险。 一张行锁表解决调度中心抢占，但高任务量、慢 SQL、连接池耗尽和主库故障都会直接影响调度时效。
背压语义不一致。 Netty 业务池、快慢触发池有界，单任务 JobThread 队列无界；不同过载点会分别表现为异常、静默拒绝或内存积压。
事务异常处理偏乐观。 扫描逻辑在 finally 中提交非空事务，即使处理过程中已经抛出异常也没有显式回滚；提交失败也只记录日志。旧版文章提到的空事务提交空指针在当前快照已有非空保护，但更完整的事务恢复仍值得关注。
回调补偿依赖本机磁盘。 容器使用临时文件系统、日志目录只读或多副本频繁漂移时，失败回调文件可能无法持续保存。
固定延迟尚未闭环。 枚举与完成器中能看到设计痕迹，但当前代码只实现 Cron 和固定频率；阅读注释不能当作产品能力。
安全模型依赖部署边界。 共享令牌适合可信内网中的基础校验，对跨公网、多租户或强审计场景，需要额外网关、TLS、密钥管理和细粒度授权。

扩展与排障入口

目标	建议起点	修改时必须一起检查
增加路由策略	`ExecutorRouteStrategyEnum`、`ExecutorRouter`	地址为空、探活超时、分片广播的独立路径
增加调度类型	`ScheduleType`、`ScheduleTypeEnum`	新增/更新校验、下次时间预览、misfire、停止条件
增加告警渠道	`JobAlarm`、`JobAlarmer`	告警状态抢占、失败重试顺序和敏感信息
定制 Spring 扫描	`XxlJobSpringExecutor`	懒加载 Bean、代理类、重复 Handler 名和排除包
排查“触发成功但没结果”	`xxl_job_log` 与执行器 callback 目录	`/trigger`、JobThread、本地日志、`/api/callback` 四段分别核对
排查执行器消失	`ExecutorRegistryThreadHelper`、`JobRegistryHelper`	注册地址、容器网络、30/90 秒窗口和 appname/token
限制动态任务	`glueenabled` 与 `ExecutorBizImpl`	历史 GLUE 任务、脚本解释器、进程权限和文件目录

应用场景与同类产品对比

XXL-JOB 适合已经以 Java 服务承载业务逻辑、希望集中管理 Cron 任务、人工补跑、路由、分片和日志的团队。XXL-JOB 尤其适合“调度平台只发命令，业务服务自己执行”的组织边界。若任务需要大规模数据并行计算、复杂 DAG 编排、强一致工作流语义，或者执行端分布在不可信公网，单靠现有调度与鉴权模型会显得吃力。

方案	主要定位	运行形态	状态与协调	更适合的取舍
XXL-JOB	集中式分布式任务调度	Admin + 嵌入业务的 Executor	MySQL 配置、日志、注册与调度锁	组件少、后台治理直观；需接受中心数据库和 HTTP 执行器边界
Quartz	JVM 内嵌调度库	与应用同进程，可用 JDBC JobStore 集群	内存或数据库 JobStore	需要库级时间调度、愿意自行建设管理与远程执行层
Apache ElasticJob	分布式作业调度与分片	作业进程嵌入应用，配合协调服务	注册中心协调分片与选主	更强调分片、弹性和分布式协调，组件与运维概念更多
PowerJob	分布式任务调度与计算	Server + Worker	数据库及其服务端调度模型	需要工作流、广播、MapReduce 等更宽任务模型，愿意承担更大的平台面

比较时不要用功能数量直接下结论。若目标只是单 JVM 内可靠触发，Quartz 更贴近问题；若核心是数据库分片任务，ElasticJob 的分片模型值得优先评估；若需要任务编排和分布式计算，PowerJob 的模型更宽。XXL-JOB 的优势来自角色清楚和落地成本，而不是覆盖所有调度问题。

构建、部署与调试问题

执行器已经启动，调度中心却没有地址

先核对 appname、accessToken、Admin URL 和执行器注册地址。容器内自动探测到的 IP 未必能被调度中心访问，可显式配置 xxl.job.executor.address。成功标准不是注册请求返回 200，而是执行器组缓存出现可由 Admin 访问的地址，并能通过 /beat。

日志显示触发成功，页面一直处于运行中

按阶段检查：trigger_code 是否成功、执行器本地日志是否创建、Handler 是否返回结果、callback 目录是否积压文件、Admin /api/callback 是否可达。只重跑任务会制造更多日志，不会修复回调网络或磁盘问题。

串行任务越积越多

SERIAL_EXECUTION 对应无界任务队列。降低触发频率、缩短任务时间，或根据业务幂等性改用 DISCARD_LATER / COVER_EARLY；同时监控 JVM 内存和单任务排队。路由到更多节点只有在路由策略确实把触发分散出去时才有效。

Docker 中 Admin 能启动，但执行器连接失败

Compose 网络内应使用服务名和容器端口，例如示例中的 http://xxl-job-admin:${XXL_JOB_ADMIN_PORT}/，不能把执行器容器里的 127.0.0.1 当成 Admin。反方向还要保证执行器注册的 9999 地址对 Admin 可达。

调度线程报数据库异常后行为异常

当前源码已经保护 transactionStatus == null 的提交分支，不应照搬针对更老版本的空指针补丁。仍需检查数据库连接、锁等待、事务超时和部分处理后提交的风险；修复前先对照自己的 tag 或 commit，因为相关逻辑曾发生变化。

callback 文件持续增长

这通常表示调度中心不可达、令牌/应用名不匹配，或回调响应持续失败。修复网络与鉴权后观察文件是否被消费；容器部署还要确认日志目录可写且有持久卷。不要直接删除未核对的文件，否则执行结果可能永久缺失。

总结与后续阅读路径

理解 XXL-JOB 的最短主线是：MySQL 保存未来触发时间，调度中心用行锁和 5 秒预读取得任务，时间轮贴近秒级提交，路由器选择执行器，JobThread 排队执行，回调再把最终结果写回日志。注册、重试、告警和子任务都围绕这条链补充状态，而不是另起一套执行模型。

继续阅读可以按问题进入：想改时间语义，从 ScheduleType 和 JobScheduleHelper 开始；想理解节点选择，从 JobTrigger 和 Router 开始；想排查任务卡住，沿 ExecutorBizImpl → JobThread → TriggerCallbackThreadHelper 走；想审视集群一致性和容量边界，则同时查看调度锁 SQL、触发池拒绝策略、注册表和回调文件。

参考资料

xuxueli/xxl-job GitHub 仓库
XXL-JOB 官方文档
XXL-JOB 3.4.2 Release
固定源码提交 e74c784
XXL-JOB 源码解析调度任务的定时触发流程 — 适合对照旧版扫描与时间轮主线，类名和事务处理需以当前提交为准。
xxl-job 源码阅读——服务端 — 从调度中心入口串起线程组件，使用的是较早版本包结构。
XXL-JOB 源码分析——调度中心启动 — 聚焦启动线程与职责拆分，可作为生命周期阅读顺序的补充。
XXL-JOB 任务调度流程梳理 — 覆盖 Bean Handler、执行和回调流程，部分类型名与当前 OpenAPI DTO 已变化。
xxl-job 源码之调度抖动与空指针 — 展示数据库异常下的旧实现风险；当前固定提交已有空事务保护，但仍应检查事务恢复边界。

XXL-JOB：一次任务如何穿过调度中心与执行器 ​

GitHub 仓库信息 ​

仓库结构与模块职责 ​

核心能力与实现机制 ​

时间驱动：数据库预读配合秒级时间轮 ​

执行器发现：心跳表代替独立注册中心 ​

路由与分片：先选节点，再发送任务 ​

执行隔离：一个任务对应一个 JobThread ​

结果闭环：回调、补偿、子任务和告警 ​

管理入口：页面操作与 OpenAPI 汇入同一服务层 ​

源码环境准备与本地运行 ​

1. 获取同一份源码 ​

2. 初始化数据库和调度中心配置 ​

3. 构建并启动调度中心 ​

4. 配置并启动示例执行器 ​

5. 完成一次有价值的验证 ​

整体架构地图与功能分布 ​

两个进程怎样启动 ​

角色入口 ​

调度中心启动链 ​

Spring 执行器启动链 ​

核心链路矩阵 ​

一次任务的完整主链 ​

扫描、误触发与时间轮 ​

快慢触发池和队列拒绝 ​

路由、分片和远程触发 ​

Handler 选择、阻塞和超时 ​

注册发现的最终一致性 ​

回调、结果丢失恢复和子任务 ​

分支、失败与安全边界 ​

值得学习的设计与不足 ​

值得学习 ​

需要带着条件看 ​

扩展与排障入口 ​

应用场景与同类产品对比 ​

构建、部署与调试问题 ​

执行器已经启动，调度中心却没有地址 ​

日志显示触发成功，页面一直处于运行中 ​

串行任务越积越多 ​

Docker 中 Admin 能启动，但执行器连接失败 ​

调度线程报数据库异常后行为异常 ​

callback 文件持续增长 ​

总结与后续阅读路径 ​

参考资料 ​

XXL-JOB：一次任务如何穿过调度中心与执行器

GitHub 仓库信息

仓库结构与模块职责

核心能力与实现机制

时间驱动：数据库预读配合秒级时间轮

执行器发现：心跳表代替独立注册中心

路由与分片：先选节点，再发送任务

执行隔离：一个任务对应一个 JobThread

结果闭环：回调、补偿、子任务和告警

管理入口：页面操作与 OpenAPI 汇入同一服务层

源码环境准备与本地运行

1. 获取同一份源码

2. 初始化数据库和调度中心配置

3. 构建并启动调度中心

4. 配置并启动示例执行器

5. 完成一次有价值的验证

整体架构地图与功能分布

两个进程怎样启动

角色入口

调度中心启动链

Spring 执行器启动链

核心链路矩阵

一次任务的完整主链

扫描、误触发与时间轮

快慢触发池和队列拒绝

路由、分片和远程触发

Handler 选择、阻塞和超时

注册发现的最终一致性

回调、结果丢失恢复和子任务

分支、失败与安全边界

值得学习的设计与不足

值得学习

需要带着条件看

扩展与排障入口

应用场景与同类产品对比

构建、部署与调试问题

执行器已经启动，调度中心却没有地址

日志显示触发成功，页面一直处于运行中

串行任务越积越多

Docker 中 Admin 能启动，但执行器连接失败

调度线程报数据库异常后行为异常

callback 文件持续增长

总结与后续阅读路径

参考资料