xiaowei-system/skills/devops/hermes-debug/references/systemd-timer.md

Systemd Timer 模式（2026-05-30）

适用场景

需要定期执行的后台任务（备份、清理、统计），且需要无需 sudo。

对比 cron

	systemd timer	cron
sudo	不需要（用户级）	需要（系统级）
环境变量	默认完整用户环境	需要手动设置
状态查询	systemctl --user list-timers	crontab -l
随机延迟	RandomizedDelaySec= 防雪崩	手动加扰动
失败告警	可绑定到 service 的 OnFailure	无内置

标准模板：每日备份（zhiyi-backup）

zhiyi-backup.service

[Unit]
Description=ZhiYi Daily Backup
After=zhiyid.service
PartOf=zhiyid.service

[Service]
Type=oneshot
ExecStart=/usr/bin/curl -s -X POST http://localhost:7821/api/v1/admin/backup \
  -H "X-API-Key: zhiyi-dev-key-2026"
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

zhiyi-backup.timer

[Unit]
Description=ZhiYi Daily Backup Timer (3:00 AM)

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true
RandomizedDelaySec=30m

[Install]
WantedBy=timers.target

部署流程

# 1. 放 service 文件
mkdir -p ~/.config/systemd/user
cp zhiyi-backup.service ~/.config/systemd/user/
cp zhiyi-backup.timer ~/.config/systemd/user/

# 2. reload + enable + start
systemctl --user daemon-reload
systemctl --user enable --now zhiyi-backup.timer

# 3. 验证
systemctl --user list-timers
# 期望：Sun 2026-05-31 03:00:00 CST  24h 57min left   -  zhiyi-backup.timer   zhiyi-backup.service

# 4. 手动触发（测试用）
systemctl --user start zhiyi-backup.service

常用 timer 表达式

表达式	含义
*-*-* 03:00:00	每天 3:00 AM
*-*-01 00:00:00	每月 1 日
Mon *-*-* 09:00:00	每周一 9:00 AM
*-*-* *:0/15:0	每 15 分钟
*-*-* 03:00:00 + RandomizedDelaySec=30m	每天 3:00-3:30 随机

关键点

• Type=oneshot：Timer 触发一次，service 执行一次（不保持 running 状态）
• PartOf=xxx.service：停止 timer 时自动停止 service
• Persistent=true：服务停机期间错过的执行时间，在恢复后补执行
• RandomizedDelaySec：防多服务同时触发（雪崩）