1. 先说清楚DolphinScheduler里的“系统时间”到底有几种1.1 三个时间概念系统时间、调度时间、运行时间聊DolphinScheduler用系统时间这个话题以前得先把几个时间概念拆开。很多人一上来就在任务里执行date命令觉得拿到的那串时间就是“系统时间”然后拿去拼分区、做判断结果数据莫名其妙错位排查半天都找不到原因。实际上在调度场景里至少存在三个不同的时间操作系统时间就是DolphinScheduler部署所在服务器的本地时间date命令、datetime.now()拿到的都是它。它本身是“无辜”的但很多错误发生在你以为自己在用它其实真正起作用的是另外两个时间。调度时间也可以叫计划时间、定时时间来自工作流定义里的cron表达式。比如你设置了0 10 0 * * ?每天00:10触发那么每个流程实例对应的调度时间就是当天的00:10。这个时间在流程实例创建时就会被固定下来即使任务因为排队延迟到00:20才真正开始跑调度时间依然是00:10。运行时间任务进程真正开始执行的那一刻。它受到队列拥堵、资源等待、前置任务耗时等各种因素影响是不稳定的。DolphinScheduler的流程实例详情页里你通常能看到“计划时间”和“运行时间”两个字段对应上面说的调度时间和运行时间。这两个概念不搞清楚后面所有关于日期的配置都会出问题。1.2 为什么不能把“运行时间”当“业务时间”这句话是我最想强调的也是绝大多数“系统时间”问题的根源。拿离线数仓最常见的场景举例每天凌晨00:10跑前一天的数据数据表按天分区比如dt20240531。很多人图省事直接在Shell脚本里写$(date %Y%m%d)想着“我凌晨跑批那当前日期就是业务日期”。这个想法在00:10的时候勉强成立——因为在00:10到23:59之间date %Y%m%d确实等于当天日期。但问题在于批处理任务跑的不是当天数据是昨天的数据。你要的分区是dt20240531而date %Y%m%d在00:10拿到的却是20240601。这一下就差了一天而且不是偶发是天天错。如果你只处理昨天的数据那应该往前推一天也就是date -d -1 day %Y%m%d。很多任务就是这么写的其实也能跑通但缺点很明显一旦任务跨天执行、补数、或者手动重跑这个“往前推一天”的逻辑就会错乱。我再举个跨天执行的例子。假设某个工作流里有两个任务A任务处理完是23:59:50B任务紧接着在00:00:10才启动。如果两个任务都用shell里的date -d -1 day来算业务日期A任务可能在23:59算出的还是昨天B任务在00:00已经算成了今天两个任务引用的业务日期就不一致了最终落库的数据分区必然错位。这种问题非常隐蔽而且不是每次都能复现。所以正确做法是凡是跟业务日期、数据分区相关的一律用DolphinScheduler的内置时间参数不要依赖任务进程自己去取系统时间。内置参数在同一个流程实例里是固定的、一致的不管任务什么时候真正跑它代表的都是同一个调度时间点。2. 最常用的方案用内置时间参数替代任务内取时间2.1 biz.date、system.biz.date、biz.time 等参数解析DolphinScheduler提供了一套内置的时间参数可以直接写在任务的内容里调度器在把任务提交给执行器之前会把参数替换成实际值。这套参数的核心是围绕“业务日期”设计的理解这几个参数的含义基本就掌握了调度的日期用法。我整理了一张常用参数表以常用的2.x版本为例参数名含义格式化结果示例假设调度时间为2024-06-01 00:10${system.biz.date}业务日期默认为调度日期的前一天20240531${system.biz.curdate}调度日期当天20240601${system.biz.time}业务时间前一天精确到秒20240531235959${system.biz.curtime}调度时间的当天精确到秒20240601001000${biz.date}自定义业务日期早期版本常用与system.biz.date类似20240531${biz.time}自定义业务时间早期版本常用20240531235959这里有个关键的默认逻辑DolphinScheduler认为你的批处理任务通常要处理前一天的数据所以${system.biz.date}默认等于“调度时间减一天”。如果你不想用这个默认逻辑而是希望拿到当天日期就用${system.biz.curdate}。还有一点要提醒不同版本的DolphinScheduler对参数名的兼容性不完全一样有的版本同时支持biz.date和system.biz.date有的版本更推荐后者。我个人建议以当前部署版本的官方文档为准而且在正式环境使用前先在一个测试工作流里把参数打出来看一眼确认格式再写进生产任务。DolphinScheduler官网文档里对参数这一块其实写得很清楚能先把参数章节啃下来至少能躲掉一半的坑。2.2 在Shell、SQL、Python任务里的实际用法参数本身不区分任务类型它是字符串替换所以所有任务类型都可以用。下面给三个最常见的场景。Shell任务#!/bin/bash # 打印当前系统时间用于日志记录 echo 当前系统时间: $(date %Y-%m-%d %H:%M:%S) # 业务日期使用内置参数 echo 业务日期: ${system.biz.date} echo 当天日期: ${system.biz.curdate} # 基于业务日期做进一步计算比如取T-2 biz_date${system.biz.date} t2_date$(date -d $biz_date -1 days %Y%m%d) echo T-2日期: $t2_dateSQL任务比如Hive SQL、MySQL SQL-- 处理T-1数据dt是字符串分区 SELECT dt, SUM(amount) FROM ods_pay_record WHERE dt ${system.biz.date} GROUP BY dt;注意SQL里字符串型日期一定要加引号${system.biz.date}替换后是20240531这种裸数字不加引号会被当成整数或者直接语法报错。Python任务from datetime import datetime, timedelta # 打印系统时间用于日志 print(运行时间:, datetime.now().strftime(%Y-%m-%d %H:%M:%S)) # 业务日期直接用内置参数DolphinScheduler会替换 biz_date ${system.biz.date} print(业务日期:, biz_date) # 基于业务日期计算T-2 t2 (datetime.strptime(biz_date, %Y%m%d) - timedelta(days1)).strftime(%Y%m%d) print(T-2:, t2)2.3 日期格式参数${yyyyMMdd} 这种写法是什么除了上面这些固定的内置参数名DolphinScheduler还支持把日期格式化字符串直接写在参数里比如${yyyyMMdd}、${yyyy-MM-dd}、${yyyy/MM/dd}。运行时调度器会按流程实例的调度时间对当前时间做格式化替换成对应的日期值。这个特性的优势是灵活可以自由控制日期格式不用拿到yyyyMMdd再手工转格式。但要注意它代表的是任务运行时刻的时间跨天场景下可能出现和${system.biz.date}不一致的情况。所以我的使用原则是日志打印、文件名拼接、临时目录命名这类对日期精度要求不高的场景可以用${yyyyMMdd}一旦涉及数据分区仍然优先用${system.biz.date}系参数。2.4 需求T-2、月初、月末怎么办实际需求里不会只跑T-1经常遇到T-2、上周一、上个月月末这类时间点。内置参数只给了T-1和T-0更多偏移需要自己算。最稳妥的方式不是在参数里搞花活而是在任务里基于${system.biz.date}做日期运算。Shell里用date -d是最顺手的base${system.biz.date} # T-2 date -d $base -1 days %Y%m%d # 上个月最后一天 date -d $base -1 day %Y%m%d # 这个看场景不一定是月末 # 直接用第一条命令算上个月月末的话更通用的是取本月1号再减一天 first_day_of_this_month$(date -d $(date %Y%m)01 %Y%m%d) last_day_of_last_month$(date -d $first_day_of_this_month -1 day %Y%m%d)SQL里也可以做比如Hive里date_sub(${system.biz.date}, 2)MySQL里DATE_SUB(${system.biz.date}, INTERVAL 2 DAY)。不要自己去维护一套“系统时间减N天”的硬编码逻辑那样性能和可维护性都很差。3. 跨任务、跨节点的时间传递与踩坑3.1 上下游任务如何共享同一个业务时间一个完整的数据工作流通常有抽取、清洗、统计、导出好几个节点每个节点都要引用同一个业务日期。最简单、也最推荐的做法是每个节点都直接写${system.biz.date}不要“上游算好再传给下游”。因为DolphinScheduler的变量替换是基于流程实例上下文的同一个流程实例里所有节点拿到的${system.biz.date}天然相同不需要任何额外设计。之前见过有人让上游Shell节点把日期写到一个临时文件下游再读文件还有的用日志里打印日期然后手动复制到下游全局参数里都属于过度设计纯给自己增加故障点。临时文件路径出错、清理不及时、权限不对都会引发问题。同一个流程实例内直接引用内置参数是性价比最高的方案。如果确实需要在不同的流程实例之间传递业务日期——比如A工作流跑完B工作流要接着用A当天处理的日期——那就不能依赖内置参数了因为每个流程实例的调度时间不同内置参数值也不同。这种情况一般建议通过关联表记录处理状态下游查询上游的处理日期或者用DolphinScheduler的流程间依赖功能保证上游成功后再启动下游。3.2 节点参数传递的玩法与限制有些场景还是需要上游把动态计算结果传给下游的比如上游从配置表里读出一个日期下游要用这个日期。DolphinScheduler支持通过Shell节点输出特殊JSON来设置全局参数下游节点再用${变量名}引用。大致写法是这样#!/bin/bash target_date20240531 echo {\setGlobalVar\:{\targetDate\:\${target_date}\}}下游节点的SQL里可以直接写SELECT * FROM dws_daily_report WHERE dt ${targetDate};几个注意事项这段JSON最好单独输出不要混在大量业务日志里避免识别失败。变量作用域是当前流程实例下游节点只要在同一个流程里就能用但跨流程实例不行。如果下游节点引用了不存在的变量DolphinScheduler不会报错而是会把变量名原样留在SQL里导致SQL执行时报错排查时要从这里入手。不同版本的实现细节有差异用之前先看官网文档确认别拿生产环境试错。3.3 手动运行与补数时的日期选择逻辑这个坑我见得最多。手动运行一个工作流时DolphinScheduler没有可参考的cron调度时间它会以当前时间为基准计算内置参数。也就是说如果今天是2024-06-01手动运行后${system.biz.date}是20240531${system.biz.curdate}是20240601。补数场景更特殊。补数时你指定一个时间范围比如从2024-05-20到2024-05-25DolphinScheduler会按这个范围内的每一天分别生成一个流程实例每个实例的调度时间就是当天的某个固定点。此时内置参数的值会跟随补数日期变化。这里有个容易绕晕的点补数时选择“2024-05-20”这天流程实例的${system.biz.curdate}通常是20240520${system.biz.date}则是20240519。如果你的任务逻辑是“处理${system.biz.date}的数据”那么你补的是5月19日的数据不是5月20日。很多人在补数时会怀疑“我明明选的是20号为什么跑出来的分区是19号”其实就是没搞懂业务日期和调度日期的差值关系。所以我给团队定的规范是SQL里读取数据分区统一用${system.biz.date}写表分区也统一用${system.biz.date}。这样T-1任务、手动任务、补数任务的行为完全一致不用每次手动换算。4. 时区问题差8小时的坑排查思路和解决方案4.1 定时任务比预期晚8小时是怎么来的上一节聊的是任务内部参数这一节聊调度系统本身的时间。DolphinScheduler的cron调度、流程实例时间、日志时间全部依赖Java进程的默认时区。如果服务器时区设置成UTC而你的业务在UTC8北京时间那么cron表达式里写的每天00:10实际上会在UTC的00:10触发也就是北京时间的08:10。这就是差8小时问题最常见的来源。还有一种情况是服务器系统时区是对的但启动DolphinScheduler进程时环境变量TZ被设置成了UTC或者Docker容器没有继承宿主机的时区配置导致JVM拿到的时区是UTC。无论是哪种最终表现都是调度时间和预期偏差8小时或者前端页面显示的时间与日志时间不一致。4.2 检查与统一时区的实操步骤我在定位这种问题时按下面的顺序查基本一趟就能找到问题查看服务器系统时区执行date -R看输出里的时区偏移是0800还是0000。也可以用timedatectl看更详细的信息。查看DolphinScheduler进程所在的环境时区执行echo $TZ。如果是空通常说明依赖系统默认时区如果写的是UTC那就要改。如果有条件用jinfo pid查看JVM的user.timezone系统属性这是Java进程最终生效的时区。查看数据库时区MySQL里执行show variables like %time_zone%;确认system_time_zone和time_zone是否为08:00或CST。修改方式也一并列出来# 修改服务器系统时区 timedatectl set-timezone Asia/Shanghai # 在环境变量中强制指定时区追加到 /etc/profile export TZAsia/Shanghai # 切到DolphinScheduler的部署用户重读环境变量 source /etc/profile # 重启调度服务务必把Master、Worker等相关进程全部重启 sh bin/dolphinscheduler-daemon.sh stop master-server sh bin/dolphinscheduler-daemon.sh start master-server如果是Docker方式部署启动容器时建议挂载时区文件并设置TZ环境变量docker run -d \ -v /etc/localtime:/etc/localtime:ro \ -v /etc/timezone:/etc/timezone:ro \ -e TZAsia/Shanghai \ ...4.3 数据库与JDBC时区的影响DolphinScheduler的元数据表里有大量时间字段比如流程实例的开始时间、结束时间、cron管理。这些时间由应用层写入最终存储到MySQL里。如果MySQL的time_zone是SYSTEM而SYSTEM又指向UTC那么时间在写入和读取时可能会经过时区转换导致展示出来的时间偏差。对于自建MySQL最简单的方式是统一设置为08:00SET GLOBAL time_zone 08:00; SET time_zone 08:00;另外DolphinScheduler连接数据库的JDBC URL里尽量显式指定时区比如jdbc:mysql://127.0.0.1:3306/dolphinscheduler?serverTimezoneAsia/ShanghaiserverTimezone参数告诉MySQL驱动应用期望的时区避免驱动使用JVM默认时区产生偏移。改了配置后记得重启DolphinScheduler服务。4.4 修改了时区为什么不生效常见原因有三类。第一只改了系统时区没有重启DolphinScheduler进程。Java进程启动后会在内存里缓存默认时区光改系统设置对已运行进程无效。第二Docker容器内没有挂载时区文件只改了宿主机容器内部仍然是UTC。第三JDBC连接串里没加serverTimezone即使系统时区对了数据库驱动在解析时间戳时也可能产生偏移。这类问题排查起来很费时间我建议DolphinScheduler部署完成后第一件事就是统一机房内所有节点的时区包括操作系统、JVM、MySQL、JDBC连接串然后在测试环境手动跑一个简单的Shell任务把date -R和内置参数都打印出来确认无误后再接入生产调度。5. 常见问题与排查实录这部分把日常被问得最多的问题整理成速查表方便你遇到问题直接对号入座。问题现象可能原因解决建议定时任务总是比配置时间晚8小时运行服务器或JVM时区是UTC统一时区为Asia/Shanghai重启DolphinScheduler任务里用date命令拿到的日期跟业务分区对不上用了系统时间而不是调度时间参数改用${system.biz.date}上游和下游任务引用的日期不一致任务运行跨天且各自用date计算日期统一使用内置参数SQL里${system.biz.date}原样出现没有被替换参数名写错或当前版本不支持该参数写法检查参数名和版本差异测试节点打印确认补数时选择的日期跟跑出来的分区对不上没有区分调度日期和业务日期明确补数时${system.biz.curdate}和${system.biz.date}的含义手动运行工作流日期参数跟预期不一致手动运行没有cron调度时间以当前时间计算手动运行前先确认当前时间和内置参数规则修改时区后调度时间没变化服务没重启或Docker时区没挂载重启Master、Worker检查容器时区配置下游引用变量没被替换SQL直接报错上游没有成功输出setGlobalVar或变量名拼错检查上游日志确认JSON输出核对变量名最后再分享一个我个人踩过不少次坑后的固定习惯所有接入DolphinScheduler的数据任务必须在任务开头打印一行当前系统时间和业务日期比如Shell里加上echo [INFO] biz_date${system.biz.date}。不要嫌麻烦这行日志在排查日期错位问题的时候就是唯一的救命线索。出现异常时先看这行日志再对比数据分区的实际值问题定位往往几分钟就完成。调度系统的“时间”从来都不是只有一个搞清楚它代表的是系统时间、调度时间还是运行时间比死记硬背任何参数名都重要。以后遇到日期对不上的问题先别甩锅给服务器回到这个基础逻辑上问一遍自己答案基本就出来了。