简介这份资源面向需要在 Kubernetes 集群中落地 XXLJOB 的运维与后端开发人员提供一份经过实际部署验证的 YAML 清单解决容器化环境下任务调度平台快速搭建与配置落地的问题。压缩包内共 1 个文件为单个 yaml 类型清单包体仅 782B体量轻巧可直接通过 kubectl 应用完成部署省去手工编写与反复调试的环节。目前已有 646 人学习下载说明该部署方式在社区中具备一定参考价值。读者可借助这份验证版清单快速理解 XXLJOB 在 K8S 中的资源对象组织方式包括调度中心与执行器相关配置的编排思路并以此为模板调整镜像、副本数、环境变量与端口等参数适配自身集群环境。对于正在推进 XXLJOB 容器化部署、希望减少试错成本的团队而言这份文件可作为可直接复用的部署起点帮助缩短从零搭建到验证成功的时间。1. 从一次调度中心迁移说起XXL-JOB 上 K8S 到底值不值去年底帮一个团队把跑了三年的 XXL-JOB 从三台物理机搬到 K8S起因很朴素——调度中心单点、执行器扩容靠手工改配置、日志散在六台机器上没人愿意翻。迁移前他们最担心的是「调度中心这种有状态服务塞进容器会不会天天翻车」结果跑下来最麻烦的既不是数据库也不是注册中心而是 YAML 里几个默认值没改导致的执行器注册不上。这篇笔记就围绕一份能直接kubectl apply的 XXL-JOB K8S 集群部署 YAML 展开把调度中心、执行器、MySQL、网络暴露这几块拆开讲清楚顺带把 xxljob 容器化部署里那些玄学问题摊开说。适合正在做 k8s 学习、准备把定时任务平台容器化的后端和运维同学也适合已经踩过坑想找一份可对照配置的人。这份资源的核心价值在于「验证版」三个字它不是一份理论模板而是把调度中心xxl-job-admin、执行器xxl-job-executor、依赖的 MySQL 初始化、Service/Ingress 暴露、健康探针、资源限制这些一次性配齐改掉镜像地址和数据库密码就能起。下面按「资源里有什么 → 怎么一步步部署 → 参数怎么调 → 坑在哪 → 怎么验证和进阶」的顺序推。2. 拆开这份 YAML调度中心、执行器与 MySQL 的编排逻辑2.1 为什么调度中心要单独拆一个 DeploymentXXL-JOB 的架构里xxl-job-admin是调度中心负责触发任务、管理执行器注册、提供 Web 控制台执行器是业务侧真正跑 job 的进程。两者职责完全不同扩缩容策略也不一样调度中心通常 12 副本做高可用执行器按业务量横向扩。所以这份 YAML 把它们拆成两个独立的 Deployment而不是塞进一个 Pod。调度中心本身是无状态的状态都在 MySQL 里所以用 Deployment 而不是 StatefulSet 是合理的。常见做法是给它配 2 个副本前面挂一个 Service控制台通过 Ingress 暴露。这里有个容易忽略的点多个 admin 副本之间不需要互相通信它们共享同一个数据库靠数据库行锁保证同一任务不被重复触发所以副本数不用太多2 个足够覆盖滚动更新时的可用性。执行器这边注册方式决定了 YAML 怎么写。XXL-JOB 支持自动注册和手动录入两种容器化场景下推荐自动注册——执行器启动时把自身地址上报给调度中心。但容器 IP 是会变的所以执行器注册时上报的地址必须是 K8S 内部能解析的地址通常是Pod IP:端口或Service 名:端口。这份 YAML 用的是执行器 Deployment Headless Service 的组合让调度中心能通过稳定的 DNS 找到执行器。2.2 数据库初始化与连接配置XXL-JOB 依赖 MySQL 存任务、日志、执行器注册信息。这份 YAML 里 MySQL 用的是一个带初始化脚本的部署方式首次启动时执行官方tables_xxl_job.sql建表。关键配置在调度中心的application.properties里通过环境变量注入# xxl-job-admin Deployment 片段 env: - name: PARAMS value: - --spring.datasource.urljdbc:mysql://xxl-job-mysql:3306/xxl_job?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueserverTimezoneAsia/Shanghai --spring.datasource.usernameroot --spring.datasource.passwordxxljob123 --xxl.job.accessTokendefault_token这段PARAMS会作为启动参数传给 Spring Boot覆盖镜像里的默认配置。spring.datasource.url里的serverTimezoneAsia/Shanghai必须带否则日志时间会差 8 小时排查任务执行时间时会被带偏。xxl.job.accessToken是调度中心和执行器之间的通信凭证两边必须一致不一致的表现是执行器注册成功但触发任务时报 401。MySQL 的 Service 名要和 URL 里的主机名对上这份 YAML 里统一叫xxl-job-mysql。如果你用外部 MySQL把这段 URL 改成外部地址同时把 YAML 里的 MySQL Deployment 整段删掉即可不用改其他部分。2.3 执行器注册与网络暴露执行器 Deployment 的关键在于注册地址和端口。XXL-JOB 执行器默认端口 9999注册时上报的地址由xxl.job.executor.address决定不配的话它会用本机网卡 IP在容器里就是 Pod IP。Pod IP 在 K8S 集群内可直达所以调度中心能连上但 Pod 重建后 IP 变注册信息会短暂失效等执行器重新注册就好。# xxl-job-executor Deployment 片段 env: - name: PARAMS value: - --xxl.job.admin.addresseshttp://xxl-job-admin:8080/xxl-job-admin --xxl.job.accessTokendefault_token --xxl.job.executor.appnamexxl-job-executor-sample --xxl.job.executor.port9999 --xxl.job.executor.logpath/data/applogs/xxl-job/jobhandlerxxl.job.admin.addresses指向调度中心的 Service注意路径要带/xxl-job-admin这是控制台的 context-path漏了会注册失败。xxl.job.executor.logpath指向容器内路径这个路径必须挂 PVC 或者至少挂 emptyDir否则 Pod 重启日志全丢——xxljob 日志如何检索这个问题根源就在日志没持久化。网络暴露分两层集群内用 Service集群外用 Ingress。调度中心需要暴露 Web 控制台给运维用执行器不需要对外暴露只要调度中心能访问即可。这份 YAML 里 Ingress 只配了 admin 的规则执行器没有 Ingress这是对的。3. 从零到跑通YAML 部署的完整操作链路3.1 前置检查与命名空间准备动手前先确认集群版本和存储。XXL-JOB 对 K8S 版本不挑1.20 以上都能跑但要注意apps/v1的 Deployment 写法在 1.16 之后才稳定。存储方面MySQL 需要 PVC如果你的集群没有默认 StorageClass得先建一个否则 PVC 会一直 Pending。# 确认集群可用与默认 StorageClass kubectl version --short kubectl get storageclass # 建独立命名空间别塞 default kubectl create namespace xxl-job # 确认节点资源调度中心执行器MySQL 至少留 2C4G kubectl top nodes命名空间单独建是为了隔离XXL-JOB 的 Service 名比较通用xxl-job-admin、xxl-job-mysql放 default 里容易和别的服务撞名。kubectl top nodes看的是节点剩余资源如果节点已经很满MySQL 的 PVC 挂载可能因为资源不足卡住。3.2 按依赖顺序 apply别一把梭这份 YAML 如果是一个多文档文件直接kubectl apply -f xxl-job-k8s.yaml -n xxl-job也能跑但依赖顺序不对时调度中心会先起来然后连不上数据库反复重启。稳妥做法是按 MySQL → 调度中心 → 执行器的顺序分批 apply。# 第一步MySQL 与初始化 kubectl apply -f 01-mysql.yaml -n xxl-job kubectl wait --forconditionready pod -l appxxl-job-mysql -n xxl-job --timeout180s # 第二步调度中心 kubectl apply -f 02-admin.yaml -n xxl-job kubectl rollout status deployment/xxl-job-admin -n xxl-job # 第三步执行器 kubectl apply -f 03-executor.yaml -n xxl-job kubectl rollout status deployment/xxl-job-executor -n xxl-jobkubectl wait那行是等 MySQL Pod ready--timeout180s给足初始化建表时间。如果 MySQL 首次启动要拉镜像加建表180 秒通常够网络慢就调到 300。rollout status会阻塞到 Deployment 完成滚动能第一时间发现镜像拉取失败或探针不过。3.3 验证调度中心与执行器注册三步都 apply 完先看 Pod 状态再进控制台确认执行器上线。# 看 Pod 和 Service kubectl get pods,svc -n xxl-job # 看调度中心日志确认数据库连接成功 kubectl logs -l appxxl-job-admin -n xxl-job --tail50 | grep -i started\|error # 端口转发到本地打开控制台 kubectl port-forward svc/xxl-job-admin 8080:8080 -n xxl-job浏览器打开http://localhost:8080/xxl-job-admin默认账号admin/123456。进「执行器管理」看xxl-job-executor-sample是否在线。如果显示离线先看执行器日志里有没有registry success再看调度中心日志有没有收到注册请求。这一步是 xxljob 容器化部署最容易卡的地方下面避坑章节细说。3.4 跑一个示例任务验证全链路执行器在线后新建一个 GLUE 模式的任务Cron 写0/30 * * * * ?运行模式选 BEANJobHandler 填demoJobHandler示例执行器自带保存后点执行一次。看调度日志里「调度成功」和「执行成功」两条记录再点「执行日志」看输出。# 同时观察执行器日志确认任务真的跑了 kubectl logs -l appxxl-job-executor -n xxl-job -f --tail20如果调度日志显示成功但执行日志为空多半是执行器日志路径没挂载或者 JobHandler 名字对不上。示例执行器里demoJobHandler是内置的自己写的执行器要确认XxlJob(yourHandler)注解里的名字和页面上填的一致。4. 参数调优与常见配置误区4.1 资源限制与 JVM 参数容器里跑 Java 服务最容易翻车的是 JVM 不认 cgroup 限制堆开到宿主机内存大小然后被 OOM Kill。这份 YAML 里给调度中心和执行器都配了resources.limits和requests同时通过JAVA_OPTS显式限制堆。resources: requests: memory: 512Mi cpu: 250m limits: memory: 1Gi cpu: 1000m env: - name: JAVA_OPTS value: -Xms512m -Xmx768m -XX:UseG1GC-Xmx768m比 limit 的 1Gi 小留出堆外内存和元空间。如果只配 limit 不配-XmxJDK 8 在某些基础镜像里会按宿主机内存算默认堆直接超 limit 被杀。requests给 512Mi 是让调度器有依据地安排节点给太小会导致节点内存碎片化。4.2 健康探针的路径与时机调度中心是 Spring Boot 应用启动要连数据库、初始化线程池冷启动可能 30 秒以上。探针配太激进会导致 Pod 反复重启看起来像「起不来」。livenessProbe: httpGet: path: /xxl-job-admin/actuator/health port: 8080 initialDelaySeconds: 60 periodSeconds: 10 failureThreshold: 3 readinessProbe: httpGet: path: /xxl-job-admin/actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 5initialDelaySeconds给 60 秒是血泪经验给 10 秒的话数据库稍慢就重启循环。注意 actuator 端点需要镜像里包含spring-boot-starter-actuator如果镜像没带把探针改成 TCP 检查port: 8080也能用只是不够精确。4.3 时区与日志持久化前面提过serverTimezone这里补一个容器时区。基础镜像默认 UTC调度中心显示的触发时间会比北京时间少 8 小时看 Cron 执行记录时非常迷惑。挂载宿主机时区或设TZ环境变量都行。env: - name: TZ value: Asia/Shanghai volumeMounts: - name: executor-logs mountPath: /data/applogs volumes: - name: executor-logs persistentVolumeClaim: claimName: xxl-job-executor-logs执行器日志挂 PVC 是为了后续检索xxljob 日志如何检索的答案就是「先持久化再用 kubectl exec 或日志采集工具捞」。不挂的话 Pod 一重建日志就没了排查历史任务只能靠数据库里的调度记录看不到业务输出。5. 避坑排查执行器注册不上与调度失败的六种情况5.1 执行器显示离线日志无注册记录现象控制台执行器列表里xxl-job-executor-sample一直离线执行器 Pod 日志里没有registry success。 原因xxl.job.admin.addresses配错最常见是漏了/xxl-job-admin路径或者 Service 名和实际不一致。 解决进执行器 Pod 里curl http://xxl-job-admin:8080/xxl-job-admin看能否返回返回 404 就是路径问题Connection refused 就是 Service 名或端口问题。5.2 注册成功但触发任务报 401现象执行器在线手动执行任务时调度日志显示「调度失败」调度中心日志有 401。 原因调度中心和执行器的xxl.job.accessToken不一致。 解决两边都检查PARAMS里的accessToken改成同一个值后重启执行器。注意 token 不要带特殊字符YAML 里之类需要转义。5.3 调度成功但执行日志为空现象调度日志两条都成功点执行日志没内容。 原因执行器logpath指向的目录没写权限或没挂载日志写不进去。 解决确认volumeMounts的mountPath和logpath一致PVC 权限用kubectl exec进去touch一个文件测试。用 emptyDir 的话重启就丢生产必须 PVC。5.4 Pod 反复重启探针失败现象kubectl get pods看到 RESTARTS 一直涨describe 里 Liveness probe failed。 原因initialDelaySeconds太短应用还没起来探针就判死。 解决调到 60 秒以上或者临时把 liveness 去掉只留 readiness确认能稳定启动后再加回来。5.5 MySQL 连接超时调度中心起不来现象调度中心日志报Communications link failure。 原因MySQL Pod 还没 ready 调度中心就启动了或者 Service 名对不上。 解决按 3.2 的顺序 apply用kubectl wait等 MySQL ready。如果 MySQL 在外部检查网络策略和防火墙。5.6 执行器扩容后任务重复执行现象执行器从 1 副本扩到 3 副本同一个任务被触发三次。 原因XXL-JOB 的路由策略默认是「第一个」或「轮询」扩副本后每个执行器都注册了调度中心按策略分发。如果业务任务不支持并发会重复跑。 解决在任务配置里把路由策略改成「分片广播」或「一致性 HASH」并在执行器里用XxlJobHelper做幂等。扩副本前先确认任务是否可并发。6. 进阶用 Ingress 暴露控制台与日志检索的落地技巧控制台默认用 port-forward 看生产环境要走 Ingress。这份 YAML 里 Ingress 规则大致是这样注意pathType和 rewrite 的配合apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: xxl-job-admin namespace: xxl-job annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: ingressClassName: nginx rules: - host: xxl-job.example.com http: paths: - path: /xxl-job-admin pathType: Prefix backend: service: name: xxl-job-admin port: number: 8080这里有个细节XXL-JOB 控制台的 context-path 是/xxl-job-adminIngress 的 path 也是它所以不要加rewrite-target把它重写掉否则页面里的静态资源路径会 404。我一般会去掉 rewrite 注解让路径原样透传。如果非要用子域名根路径访问得在应用侧改server.servlet.context-path比改 Ingress 麻烦。日志检索这块执行器日志落到 PVC 后临时排查用kubectl exec进 Pod 直接 grep# 进执行器 Pod 按任务日志 ID 检索 kubectl exec -it deploy/xxl-job-executor -n xxl-job -- \ grep -r jobLogId /data/applogs/xxl-job/jobhandler/2025-01-01/长期方案是接日志采集把/data/applogs这个目录用 sidecar 或 DaemonSet 采集到集中存储。注意 XXL-JOB 的日志按日期分目录、按 jobLogId 分文件采集时保留目录结构否则检索时对不上调度记录里的日志 ID。我习惯在任务里用XxlJobHelper.log()输出关键上下文这样日志文件里既有业务输出也有框架的调度信息排查时不用两头翻。从那以后我每次部署 XXL-JOB 到新集群都强制走一遍「MySQL ready → admin 起来 → executor 注册 → 跑一个 demo 任务」这四步不跳步。这套 YAML 省掉的是写配置的时间省不掉的是对依赖顺序和注册链路的理解。希望帮到你。本文还有配套的精品资源点击获取