systemd OnCalendar 处理带时区的定时任务

如果同一个 Linux 定时任务要在不同地区的服务器上都按“当地某个业务时刻”执行，关键不是给服务进程设置一个临时环境变量，而是把时区写进 OnCalendar= 的日历表达式。systemd 支持 UTC、本地时区和 IANA 时区数据库名称；没有显式时区时，表达式会使用当前时区。

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

下面用一个“每天欧洲中部时间 02:30 执行归档”的场景说明配置方法。文章中的图片是静态结构说明图，用于解释配置关系，不是浏览器、终端或实际运行截图。

先明确 OnCalendar 的墙上时钟语义

OnCalendar= 属于 realtime timer，它匹配的是日历上的日期和时间，而不是“服务启动后经过多少秒”。时间表达式没有写时区时，systemd 会按主机当前时区解释；主机迁移到另一个地区，或者运行时修改了时区，读者看到的“02:30”就可能不再代表原来的业务时刻。

跨主机部署时，建议把三个概念分开：

用匹配的 service 和 timer 固定业务时刻

timer 单元负责“何时触发”，service 单元负责“触发后做什么”。例如下面的服务只演示归档入口，实际生产环境应替换为自己的脚本，并为脚本设置绝对路径、权限和失败策略。

# /etc/systemd/system/report-archive.service
[Unit]
Description=归档报表文件

[Service]
Type=oneshot
# 使用绝对路径，避免 systemd 的工作目录与交互式 Shell 不同
ExecStart=/usr/local/bin/report-archive --format=tar --output=/srv/archive

接着在 timer 中把时区写在日历表达式末尾。Europe/Berlin 是 IANA 时区名，systemd 会依据系统时区数据库处理季节性偏移。

# /etc/systemd/system/report-archive.timer
[Unit]
Description=每天按欧洲中部时间归档报表

[Timer]
Unit=report-archive.service
# 每天 02:30，按 Europe/Berlin 的日历规则解释
OnCalendar=*-*-* 02:30:00 Europe/Berlin
# 机器关机错过时刻后，启动时补触发一次；按业务是否允许补偿决定
Persistent=true
# 允许系统在短时间窗口内合并唤醒，避免把它当成精确秒级闹钟
AccuracySec=1min

[Install]
WantedBy=timers.target

这里的 Persistent=true 是业务选择，不是时区配置的一部分。如果归档任务不能在开机后补跑，就应该删掉它或明确设计幂等逻辑。

先用 systemd-analyze calendar 解读表达式

不要只看配置文件里的字符串是否“像正确格式”。systemd-analyze calendar 可以解析日历表达式，并给出规范化形式和下一次匹配时间。检查时把它当作表达式解释器，而不是线上任务成功的证明。

# 解析表达式，并要求工具计算下一个匹配时刻
systemd-analyze calendar '*-*-* 02:30:00 Europe/Berlin'

# 列出本机可用的 IANA 时区名称，避免手写不存在的别名
timedatectl list-timezones | grep -E '^(Europe/Berlin|Asia/Shanghai)$'

如果表达式能被解析，输出会包含规范化的日历形式和下一次触发的时间描述。不同主机的显示时区可能不同，所以排查时要把“表达式采用的时区”和“输出显示的时区”分开阅读。

让已加载的 timer 与文件保持一致

编辑单元文件后，systemd 不会自动把新内容当成已加载配置。常用的切换顺序如下：

# 重新读取 /etc/systemd/system 下的单元文件
sudo systemctl daemon-reload

# 设置为开机启动，并立即启动 timer 单元
sudo systemctl enable --now report-archive.timer

# 查看已加载的下一次触发时刻、剩余时间和对应服务
systemctl list-timers --all report-archive.timer

# 需要排查单元状态时，查看 timer 自身的失败原因
systemctl status report-archive.timer --no-pager

list-timers 观察的是已加载的 timer 状态，不是对 OnCalendar 字符串的静态语法说明。修改表达式后，应同时确认 daemon-reload 已执行、timer 处于 active waiting，并且它指向了预期的 service。

规模化部署时的取舍与边界

在多地区环境中，显式时区能让配置表达业务规则，但仍有几个边界要提前写入运行手册：

• 夏令时跳过或重复时刻：某些当地时间在切换日可能不存在或出现两次，不要把这类时刻当成精确的一次性时间点；对关键结算任务应增加幂等键和业务侧去重。
• 时间同步：日历 timer 依赖 realtime clock。系统时间尚未同步时，下一次触发判断可能受影响；官方文档说明日历 timer 会与 time-sync.target 建立排序关系，但仍要确认发行版的时间同步服务实际可用。
• 精度与负载：AccuracySec 允许 systemd 在窗口内安排触发，不适合拿来代替秒级调度器。多台主机同时执行重任务时，可以结合随机延迟或业务队列分散负载。
• 长时间运行：如果目标 service 还在 active，timer 再次到点不会为它创建新的实例。重复触发的任务应设计为可重入或明确记录跳过原因。

把配置检查纳入上线后的改进

一套可维护的做法是把“业务时区”作为配置输入，生成或审核 timer 文件时禁止隐式使用主机时区；部署后再用 list-timers 检查下一次触发时间。这样能把问题拆成三层：表达式是否正确、单元是否加载、服务执行是否成功，避免把所有异常都归咎于时区。

如果团队有多个地区，可以为每个业务任务记录：业务时区、允许的触发窗口、是否允许错过后补跑、重复执行时的幂等策略，以及夏令时切换日的人工处置方式。配置的可读性和运行时观测同时存在，迁移主机时才不会依赖某台机器的隐含设置。

常见问题

OnCalendar 不写时区时按什么时区执行？

默认按当前时区解释。当前时区来自主机的系统设置，因此跨地区迁移时不要把未写时区的表达式当成固定业务规则。

应该写 UTC 还是写 Europe/Berlin 这样的 IANA 名称？

如果业务要求全球统一瞬时时刻，UTC 更直观；如果业务要求某个地区的当地时间，并希望自动跟随当地规则，使用 IANA 名称更合适。

为什么修改 timer 后 list-timers 还是旧时间？

通常先检查是否执行了 systemctl daemon-reload，再确认 timer 是否重新启动或已重新计算下一次触发时间；同时检查查看的是正确的 unit。