XXL-JOB容器化部署实战：K8S集群落地与避坑指南

简介：面向需要在Kubernetes集群中快速部署XXL-JOB定时任务调度平台的运维与开发人员，这份经过验证的YAML部署文件可省去自行编写配置的繁琐过程，直接应用到集群即可完成基础环境搭建。资源包内共1个文件，为YAML格式清单，整体仅约782B，轻量小巧，便于下载与审阅，适合直接纳入现有集群或作为部署模板二次调整。目前已有646人学习下载，说明该方案被不少同类场景使用者认可。该YAML将XXL-JOB容器化部署所需的关键配置集中整合，涵盖集群模式下的资源对象定义，读者既能直接拿来落地，也可作为理解K8s服务编排与xxljob部署细节的参考样例，降低环境搭建与排错成本。相比从零编写，这份经验沉淀能明显缩短从镜像到服务可用的验证周期，尤其适合生产前快速验证与CI/CD流水线集成。

1. XXL-JOB 容器化部署：本地能跑不代表集群能用

调度中心在本地 IDE 里一点就起，复制到 K8S 集群却怎么调都起不来，卡了一整天最后发现是连接串少了时区参数——这种经历，部署过 XXL-JOB 的人多少都撞上过。XXL-JOB 是最常见的分布式任务调度框架，容器化部署本身不复杂，真正劝退人的是 YAML 里的隐性约定：执行器注册地址怎么写、Pod IP 漂移了怎么办、admin 和 executor 版本能不能对上、MySQL 到底放不放集群里。这些问题不提前理清，YAML 一遍遍 apply 下去，报错全是玄学。这篇笔记以 XXL-JOB 2.4.0 为例，记录一套从 MySQL、调度中心到执行器在 K8S 集群里完整落地的部署方案，版本、镜像、参数、验证拆开讲。

2. 版本与部署前准备：镜像、存储、命名空间一次定清

2.1 镜像版本选择：admin 与 executor 必须保持同一分支

动手写 YAML 之前，先确认一件事：调度中心（xxl-job-admin）和执行器（xxl-job-executor）的镜像版本要保持在同一条大版本线上。我见过有人在集群里 admin 用 2.4.0，执行器却拉了个 2.2.0 的镜像，结果执行器管理页能看到心跳，点执行就一直超时。XXL-JOB 调度器和执行器之间的通信字段在不同版本里有变化，老执行器注册上来后，admin 经常解析不出地址信息，日志里又看不出明显报错，只表现为任务调度超时。这种问题排查起来非常费劲，因为表面迹象和实际原因隔了一层。

版本确定后，镜像要提前准备好。常见做法是把 xxl-job-admin 和 xxl-job-executor 对应版本的镜像拉到本地，再推到你集群节点能访问的私有仓库，YAML 里的 image 字段直接写私有仓库地址。如果集群节点拉镜像不方便，这一步必须在部署前做完，否则 apply 的时候会卡在 ImagePullBackOff 上。我一般会顺手把镜像 tag 固定下来，比如 xxl-job-admin:2.4.0，不写 latest，避免过段时间拉下来一个行为不一致的新镜像。

2.2 命名空间与资源规划：PVC、副本数、StorageClass 预先定好

这套部署我建议单独开一个命名空间，叫 xxl-job，和业务应用隔离。集群里如果多个项目共用默认空间，Deployment、Service 重名冲突不说，后面看日志、清理资源都乱。命名空间本身是一个很轻量的资源，单独建一个不亏。下面是我常用的资源规划方式。

MySQL 放进集群还是用外部实例，取决于你那边的基础设施情况。如果公司已经有 RDS 或者统一的 MySQL 服务，直接用外部地址就行，省掉一个要维护的组件；如果没有，就在集群里起一个单实例 MySQL 做元数据库，测试环境足够。PVC 的 storageClass 要提前确认，K8S 集群默认 storageClass 没配好的话，PVC 会一直 Pending，后面 Pod 也起不来。

2.3 核心环境变量清单：部署前先把参数表吃透

XXL-JOB 两个镜像本质上是 Spring Boot 应用，官方镜像默认支持用环境变量 PARAMS 直接透传启动参数，不用进容器改配置文件。部署前把下面这张表吃透，后面写 YAML 基本不会慌。

这里最容易被忽略的是时区参数 serverTimezone。MySQL 连接串里不加它，admin 启动时大概率报 "The server time zone value" 之类的时区异常。另外 accessToken 默认是空的，但集群环境下我会强制设一个，防止内网里其他服务误连调度中心。这个值调度中心配置和执行器配置必须完全一致，一个小数点不对，执行器就注册不上。

3. 逐项落地 YAML：从 MySQL 到调度中心再到执行器

3.1 MySQL：把调度中心的元数据库放进集群

先写 MySQL 的 Deployment 和 Service。这一层比较标准，关键是把数据目录挂到 PVC 上，Pod 重启后数据不丢。下面这份 YAML 可以直接存成 01-mysql.yaml。

apiVersion: apps/v1 kind: Deployment metadata: name: xxl-job-mysql namespace: xxl-job spec: replicas: 1 selector: matchLabels: app: xxl-job-mysql template: metadata: labels: app: xxl-job-mysql spec: containers: - name: mysql image: your-registry/mysql:5.7 ports: - containerPort: 3306 env: - name: MYSQL_ROOT_PASSWORD value: "XxlJob@2024" - name: MYSQL_DATABASE value: "xxl_job" volumeMounts: - name: mysql-data mountPath: /var/lib/mysql volumes: - name: mysql-data persistentVolumeClaim: claimName: xxl-job-mysql-pvc --- apiVersion: v1 kind: Service metadata: name: xxl-job-mysql namespace: xxl-job spec: selector: app: xxl-job-mysql ports: - port: 3306 targetPort: 3306

容器启动时 MYSQL_DATABASE=xxl_job 会自动建库，数据目录挂在 PVC 上，Pod 删了重建数据还在。MySQL 5.7 的镜像比较成熟，XXL-JOB 官方文档里对 MySQL 版本没有特别苛刻的要求，5.7 是足够稳的选择。PVC 部分需要你提前在集群里准备好 storageClass，创建方式通常是维护同学已经配好的，不需要你手动建 PV。

建完库之后，表结构需要手动初始化。XXL-JOB 官方提供了一个建表 SQL 脚本 tables_xxl_job.sql，这步不能跳过。把脚本拷进 Pod 再执行：

MYSQL_POD=$(kubectl get pod -n xxl-job -l app=xxl-job-mysql -o jsonpath='{.items[0].metadata.name}') kubectl cp ./tables_xxl_job.sql xxl-job/$MYSQL_POD:/tmp/tables_xxl_job.sql kubectl exec -n xxl-job $MYSQL_POD -- sh -c 'mysql -uroot -pXxlJob@2024 xxl_job < /tmp/tables_xxl_job.sql'

第一条命令先动态拿到 MySQL Pod 的名字，再用 kubectl cp 把本地的 SQL 脚本传进 Pod 的 /tmp 目录，最后在 Pod 里执行导入。这里没有把 Pod 名写死，因为 Deployment 管理的 Pod 名带随机后缀，每次重建都会变。如果导入时报错，先检查脚本路径是否传对，再检查 mysql 客户端版本兼容性。

3.2 调度中心 admin：Deployment、探针与 Service 三件套

调度中心是核心组件，建议开两个副本。它的状态都存在 MySQL 里，多副本不会产生数据不一致的问题，反而能避免单点故障。探针很重要：admin 启动比较慢，探针配置不当会出现明明还在启动却被误杀的情况，后面避坑章节专门讲。这份存成 02-admin.yaml。

apiVersion: apps/v1 kind: Deployment metadata: name: xxl-job-admin namespace: xxl-job spec: replicas: 2 selector: matchLabels: app: xxl-job-admin template: metadata: labels: app: xxl-job-admin spec: containers: - name: admin image: your-registry/xxl-job-admin:2.4.0 ports: - containerPort: 8080 env: - name: PARAMS value: "--spring.datasource.url=jdbc:mysql://xxl-job-mysql:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false --spring.datasource.username=root --spring.datasource.password=XxlJob@2024" readinessProbe: httpGet: path: /xxl-job-admin/ port: 8080 initialDelaySeconds: 30 periodSeconds: 10 livenessProbe: httpGet: path: /xxl-job-admin/ port: 8080 initialDelaySeconds: 60 periodSeconds: 20 --- apiVersion: v1 kind: Service metadata: name: xxl-job-admin namespace: xxl-job spec: type: ClusterIP selector: app: xxl-job-admin ports: - port: 8080 targetPort: 8080

PARAMS 环境变量把数据库连接串一次性透传进去，多个参数之间用空格分开，每个参数前加 -- 前缀，这是 Spring Boot 标准的命令行参数写法。连接串里必须带 serverTimezone=Asia/Shanghai。镜像默认端口是 8080，context path 是 /xxl-job-admin，所以探针的 path 写成 /xxl-job-admin/，不要把路径漏掉。

两个探针的 initialDelaySeconds 我给得比较保守。readinessProbe 等 30 秒才开始探测，livenessProbe 等 60 秒，因为 admin 第一次启动要初始化连接池。如果设得太小，探针在应用还没就绪时就判失败，Pod 会被反复重启，日志里又看不出业务异常。

3.3 执行器 executor：IP 注入、Token 与日志路径

执行器的部署比 admin 多了两个关键点：IP 注入和端口暴露。很多人在这里翻车，直接把 IP 写死成某个固定值，Pod 重建之后就彻底失联。正确做法是用 Kubernetes 的 fieldRef 机制把当前 Pod 的 IP 注入到环境变量里，再传给启动参数。这份存成 03-executor.yaml。

apiVersion: apps/v1 kind: Deployment metadata: name: xxl-job-executor namespace: xxl-job spec: replicas: 1 selector: matchLabels: app: xxl-job-executor template: metadata: labels: app: xxl-job-executor spec: containers: - name: executor image: your-registry/xxl-job-executor:2.4.0 ports: - containerPort: 9999 env: - name: POD_IP valueFrom: fieldRef: fieldPath: status.podIP - name: PARAMS value: "--xxl.job.admin.addresses=http://xxl-job-admin:8080/xxl-job-admin --xxl.job.accessToken=XxlJob@Token2024 --xxl.job.executor.appname=xxl-job-executor --xxl.job.executor.ip=$(POD_IP) --xxl.job.executor.port=9999 --xxl.job.log.path=/data/applogs/xxl-job/jobhandler" volumeMounts: - name: logs mountPath: /data/applogs/xxl-job volumes: - name: logs emptyDir: {}

POD_IP 环境变量通过 fieldRef 从 status.podIP 取值，这是 K8S 原生的字段注入方式，Pod 每次重建都会拿到新 IP，不需要你手工改 YAML。这里有个顺序要求：POD_IP 必须定义在 PARAMS 之前，这样 PARAMS 里的 $(POD_IP) 才能被正确展开。如果顺序写反，容器启动后 IP 是空的，执行器注册的地址就是 :9999。

accessToken 我在这里写的是 XxlJob@Token2024，你在实际部署时替换成自己的随机字符串。这个值要和 admin 侧保持一致，后面有时间我再写一篇怎么用 Secret 管理 token——部署阶段用明文写在 YAML 里是常见做法，记得到生产环境要换掉。

3.4 apply 顺序与一次过检查：从空集群到 XXL-JOB 启动

三个 YAML 文件都准备好之后，apply 的顺序有讲究。我的习惯是先建命名空间和 MySQL，再导 SQL，最后起 admin 和 executor。上面已经建好表的话，直接执行：

kubectl create namespace xxl-job kubectl apply -n xxl-job -f 01-mysql.yaml kubectl apply -n xxl-job -f 02-admin.yaml kubectl apply -n xxl-job -f 03-executor.yaml

如果命名空间已经存在，kubectl create 会报 AlreadyExists，这个错误不影响后续操作，直接继续 apply 就行。想避免这条报错的话，也可以把 namespace 写成一个单独的 YAML 文件，用 kubectl apply -f namespace.yaml 来创建。apply 的顺序是先 MySQL 后 admin，因为 admin 启动时就要连数据库；executor 放最后，它启动时需要能访问 admin。

apply 完成后先看 Pod 状态：

kubectl get pod -n xxl-job -o wide

正常的话三个 Pod 都会是 Running 且 Ready 为 1/1。如果看到 CrashLoopBackOff，先看日志：

kubectl logs -n xxl-job deployment/xxl-job-admin --tail=100

日志里出现数据库连接异常，优先排查 MySQL 的 Service 名、端口和密码；出现时区相关报错，检查连接串里的 serverTimezone 参数。executor 的日志则要特别注意注册地址打印出来的内容，确认 IP 不是空的。

4. 避坑指南：XXL-JOB 容器化部署的五个典型翻车现场

4.1 数据库连不上：时区参数与 DNS 解析都要看

现象：admin Pod 启动后一直 CrashLoopBackOff，kubectl logs 里反复刷 Communications link failure 或者 Access denied。

原因：多数情况是连接串写错。最常见的两个坑：一是忘了加 serverTimezone=Asia/Shanghai，MySQL 驱动在时区不明确时会直接抛异常；二是 Service 名称写错，比如把 xxl-job-mysql 写成了 mysql，或者漏了端口。

解决：先核对连接串里的 Service 名、端口和密码。用 kubectl exec 进 admin Pod 里测试连通性，再用 kubectl logs 看完整异常栈。把连接串改成 jdbc:mysql://xxl-job-mysql:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false，基本能解决九成问题。

4.2 执行器永远离线：Token 与 admin 地址要对齐

现象：admin 管理台能正常打开，执行器管理页面也看得到 xxl-job-executor 这个名字，但状态一直离线，注册地址显示不出来。

原因：调度中心侧配置的 accessToken 和执行器侧配置的不一致。XXL-JOB 在 token 不匹配时不会拒绝注册，而是默默丢弃心跳数据，表现就是执行器一直离线或者在线状态反复横跳。另一个原因是 admin.addresses 写错，比如把 http 写成了 https，或者路径漏了 /xxl-job-admin。

解决：两端 token 改成一样的，重启 executor。admin.addresses 必须是执行器容器内能访问到的地址，也就是 http://xxl-job-admin:8080/xxl-job-admin，不要写成 localhost。

4.3 Pod 重启后任务失联：IP 漂移才是最隐蔽的坑

现象：刚部署完一切正常，某天节点维护或者 Deployment 滚动更新后，执行器管理页里的注册地址变成了一个旧 IP，任务全部调度失败。

原因：执行器 YAML 里把 xxl.job.executor.ip 写死了。K8S 里 Pod 的 IP 是动态分配的，重建后会变，写死 IP 等于断了后路。

解决：用 3.3 节的方式，通过 fieldRef 注入 status.podIP，让执行器每次启动都拿当前 Pod 的真实 IP。这也是 K8S 部署 XXL-JOB 最推荐的方案。从那以后我再也没手写过执行器 IP，全走注入。

4.4 探针误杀：admin 启动慢被误判为不健康

现象：admin Pod 反复重启，kubectl get pod 看到 RESTARTS 一直涨，但日志里没有明显异常，最后一条日志停在 Spring Boot 的启动阶段。

原因：livenessProbe 的 initialDelaySeconds 设太小，admin 第一次启动要初始化连接池和定时线程，还没就绪就被探针判定失败，K8S 直接杀掉重启。这是个很典型的配置节奏问题。

解决：readinessProbe 的 initialDelaySeconds 调到 30 秒以上，livenessProbe 调到 60 秒以上。如果集群节点性能一般，再往上加 10 到 20 秒都不过分。探针是保护机制，不是考勤打卡，延迟大一点问题不大。

4.5 建表脚本没执行：任务配置页反复报错

现象：admin 启动成功，登录管理台也正常，但进到任务管理或者执行器管理页面时，页面报错，后台日志出现表不存在的 SQL 异常。

原因：只建了数据库，没有导入 tables_xxl_job.sql。XXL-JOB 的 admin 启动时不会自动建表，这是很多人都踩过的坑。

解决：按 3.1 节的命令把 SQL 脚本导入，然后重启 admin Pod 让连接池重新建立。导入之后可以用一条命令验证表是否存在：

kubectl exec -n xxl-job deploy/xxl-job-mysql -- sh -c 'mysql -uroot -pXxlJob@2024 -e "USE xxl_job; SHOW TABLES;"'

能看到 xxl_job_qrtz 开头的定时任务表以及 xxl_job_info、xxl_job_registry 这些核心表，才算真正完成。

5. 部署后验证：把一个定时任务完整跑通

5.1 从 Pod 状态看到调度中心启动

部署完成后，第一件事是看 Pod 状态和日志：

kubectl get pod -n xxl-job -o wide kubectl logs -n xxl-job deployment/xxl-job-admin --tail=50 kubectl logs -n xxl-job deployment/xxl-job-executor --tail=50

admin 的日志里出现监听 8080 端口的记录，executor 的日志里出现注册成功的地址信息，比如类似 xxl-job-executor-xxx:9999 的注册内容，说明两个组件通信正常。如果 executor 日志里没有出现注册地址，直接跳到第 4 章的避坑清单查 token 和 admin 地址。

5.2 浏览器登录管理台，确认执行器自动注册

验证阶段最简单的暴露方式是用 port-forward，不用改 Service 类型：

kubectl port-forward -n xxl-job svc/xxl-job-admin 8080:8080

浏览器打开 http://localhost:8080/xxl-job-admin，用镜像自带的默认管理员账号 admin / 123456 登录，首次登录后记得改密码。在左侧菜单进入“执行器管理”，正常情况下能看到一个名为 xxl-job-executor 的执行器，注册地址列显示的是 Pod IP 加 9999 端口。这里要确认地址不是空也不是 localhost，而是 10.x.x.x:9999 这种形式。

5.3 创建一个真实任务，验证调度闭环

最后一步是创建一个最简单的任务，确认调度中心能下发指令、执行器能执行并回传结果。进入“任务管理”，新增任务：

• 执行器选 xxl-job-executor
• JobHandler 填 demoJobHandler，这是镜像自带的示例处理器
• Cron 填 0/30 * * * * ?
• 运行模式选 BEAN
• 启动状态选“启动”

保存后回到任务列表，勾选该任务点击“执行一次”，然后点“调度日志”。日志里能看到调度成功、执行成功的记录，点进去看执行详情，能看到完整的执行链路。如果你用的是自己开发的执行器，JobHandler 就填代码里 @XxlJob 注解对应的 value。

这套验证走完，调度中心、元数据库、执行器、任务分发整条链路全部打通。从那以后，我每次在集群里部署 XXL-JOB，都会强制自己走一遍从建库、导表、核对 token、看注册地址到跑一个真实任务的完整流程，一步不跳。部署本身不难，难的是把每个坑的位置提前标出来。希望这篇记录能帮你在集群里少踩几个 XXL-JOB 的暗坑。

本文还有配套的精品资源，点击获取