XXL-JOB Admin 启动失败主因是 MySQL 配置不合规：需 MySQL ≥5.7、建库用 utf8mb4、JDBC URL 含必要参数；执行器注册失败多因地址配置不一致；任务无日志常因依赖冲突或日志配置错误；分片参数失效源于跨线程或异步调用导致 ThreadLocal 上下文丢失。
XXL-JOB Admin 启动失败，报 DataSource 初始化异常
常见现象是启动时抛 org.springframework.beans.factory.UnsatisfiedDependencyException，或日志里反复出现 Failed to obtain JDBC Connection。根本原因不是 XXL-JOB 本身有问题，而是它默认依赖外部 MySQL，并且对表结构、字符集、JDBC 驱动版本有明确要求。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 确认 MySQL 版本 ≥ 5.7（8.0+ 需额外配置
serverTimezone=Asia/Shanghai在 JDBC URL 里） - 建库语句必须用
utf8mb4字符集：CREATE DATABASE xxl_job_admin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - 执行官方 SQL 脚本前，先检查
xxl_job_lock表是否存在——如果已有旧版残留表，xxl_job_log的索引可能不兼容，直接导致初始化失败 -
application.properties中的spring.datasource.url必须显式带上useUnicode=true&characterEncoding=UTF-8&autoReconnect=true，少一个参数都可能在高并发下断连
执行器注册不上，Admin 页面显示 OFFLINE
不是网络不通，也不是端口没开，大概率是执行器主动上报地址和 Admin 实际访问它的地址不一致。XXL-JOB 不靠心跳探测，而是靠执行器“自报家门”——它启动时会调用 adminAddresses 列表里的地址，把自己的 ip:port 注册进去；Admin 后续回调任务，用的正是这个注册值。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 检查执行器配置项
xxl.job.admin.addresses是否写错，比如漏了http://或多写了斜杠 - 容器或云环境务必设
xxl.job.executor.ip和xxl.job.executor.port，不能依赖自动获取——Docker 网络里InetAddress.getLocalHost()返回的是内网网桥地址，Admin 根本调不通 - 如果执行器加了反向代理（如 Nginx），要确保
xxl.job.executor.address填的是代理后暴露的公网/集群内可访问地址，而不是服务实际监听的localhost:9999
任务触发后无日志，控制台看不到 Sharding 或 trigger 记录
说明调度链路卡在了 Admin 到执行器的远程调用环节。XXL-JOB 用的是 HTTP + JSON 通信，不是 RPC，所以问题往往出在序列化兼容性或线程模型上。
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 确认执行器模块引入的是
xxl-job-core，而非老版本的xxl-job-executor-sample-springboot—— 后者内置 Tomcat，若项目已用 Netty（如 WebFlux）会冲突，导致/run接口 404 - 检查执行器日志级别是否被调成
WARN以上，xxl.job.executor.logretentiondays设为 -1 会导致日志异步刷盘失败，看似没输出 - Spring Boot 2.6+ 默认禁用循环依赖，而 XXL-JOB 的
XxlJobSpringExecutor初始化时会间接引用ApplicationContext，需在application.properties加spring.main.allow-circular-references=true
分片广播任务里，ShardingUtil 拿不到分片参数
不是 API 用错了，是执行时机不对。ShardingUtil 的数据只在任务真正被执行的线程里有效，如果在 @XxlJob("demo") 方法外提前取，或者放在异步线程（比如 CompletableFuture）里调用，拿到的永远是空。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 分片信息必须在
@XxlJob标记的方法体内、同步上下文中调用：ShardingUtil.getShardingParam().getNow() - 避免在
static方法或工具类静态字段里缓存ShardingUtil实例——它内部用ThreadLocal绑定当前任务上下文，跨线程即失效 - 如果任务逻辑需要拆成多个子任务并行处理，每个子任务必须显式传入
shardingItem和shardingTotal，不能指望子线程自动继承
分片逻辑看着简单，但所有隐式依赖线程上下文的地方，一旦进到异步、定时、代理增强的代码路径里，就容易丢参数。这点比 Cron 表达式还容易踩坑。
