简介最新XXLJOB K8s集群部署验证版YAML文件面向需要在Kubernetes环境中快速接入XXL-JOB调度中心的运维工程师、平台开发人员以及容器化改造项目团队。这一部署包解决的是xxljob在K8s集群中部署配置繁琐、参数易错、验证成本高等常见问题由于已经过部署验证比社区常见模板更具可靠性可直接作为生产或测试集群的部署基线避免从零编写清单的重复劳动。压缩包整体仅782B内部只有1个文件即经过整理的独立YAML清单涵盖K8s部署所需的核心对象定义结构紧凑无冗余无需二次解包和复杂目录跳转。目前已有646人学习/下载适合具备基础K8s操作经验、希望快速打通xxljob定时任务调度链路的用户也可以作为后续调整命名空间、资源配额或镜像版本的起步模板。对初学者而言这仍是一份便于逐行理解xxljob在K8s中运行依赖的精简参考能帮助降低容器化部署门槛。1. 把 XXL-JOB 搬上 K8s一份能直接 apply 的 YAML和它背后的网络真相XXL-JOB 应该是国内用得最广的开源分布式定时任务调度平台了轻量、可控、文档全二开成本低。但把它从单机 jar 包迁移到 K8s 集群部署很多人第一版翻车都不是因为任务本身而是因为没搞懂调度中心与执行器之间的回调链路。我这次给的是一套验证过的 YAML 部署方案admin、executor、MySQL、日志目录全都编排好kubectl apply 就能跑起来调度中心页面能登录执行器能注册手动触发一次任务能拿到完整日志。适合刚把定时任务平台容器化的团队也适合准备做 xxljob 集群部署、正在梳理 K8s 资源清单的从业者。2. 部署模型先行调度中心、执行器与 K8s 组件如何一一映射容器化最忌讳上来就写 YAML至少得先把 XXL-JOB 的运行模型和 K8s 的对象模型对齐。很多人混淆 k8s 和 docker 的区别以为把 jar 包塞进容器就完事结果 Service、探针、持久化一个都没做Pod 重启一次配置就丢一次。这一章先把模型讲清楚。2.1 四个角色一次看清admin、executor、MySQL、任务日志XXL-JOB 本身分两个进程角色xxl-job-admin 是调度中心负责任务的 cron 解析、触发、调度日志展示xxl-job-executor 是执行器真正跑 JobHandler并把执行结果回传给调度中心。中间还有一个强制依赖的 MySQL所有任务配置、调度记录、执行结果都落库。第四个容易被忽略的角色是任务日志它在 executor 的本地磁盘上通过调度日志里的日志地址再去读对应的文件内容。在 K8s 里这四个角色的映射关系大致是admin 用 Deployment 部署副本数按调度压力从 1 到 3 都可以但要注意多副本时调度日志和任务锁都在 MySQL必须把数据库外置否则副本之间状态不一致executor 用 Deployment 部署副本数就是任务执行的并行度同一 appname 下的多个 executor 会分摊任务MySQL 用 StatefulSet 或者直接托管云数据库不能跟 admin 挤在一个 Pod 里任务日志则要挂 PVC 或者把 stdout 接出来。这里最关键的认知是XXL-JOB 的“集群”不是 K8s 意义上的负载均衡集群admin 多副本需要数据库锁来保证同一时刻只有一个节点在触发调度executor 多副本才真正把任务分发到不同 Pod。所以 YAML 里 replicas 的语义要分清楚。2.2 网络回调是第一个分水岭从 admin 到 executor 的链路XXL-JOB 的调度链路和很多 MQ 类中间件不一样它不是 admin 把任务推给 executor 之后就各管各的。admin 在命中 cron 后先通过 HTTP 回调执行器暴露的端口执行器收到触发请求后异步跑 JobHandler再把执行结果通过同一个 HTTP 连接回传。也就是说 admin 必须能访问到 executorexecutor 也必须能访问到 admin。这个双向网络依赖在容器化环境里会引出很多问题。executor 启动时会自动探测本机 IP探测到的往往是 Pod IP比如 10.244.1.23然后把这个 IP 注册到调度中心。如果 admin 和 executor 在同一个集群的同一个 Namespace 下Pod 到 Pod 是通的这没问题。但如果 executor 用了 hostNetwork或者调度中心跑在集群外部又或者集群的 CNI 网段跨节点路由有问题回调就会断掉表现就是“触发任务失败报 503”。所以我在设计 YAML 时admin 和 executor 都放在同一个 Namespace 里executor 内部通过 Service DNS 访问 adminexecutor 本身不额外暴露 NodePort让回调链路在集群网络内部闭环。这样网络模型最简单也最容易排障。等这套跑通了再根据自身网络环境去调注册地址和暴露方式。2.3 镜像与版本选择官方镜像、执行器样例与参数覆盖方式镜像方面直接使用官方仓库admin 是 xuxueli/xxl-job-admin执行器是 xuxueli/xxl-job-executor-sample-frameless。这个组合的好处是执行器镜像已经内置了一个 demoJobHandler部署完就能在页面上手动触发一次任务验证全链路。版本选 2.4.0 即可2.x 系列配置项基本通用后续升级也只需要替换镜像 tag。官方镜像的启动方式有一个特殊点容器 entrypoint 会读取一个 PARAMS 环境变量把里面的字符串原样追加到 java 启动命令后面。这正好是用来覆盖 Spring Boot 配置项的入口比如数据库地址、执行器端口、日志路径都可以通过 PARAMS 传进去。常见做法有两种一种是把整个 PARAMS 写成一个很长的单行字符串放在 Deployment 的 env 里另一种是用 ConfigMap 管理。我比较推荐 ConfigMap因为它把配置和部署结构分开了后面调参数不用反复改 Deployment。需要提醒的是PARAMS 这个环境变量里传的是 Spring Boot 的命令行参数优先级比 application.properties 高所以它能覆盖镜像内默认配置。镜像里默认会连一个 localhost 的 MySQL如果不覆盖admin 启动后一定会报数据库连接失败。3. 落地 YAML一份可直接部署的 xxl-job 编排文件拆解这一章直接给资源清单。整体编排顺序是 Namespace、ConfigMap、MySQL、admin、executor。我建议不要把所有对象揉进一个超长文件至少把 MySQL 和业务组件分开不然后面单独重建数据库会很麻烦。3.1 Namespace 与 ConfigMap把参数从镜像里解耦出来我习惯先建一个独立的 Namespace 把 xxl-job 相关资源收拢和业务应用隔离。这样后面做权限控制、网络策略、资源配额都方便。apiVersion: v1 kind: Namespace metadata: name: xxl-job接着是 ConfigMapadmin 和 executor 的 PARAMS 都放这里。注意-是 YAML 的折叠标量会把换行折叠成空格最终得到的 PARAMS 是一整行正好符合官方镜像的读取方式。apiVersion: v1 kind: ConfigMap metadata: name: xxl-job-config namespace: xxl-job data: admin_params: - --server.port8080 --spring.datasource.urljdbc:mysql://mysql-svc.xxl-job.svc.cluster.local:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai --spring.datasource.usernamexxl_job --spring.datasource.passwordxxl_job_pass --xxl.job.accessToken executor_params: - --xxl.job.admin.addresseshttp://xxl-job-admin-svc.xxl-job.svc.cluster.local:8080/xxl-job-admin --xxl.job.executor.appnamexxl-job-executor --xxl.job.executor.ip --xxl.job.executor.port9999 --xxl.job.executor.logpath/data/applogs/xxl-job/jobhandler --xxl.job.executor.logretentiondays30这里解释几个参数的用意。数据库 URL 里我用了服务名 mysql-svc.xxl-job.svc.cluster.local而不是 Pod IP因为 Pod 重建 IP 会变Service DNS 才是稳定的访问入口。executor 的xxl.job.executor.ip故意留空让容器自己探测 Pod IP在我们的网络模型下它是可达的。xxl.job.executor.logpath必须和后面 Volume 的挂载路径一致否则日志文件写不进持久化目录。3.2 调度中心 adminDeployment、Service 与 NodePort 暴露admin 的 Deployment 关键是把 PARAMS 从 ConfigMap 引进来同时配置就绪探针。探针的 initialDelaySeconds 要给足因为 admin 启动时要建连接池、加载任务配置就算进程起来了HTTP 接口也要等一会儿才能响应。如果探针配得太激进Pod 会被不断重启Service 的 Endpoints 又一直为空。apiVersion: apps/v1 kind: Deployment metadata: name: xxl-job-admin namespace: xxl-job spec: replicas: 1 selector: matchLabels: app: xxl-job-admin template: metadata: labels: app: xxl-job-admin spec: containers: - name: xxl-job-admin image: xuxueli/xxl-job-admin:2.4.0 ports: - containerPort: 8080 env: - name: PARAMS valueFrom: configMapKeyRef: name: xxl-job-config key: admin_params - name: TZ value: Asia/Shanghai readinessProbe: httpGet: path: /xxl-job-admin/ port: 8080 initialDelaySeconds: 60 periodSeconds: 10admin 的 Service 先用 ClusterIP因为 executor 要从集群内访问它。如果要打开管理页面再额外加一个 NodePort 或者 Ingress。我给的是两者都兼容的方案Service 类型设 NodePort指定 32080 端口方便浏览器直接访问。apiVersion: v1 kind: Service metadata: name: xxl-job-admin-svc namespace: xxl-job spec: type: NodePort selector: app: xxl-job-admin ports: - name: http port: 8080 targetPort: 8080 nodePort: 320803.3 执行器 executorDeployment 与注册 IP 处理executor 的 Deployment 核心配置项是 appname 和 admin 地址。appname 相当于执行器分组在 admin 页面里配置任务时也要选同一个 appname否则任务触发时找不到执行器。admin 地址必须指向 admin 的 Service DNS我见过有人把这里写成 localhost那是单机部署的写法容器里这么写只会连到 executor 自己。apiVersion: apps/v1 kind: Deployment metadata: name: xxl-job-executor namespace: xxl-job spec: replicas: 2 selector: matchLabels: app: xxl-job-executor template: metadata: labels: app: xxl-job-executor spec: containers: - name: xxl-job-executor image: xuxueli/xxl-job-executor-sample-frameless:2.4.0 ports: - containerPort: 9999 env: - name: PARAMS valueFrom: configMapKeyRef: name: xxl-job-config key: executor_params - name: TZ value: Asia/Shanghai volumeMounts: - name: job-log mountPath: /data/applogs/xxl-job/jobhandler volumes: - name: job-log persistentVolumeClaim: claimName: xxl-job-log-pvc副本数给 2 是为了演示执行器分组的效果任务调度时 admin 会挑一个可用的执行器下发。日志目录挂的是 PVC后面日志检索和数据持久化都依赖这一步。不挂的话 Pod 一删日志就没了线上排查问题会非常被动。3.4 MySQL 初始化与数据持久化让调度记录不再睡在临时目录XXL-JOB 的数据库表结构官方在 GitHub 仓库里有不在容器里。部署时最省事的做法是让 MySQL 容器第一次启动时自动执行初始化脚本。MySQL 官方镜像支持把 .sql 文件放到 /docker-entrypoint-initdb.d/ 目录首次启动会自动按文件名顺序执行。我一般用 ConfigMap 把初始化脚本挂载进去。apiVersion: v1 kind: ConfigMap metadata: name: xxl-job-mysql-init namespace: xxl-job data: tables_xxl_job.sql: | -- 这里是从官方仓库下载的初始化脚本 -- 包含 xxl_job_qrtz_* 系列表 -- 包含 xxl_job_info、xxl_job_log、xxl_job_registry 等业务表MySQL 的 Deployment 只需要单副本数据目录挂 PVC。这里给的是关键片段密码按自己环境改。apiVersion: apps/v1 kind: Deployment metadata: name: mysql namespace: xxl-job spec: selector: matchLabels: app: mysql template: metadata: labels: app: mysql spec: containers: - name: mysql image: mysql:8.0 ports: - containerPort: 3306 env: - name: MYSQL_ROOT_PASSWORD value: root_pass - name: MYSQL_DATABASE value: xxl_job - name: MYSQL_USER value: xxl_job - name: MYSQL_PASSWORD value: xxl_job_pass volumeMounts: - name: mysql-data mountPath: /var/lib/mysql - name: init-script mountPath: /docker-entrypoint-initdb.d volumes: - name: mysql-data persistentVolumeClaim: claimName: xxl-job-mysql-pvc - name: init-script configMap: name: xxl-job-mysql-init数据库初始化要注意一个顺序问题admin 启动时如果发现表不存在它会尝试建表但部分旧版本脚本不完整可能导致后续调度日志写入报错。所以最好还是让 MySQL 先把表建好admin 再起来。部署顺序上YAML 可以一次性 apply但 MySQL Pod 启动到初始化完成需要几十秒admin 的连接池如果反复重试最终也能连上不会造成数据损坏。4. 从 kubectl apply 到任务跑通部署验证全流程YAML 准备好之后部署顺序基本是从底层到上层先 Namespace再 ConfigMap再 MySQL最后 admin 和 executor。这样即便 apply 报错也能快速定位是哪一层的问题。4.1 应用 YAML 的顺序与命令我没有把所有对象拼成一个巨型 YAML而是按职责拆成几个文件按顺序执行kubectl apply -f 01-namespace.yaml kubectl apply -f 02-configmap.yaml kubectl apply -f 03-mysql.yaml kubectl apply -f 04-xxl-job.yamlNamespace 和 ConfigMap 是纯声明apply 后立即生效。MySQL 的 Deployment 会先拉镜像首次启动时跑初始化脚本这段时间 admin 不必等它即使 admin 先起来了Spring Boot 的数据源重试机制也会在 MySQL 就绪后自动连上。一个需要注意的小习惯apply 之后不要急着看页面先看 Pod 状态。K8s 里 YAML 语法错误会在 apply 时报出来但网络不通、镜像拉取失败、探针不通过这类问题只能靠下面这条命令发现。kubectl -n xxl-job get pods -o wide如果某个 Pod 一直处于 ContainerCreating多半是 PVC 没绑定或者镜像拉取有问题如果是 Running 但 READY 显示 0/1基本是探针没过。这两种情况的排查路径完全不同先从 READY 列区分开。4.2 三个“真跑通”的验证信号很多人部署完能看到登录页就觉得成功了其实那只说明 admin 的 web 服务起来了。我判断一套 XXL-JOB 集群真正可用要看三个信号。第一个信号是 admin 页面能登录默认账号 admin / 123456登录后能看到左侧菜单和仪表盘。这一步验证的是 admin 和 MySQL 之间的读写链路如果表缺失或者用户名密码不对登录时会直接报错。第二个信号是“执行器管理”页面里能看到刚才部署的 executor状态是“在线”。这里有一个时间差executor 启动后要向 admin 心跳注册默认大概 30 秒内会出现。如果一直是空列表或者显示离线问题基本在 executor 配置的 admin 地址、appname 或者网络不通后面避坑章会展开说。第三个信号是调度日志里有真实的调度记录。进入“任务管理”找到 sample 任务点“执行一次”然后去“调度日志”里刷新。如果是执行成功且能看到返回的执行结果说明 admin 到 executor 的回调链路是通的。这三个信号全部满足才算部署验证通过。4.3 手动触发一次任务并核对日志链路官方 executor 镜像里自带了一个 demoJobHandler任务管理里通常已经存在对应的示例任务。如果没有手动新建一条任务JobHandler 填 demoJobHandlercron 随便填一个未来的时间执行器选 xxl-job-executor 分组。kubectl -n xxl-job logs -l appxxl-job-executor --tail100点“执行一次”之后建议去这个 Pod 日志里看。正常情况下能看到类似触发请求进来、JobHandler 开始执行、执行完毕回传结果的日志行。如果这里空白说明任务根本没下发到 executor问题在 admin 侧如果这里显示了执行过程但页面上的调度日志没有回执问题在执行器回传那一段。日志可以看到“xxl-job executor”的注册、心跳、线程池等信息。确认完这些再在页面上看调度日志里的“执行日志”里面会显示具体的日志地址这个地址指向 executor 容器里的文件路径。我在 PVC 挂载了日志目录所以即使 Pod 重启这个日志也还在。5. 避坑指南靠近生产环境的 XXL-JOB 容器化问题清单这一章把我在线上和测试环境踩过的坑按“现象、原因、解决”整理出来。每一条都是真实会发生的问题不是理论推演。5.1 调度中心注册不上从 503 响应看网络回调的断点现象executor 启动日志显示注册成功但 admin 页面“执行器管理”里看不到在线执行器或者任务触发后调度日志一直报“执行器返回结果失败”伴随 HTTP 503。原因503 是 admin 发起 HTTP 回调时连不上 executor。常见原因有三个。第一executor 探测到的注册 IP 是 Pod IP而 admin 与 executor 之间存在跨节点网络隔离CNI 插件配置了网络策略但没有放行这一对 Pod。第二executor 配置了xxl.job.executor.ip指向节点 IP但节点防火墙没有放行 9999 端口。第三admin 的 PARAMS 里忘配xxl.job.accessToken而两端 token 不一致触发时会报签名错误。解决把 admin 和 executor 放在同一个 Namespace先验证 Pod IP 之间的连通性再确认为空 token 或统一 token。从集群内任意一个 Pod 执行curl http://executor-pod-ip:9999能通基本就解决了。5.2 任务触发成功但日志是空的时区与目录的联动坑现象手动执行任务调度日志显示“成功”但“查看日志”点开是一片空白或者日志时间比北京时间晚了 8 小时。原因这个坑有两个触发点。一是容器默认时区是 UTCadmin 和 executor 的时间都偏了 8 小时调度时间和执行时间对不上日志文件里的时间戳看起来就是错位的。二是日志写到了容器里的临时路径没有挂载出来页面读取日志时通过调度日志里的地址去容器文件系统里找但只要 Pod 被调度到别的节点这个路径就找不到了。解决在 Deployment 的 env 里统一加TZAsia/Shanghai同时把 executor 的日志路径挂到 PVC。改完配置后重启 Pod再手动触发一次任务此时页面日志里能显示北京时间日志文件也能持久保留。5.3 Pod 重启后任务重复执行状态从 MySQL 与 PV 里找回来现象executor Pod 异常重启恢复后最近一段时间内的任务被重复执行了或者刚好相反某个任务明明跑过调度日志里却查不到记录。原因XXL-JOB 的任务触发记录以 MySQL 为准但执行中的任务状态在 executor 内存里。如果 Pod 在任务执行过程中被 killadmin 侧可能已经记录触发成功executor 侧的实际执行结果却丢失去重启后就会出现对不上的情况。同时如果 MySQL 是容器化部署又没有挂 PVPod 重建会把调度日志整个清空。解决MySQL 必须持久化executor 的日志目录也必须挂 PVC。如果确实出现过重复执行检查任务的阻塞处理策略改为“丢弃后续调度”或者“覆盖之前调度”线上财务类、对账类任务尤其不能允许重复执行。5.4 PARAMS 配置串折行导致启动参数被截断现象admin 或 executor 容器不断重启日志里能看到不完整的启动参数比如数据库 URL 后半段被截断。原因我在 ConfigMap 里用的是 YAML 折叠标量-它有特殊规则缩进块内的换行会被折叠成空格但如果内容里出现了空行或额外缩进折叠行为会改变多行参数可能被当成一个参数传递Spring Boot 解析时就会报错。解决不要把整串 PARAMS 手工折成几行写在代码块里要么保持-折叠写法且内部无空行要么直接把整个参数串写成一整行。部署后先用下面的命令确认容器实际拿到的参数kubectl -n xxl-job exec deploy/xxl-job-admin -- env | grep PARAMS5.5 admin 页面能打开但登录报数据库错误现象浏览器能访问/xxl-job-admin/页面但输入默认账号密码后提示系统异常后台日志里是 Unknown database 或 Table doesnt exist。原因admin 的 web 服务启动成功了但数据源配置有问题。最常见的是 MySQL 初始化脚本没执行成功数据库里是空的或者是 PARAMS 里的 username 和 password 与 MySQL 容器里创建的用户不一致。MySQL 8.0 默认认证插件是 caching_sha2_password某些老版本 JDBC 驱动也会连不上。解决进 MySQL 容器检查库表。kubectl -n xxl-job exec deploy/mysql -- mysql -uxxl_job -pxxl_job_pass -e use xxl_job; show tables;确认表存在后再回头看 admin 的 PARAMS 是否指向了正确的 Service DNS。5.6 探针配置太激进导致 Pod 反复重启现象admin Pod 启动后过一会儿就被 K8s 重启kubectl describe pod里能看到 Liveness probe failed 的记录。原因livenessProbe 和 readinessProbe 的探活地址指向/xxl-job-admin/但 Spring Boot 在任务持久化、线程池初始化还没完成时这个接口返回的不是 200。如果 initialDelaySeconds 设置得太短比如 10 秒K8s 会判定探活失败并重启容器反而让应用永远进不了就绪状态。解决探针的路径、端口、延迟时间要和应用的启动耗时匹配。我这边 initialDelaySeconds 给的 60 秒如果机器性能差或 JVM 参数改了堆内存建议再放宽到 90 秒。只保留就绪探针不需要 livenessProbe避免网络抖动触发重启。6. 进阶技巧把 xxl-job 日志从 K8s 里捞出来做线上检索XXL-JOB 的任务日志默认在 executor 的磁盘路径下日志按任务 ID 和触发时间分文件做线上问题排查时我们最常遇到的场景是用户说“某个任务在某个时间点跑失败了”这时你的第一步不是翻页面而是直接在容器里按关键字过滤日志。我平常最顺手的一条命令是这样先找到 executor 的 Pod然后持续跟踪日志输出kubectl -n xxl-job logs -l appxxl-job-executor -f --tail200 | grep -E JobHandler|执行成功|执行失败但注意kubectl logs只能看到 stdout而 xxl-job 的 JobHandler 日志默认写在文件里通过 logback 的 console appender 才会打到 stdout。如果你发现容器日志里只有注册信息、没有任务执行细节那就直接进容器读文件日志路径就是 ConfigMap 里配的/data/applogs/xxl-job/jobhandler。kubectl -n xxl-job exec deploy/xxl-job-executor -- find /data/applogs/xxl-job/jobhandler -name *.log -mtime -1 | head -20挂载了 PVC 之后这个目录可以长期保留。我会按日志日期 任务 ID的规律去定位文件文件内容包含触发参数、执行耗时、返回结果比页面里的摘要日志更适合分析问题。更快的方法是在调度日志页面里找到“日志地址”一栏直接拼出容器里的文件路径然后体验更顺。如果任务量大stdout 方式会更适合接入日志平台。可以把 executor 的 logback 配置改成同时输出到标准输出和文件然后在集群里部署 filebeat 采集容器日志按 appname 打索引。这是我目前比较推荐的组合立即检索走 stdout问题复盘走持久化日志文件。最后再说一个我自己的操作习惯。从那以后我每次部署完 xxl-job都会强制自己走一遍三连验证先去执行器管理页面看在线状态再手动触发一次任务最后去容器里翻一下 JobHandler 日志。这三件事做齐了这份 YAML 才算真的落地而不是页面能打开就完事。希望帮到你。本文还有配套的精品资源点击获取