systemd-analyze calendar 校验 OnCalendar 表达式的实用方法

写 systemd.timer 时，最容易被忽略的不是语法本身，而是“能解析”和“符合预期”是两回事。systemd-analyze calendar 会按照 OnCalendar= 使用的日历语法解析表达式，给出归一化形式，并计算下一次命中的时间；它不会替你加载 unit、启用 timer 或证明任务已经执行。

官方资料：https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html

部署前先把表达式单独交给 systemd-analyze calendar，重点看三项：解析是否成功、归一化后的规则是什么、下一次时间是否落在你想要的日期和时区。三项都对，再把相同文本放进 OnCalendar=。

先确认 systemd.timer 负责什么

OnCalendar= 描述的是一个或多个日历事件，星期、日期、时间和时区共同决定匹配条件。systemd-analyze calendar 使用同一套日历语法进行解析，所以它适合做配置文本的前置检查；但 timer 是否被加载、是否启用、是否在错过事件后补跑，属于另外的运行状态问题。

可以先把目标规则写成最小的 timer 片段。下面的注释只说明配置意图，不代表当前主机已经加载了这个 unit。

[Timer]
# 每周一到周五的 09:30 作为日历匹配条件
OnCalendar=Mon..Fri *-*-* 09:30:00
# 让 timer 在启动后按照当前日历规则重新计算下次时间
Persistent=no

这里真正需要校验的是 Mon..Fri *-*-* 09:30:00 这一段，而不是先把问题扩大到服务依赖或补跑策略。

用一条命令看归一化结果

把表达式作为一个完整参数传给命令。包含空格、星号或范围的表达式要用引号包住，避免被 shell 拆开或展开。

# 用引号保留完整的 OnCalendar 表达式
systemd-analyze calendar 'Mon..Fri *-*-* 09:30:00'

输出通常会同时呈现原始形式、归一化形式和下一次命中时间。审查时先看 Normalized form：它会把省略的字段、数字格式和星期范围整理成 systemd 实际理解的形式。比如你写的是工作日范围，归一化结果仍应保留星期范围，而不是悄悄变成每天。

Original form: Mon..Fri *-*-* 09:30:00
Normalized form: Mon..Fri *-*-* 09:30:00
Next elapse: ...

这一步的价值在于把“我以为它表示什么”变成“解析器把它解释成什么”。如果命令直接报解析错误，先修正表达式；如果能解析但归一化结果和预期不同，就不要继续部署。

用 --iterations 看下次触发时间

只看一次 Next elapse，有时看不出重复规则是否写对。使用 --iterations=5 可以查看接下来多个命中点，适合检查工作日、闰日、月末或带时区的表达式。官方说明中，这个选项用于显示指定数量的后续迭代，默认只显示下一次。

# 查看接下来五个命中点，便于发现星期或日期范围写错
systemd-analyze calendar --iterations=5 'Mon..Fri *-*-* 09:30:00'

如果要固定一个审查基准，可以额外指定 --base-time=，避免审查记录因当前时间变化而难以比较：

# 固定基准时间，比较规则在同一时间点之后的命中情况
systemd-analyze calendar --base-time='2026-10-22 08:00:00' --iterations=5 'Mon..Fri *-*-* 09:30:00'

遇到跨时区规则时，把时区明确写入表达式，例如 09:30 Asia/Shanghai，并观察归一化结果是否保留该时区。不要只根据本机显示的时间猜测部署目标机的解释。

把校验结果写进 timer 配置审查单

一个可复用的审查记录至少保留四列：原始表达式、归一化表达式、后续命中样本、部署边界。这样下一次修改 unit 时，能看出是表达式变化，还是 timer 启用和服务状态变化。

如果只是想验证 unit 文件本身是否能被 systemd 识别，还应把 unit 加载检查和日历表达式检查分开记录。这样当任务没有按时出现时，可以先回答“规则写错了吗”，再回答“timer 是否真的处于运行状态”。

常见疑问

为什么命令能解析，timer 还是没有执行？

因为命令只解析日历表达式并计算命中时间，不负责启用、激活 timer，也不检查关联 service 的执行结果。继续排查时应转向 unit 状态、依赖关系和服务日志。

为什么要看多个迭代，而不是只看下一次？

单次命中只能说明当前时间之后存在一个匹配点。查看多个迭代，才能发现星期范围、月日组合或时区写法在后续日期上是否偏离预期。

什么时候需要 --base-time？

当团队要在审查记录、变更单或迁移前后对比同一条规则时使用。固定基准时间后，后续命中点不会随着命令执行时刻变化。

把 systemd-analyze calendar 当成 OnCalendar 的语义探针：先看能否解析，再看归一化文本，最后用多次命中确认日期和时区。校验通过后仍要单独完成 timer 的加载、启用和服务执行检查，这样问题边界才不会混在一起。