Linux systemd timer Persistent=true 补跑任务如何判断

我排查 systemd 定时任务时，最容易误判的一幕是：机器开机后服务马上跑了一次，就把它当成了“Persistent=true 补跑”。更稳妥的判断方式是先看配置，再对照 timer 的 NEXT、LAST 和服务日志。Persistent=true 只对配置了 OnCalendar= 的 timer 有效；它会把服务上次触发时间保存下来，timer 重新激活时如果已经错过至少一个日历触发点，才会触发一次补跑。

先看 OnCalendar：Persistent=true 到底判断什么

systemd 的官方说明把 Persistent 的语义限定在日历型 timer：它保存服务最近一次触发时间，timer 重新激活时检查这段停机或未激活期间是否至少错过一次 OnCalendar 事件。也就是说，OnCalendar=daily 配合 Persistent=true，适合处理“每天至少补一次”的任务；它不是任务队列，也不会把停机期间错过的每一天逐个补齐。

我会先用下面这张结构图确认三件事：timer 负责日历条件，Persistent 负责保存触发时间，Unit 指向真正执行工作的 service。三者没有连上时，后面的日志很难解释。

把 timer 和 service 写成可观察的最小组合

下面的例子把目标服务设为一次性任务，并让它记录一行带时间的日志。代码是配置示例，注释解释了判断所需的关键字段：

# /etc/systemd/system/report-refresh.service
[Unit]
Description=Refresh daily report

[Service]
Type=oneshot
# 用 logger 留下可检索的服务级证据；真实任务应替换为幂等脚本
ExecStart=/usr/bin/logger -t report-refresh "service triggered"

# /etc/systemd/system/report-refresh.timer
[Unit]
Description=Run the daily report refresh

[Timer]
# Persistent 只对 OnCalendar 日历表达式产生补跑语义
OnCalendar=*-*-* 02:30:00
Persistent=true
# 显式绑定目标，避免改名后误触发同名服务
Unit=report-refresh.service

[Install]
# enable --now 时让 systemd 在当前启动周期加载 timer
WantedBy=timers.target

这里的关键不是让服务“开机自动执行”，而是让 timer 在开机后恢复时能够比较保存的触发时间与下一次日历事件。服务本身不要再放到 multi-user.target 里直接启用，否则手工启动服务与 timer 补跑会混在一起。

list-timers 只能告诉你计划和上次触发

安装或修改 unit 后，先重新加载配置，再查看 timer：

# 重新读取 unit 文件，并只启动 timer，不直接启动 service
sudo systemctl daemon-reload
sudo systemctl enable --now report-refresh.timer

# 关注 NEXT、LAST、UNIT 和 ACTIVATES 四列
systemctl list-timers --all report-refresh.timer

NEXT 是下一次计划时间，LAST 是 timer 最近一次触发时间，UNIT 是 timer 名称，ACTIVATES 是它会启动的 service。开机后如果 LAST 很快出现，并不单独证明是补跑：可能是正常的日历触发、手工 systemctl start，也可能是其他 unit 触发了同一个 service。

用 show 和 journalctl 给“补跑”定性

我通常把配置属性和运行属性放在同一次排查里。systemctl show 更适合脚本读取，journalctl 则用来确认 service 的启动、退出和 logger 记录是否在同一时间段：

# 读取持久化开关、日历表达式和两类触发时间
systemctl show report-refresh.timer \
  --property=Persistent,TimersCalendar,LastTriggerUSec,NextElapseUSecRealtime

# 同时看 timer 与 service，避免只过滤其中一个 unit
journalctl -u report-refresh.timer -u report-refresh.service \
  --since "today" --no-pager

# 任务完成后再确认 service 的退出状态
systemctl show report-refresh.service \
  --property=Result,ExecMainStatus,ActiveState,InactiveState

判断可以按这个顺序落地：Persistent=true 且存在 TimersCalendar，说明配置具备补跑前提；timer 恢复时出现一次新的触发记录，说明发生了激活动作；service 的退出状态为成功，才说明这次补跑完成。若日志里出现 systemctl start 或人工操作记录，就要把它从补跑证据里剔除。

三个容易把结果看错的边界

第一，Persistent=true 只触发一次“至少错过一次”的补跑，不是按错过次数补执行；如果需要补齐每个业务日期，应在服务里维护业务游标。第二，持久化时间戳必须落在重启后仍存在的文件系统上，容器、临时根文件系统或清理流程可能让历史状态消失。第三，手工执行 systemctl start report-refresh.service 会改变服务日志，却不能证明 timer 做过补跑。

如果要重置这个 timer 的持久化时间戳，使用：

# 仅清理 timer 的持久化状态；清理前确认不会丢掉业务审计需要
sudo systemctl clean --what=state report-refresh.timer

# 清理后重新加载并启动 timer，观察新的 NEXT/LAST 状态
sudo systemctl daemon-reload
sudo systemctl start report-refresh.timer

生产任务还应给每次运行带上业务日期或幂等键。这样即使管理员手工重试、主机重启或 timer 因停机补跑，也不会因为同一个日期被处理两次而产生重复账单、重复通知或重复导入。

相关问题

Persistent=true 会把关机期间每天的任务都补一遍吗？

不会。它只判断是否至少错过一次日历触发，通常恢复后触发一次；逐日补齐需要业务程序自己记录日期。

为什么 LAST 有值但我看不到任务成功？

LAST 只表示 timer 触发过，service 可能失败。继续检查 service 的 Result、ExecMainStatus 和 journal。

OnBootSec 配 Persistent=true 能补跑吗？

不能按同一语义判断。官方文档明确 Persistent 的补跑效果只适用于包含 OnCalendar= 的 timer。

如何避免补跑导致重复处理？

让服务按业务日期、文件哈希或任务 ID 做幂等检查，不要把“timer 只触发一次”当成业务去重保证。