systemd timer OnCalendar 如何避免重复触发

systemd timer 的 OnCalendar= 看起来“重复触发”，通常不是 systemd 把同一个时间执行了两遍，而是配置里存在多个命中入口：同一个 timer 写了重叠的日历表达式，两个 timer 指向同一个 service，或者 Persistent=true 在 timer 停止期间补跑了一次。先把 timer 和 service 的对应关系查清，再决定是否需要补偿执行，问题一般就能收敛。

最稳妥的做法是：一个任务保留一个明确的 OnCalendar 规则，显式指定 Unit；不需要关机补偿时使用 Persistent=false，并用 list-timers、systemd-analyze calendar 和 journalctl 交叉确认。

三个先记住的判断：多个 OnCalendar= 是“任一规则到点就触发”；AccuracySec= 只控制允许的时间窗口，不负责去重；Persistent=true 可能让刚恢复的 timer 立即补跑错过的日历事件。

先把重复现象拆成几个触发入口

排查时先不要急着改时间表达式。用 systemctl list-timers --all 看是否有两个不同的 timer 都指向同一个服务，再用 systemctl cat 分别查看它们的 [Timer] 段。一个常见误区是把两条需求写进同一个 timer：

[Timer]
# 两个日历规则是两个可能的触发入口，不是同一条规则的注释说明
OnCalendar=*-*-* 02:30:00
OnCalendar=Mon *-*-* 02:30:00
Unit=report.service

上面的周一 02:30 同时满足两条表达式。更容易维护的写法是只保留能表达业务意图的一条规则；如果确实需要不同时间，先确认它们不会在同一时刻重叠，并把每次触发记录到同一个可检索的日志字段中。

把 OnCalendar 和 Persistent 的职责分开

OnCalendar= 使用墙上时钟的日历表达式；它可以写星期、日期、时间和时区。systemd 官方手册还规定，多个 OnCalendar= 会在任意一个表达式到期时触发。先用单独的 timer 文件表达一个任务：

[Unit]
# 让 timer 的职责只指向这一个报表服务
Description=Daily report timer

[Timer]
# 每天 02:30 触发一次，按本机日历解析
OnCalendar=*-*-* 02:30:00
# 不需要关机后的补跑时，明确关闭持久化补偿
Persistent=false
# 允许 systemd 在小窗口内安排，不把它当成去重开关
AccuracySec=1min
Unit=report.service

[Install]
# 让 timer 随 timers.target 启动
WantedBy=timers.target

Persistent=false 是“不要因为离线期间错过时间而补跑”，并不等于禁止同一时刻的重复配置。如果业务要求“机器关机后恢复也必须补一次”，可以改成 true，但要把恢复后的那次执行视为设计内的补偿，而不是异常重复。不要用 AccuracySec= 代替去重，也不要在同一任务上同时保留多个旧 timer。

用三组证据确认是否真的重复

修改 unit 后执行一次重新加载，再分别看表达式、timer 状态和日志。命令本身只作为排障示例，输出需要以你的主机为准：

# 解析表达式，先确认它实际命中的下一次时间
systemd-analyze calendar '*-*-* 02:30:00'

# 重新读取 unit 文件，并只启用目标 timer
sudo systemctl daemon-reload
sudo systemctl enable --now report.timer

# 查看同一 service 是否被多个 timer 关联
systemctl list-timers --all
systemctl show report.timer -p Unit -p NextElapseUSecRealtime -p LastTriggerUSec

# 将 timer 触发记录与 service 自身日志分开观察
journalctl -u report.timer --since today
journalctl -u report.service --since today

第一条命令回答“表达式会在什么时候命中”；list-timers 和 show 回答“当前到底有哪些 timer、上次和下次分别是什么”；两组 journal 则帮助区分是 timer 真的发起了两次激活，还是 service 内部重试、脚本重复写日志。

把防重复检查写进发布清单

每次调整定时任务后，至少复查四件事：第一，目标 service 是否只有一个预期的 timer 关联；第二，所有 OnCalendar= 是否真的互斥或已经合并为一条；第三，Persistent= 的取值是否符合业务，而不是为了“保险”随手打开；第四，service 日志中的一次业务批次是否有唯一标识。

如果日志显示 timer 只触发一次、service 却出现两条业务记录，问题已经越过 OnCalendar，应继续查脚本重试、队列消费或应用层幂等。反过来，如果 timer 日志本身出现两次，就回到 unit 列表和表达式重叠处，不要先改业务代码。

相关问题

Persistent=true 会每次启动都执行吗？不会。它用于 timer 非活动期间错过日历事件时补触发；是否补跑取决于停用期间是否确实错过了匹配时间。

AccuracySec 调小能解决重复吗？不能。它影响 timer 在目标时间附近的调度精度；重复入口、补偿策略和 service 自身行为仍需分别检查。

总结

systemd timer 的去重关键不是把时间写得更复杂，而是收敛触发入口：一个任务对应清晰的日历规则和目标 service，明确 Persistent 的业务含义，再用表达式解析、timer 状态和 journal 三组证据复查。这样才能判断“重复”究竟发生在调度层，还是发生在服务内部。