Linux 用 systemd timer 替代定时任务的迁移

把 cron 迁到 systemd timer，关键不是把一行表达式原样搬家，而是把“执行什么”和“什么时候执行”拆成两个单元：.service 负责一次任务，.timer 负责日历触发。迁移后用 systemctl list-timers 看下一次触发，用 journalctl 看服务结果，排查会比只盯着 cron 邮件更直接。

官方文档：https://www.freedesktop.org/software/systemd/man/latest/

最稳妥的迁移顺序是先建立同名的 service/timer 对，再用 OnCalendar 写时间、用 Persistent=yes 处理关机错过的日历任务，确认日志正常后再删除旧 cron 行。

先把 cron 的一行拆成两个单元

假设旧任务每天凌晨两点半执行 /usr/local/bin/report-clean。先创建服务文件，服务只描述一次执行，不承载调度规则：

# 一次执行单元：只说明任务本身，不写每天几点运行
[Unit]
Description=清理报表临时文件

[Service]
# oneshot 适合执行完就退出的脚本
Type=oneshot
ExecStart=/usr/local/bin/report-clean

再创建同名的 timer 文件。默认情况下，report-clean.timer 会激活同名的 report-clean.service，所以这里不必额外填写 Unit=：

# 调度单元：只说明何时激活 report-clean.service
[Unit]
Description=按日清理报表临时文件

[Timer]
# 日历表达式替代 cron 的“分 时 日 月 周”字段
OnCalendar=*-*-* 02:30:00
# 关机期间错过的日历触发，在重新启动后补一次
Persistent=yes

[Install]
# enable 时加入系统定时器目标
WantedBy=timers.target

保存后让 systemd 重新读取单元，再启用 timer：

# 让 systemd 读取新增或修改过的单元文件
sudo systemctl daemon-reload
# 开机启用并立即启动 timer，service 会在触发时才运行
sudo systemctl enable --now report-clean.timer

OnCalendar 和 Persistent 分别解决什么

OnCalendar= 使用墙上时钟的日历表达式，例如 Mon..Fri *-*-* 09:00:00 表示工作日九点。它可以重复出现，也可以和相对启动时间的定时项组合。迁移前可先让 systemd 解析表达式，减少星期和日期写错的情况：

# 只解析日历表达式，观察下一次匹配时间；不执行目标服务
systemd-analyze calendar 'Mon..Fri *-*-* 09:00:00'

Persistent=yes 只对 OnCalendar 有效。systemd 会把上次触发时间保存到磁盘；如果 timer 停用或机器关机期间本来应该触发过，重新激活时会立即补一次。它不是“把错过的每一分钟全部补齐”，也不保证脚本本身一定成功，补跑仍受服务失败和其他 timer 配置影响。

用两个入口判断迁移是否真的生效

先看 timer 是否被 systemd 接管，以及下一次和上一次触发时间：

# --all 也显示没有被激活的 timer，便于发现拼写或 enable 遗漏
systemctl list-timers --all | grep report-clean
# 看 timer 的加载状态、触发时间和关联服务
systemctl status report-clean.timer

如果能看到下一次触发时间，说明调度单元已被加载；但这不能证明脚本成功。服务结果要到 journal 中确认：

# 只查看该服务最近的日志，避免被整机日志淹没
journalctl -u report-clean.service -n 50 --no-pager
# 迁移排错时同时查看单元最终内容，确认没有读错文件
systemctl cat report-clean.service

观察时把两个问题分开：list-timers 负责回答“何时触发”，journalctl 负责回答“触发后做了什么”。若 timer 有下一次时间但日志显示退出失败，应修复脚本权限、工作目录或环境变量，而不是反复修改 OnCalendar。

切换窗口与回退方式

生产迁移时不要让 cron 和 timer 长期同时运行，否则同一个任务可能执行两次。可以先部署但不启动 timer，在切换窗口停掉旧 cron 后执行 enable --now，随后观察一次服务日志。需要回退时，停用 timer 即可，service 文件可以保留供人工执行：

# 回退只停止调度，不删除服务定义，便于再次启用或手工运行
sudo systemctl disable --now report-clean.timer
# 确认旧 cron 仍按计划恢复前，再决定是否删除旧配置

最后可以用这张清单收尾：service 能单独描述一次成功执行；timer 的名字和关联服务明确；OnCalendar 已按目标时区理解；Persistent 的补跑预期已写进运维说明；list-timers 能看到下一次触发；journalctl 能定位服务退出结果。

常见迁移疑问

为什么 timer 显示 active，但脚本没有按时执行？

active 只代表 timer 正在等待触发。先看 list-timers 的 NEXT，再看服务单元的 journal；如果服务已经被触发，问题通常在脚本自身或运行用户环境。

Persistent=yes 会不会重复执行任务？

它用于处理 timer 不活动期间错过的日历触发，重点是补一次，而不是把所有错过的周期逐个重放。对不可重复执行的任务，仍应在脚本内部做好幂等。