systemd.service StartLimit 怎样限制短时间重复重启

当一个 .service 进程启动后立即退出，Restart=always 或 Restart=on-failure 会让 systemd 继续尝试拉起它。若故障原因没有修好，服务就可能在很短时间内反复重启。解决办法是把启动频率限制写在服务单元的 [Unit] 区段：StartLimitIntervalSec= 定义观察区间，StartLimitBurst= 定义区间内允许的启动次数。

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

例如，StartLimitIntervalSec=60 与 StartLimitBurst=5 表示在 60 秒观察窗口内达到启动次数上限后，不再允许新的启动尝试。它统计的不只是 Restart 触发的动作，手动启动、定时器或 socket 触发的启动也会进入同一限流语义。

先分清两个 StartLimit 参数放在哪里

StartLimitIntervalSec= 和 StartLimitBurst= 是通用 unit 配置，应该放在 [Unit]；Restart=、RestartSec= 属于服务行为，放在 [Service]。把 StartLimit 写进 [Service]，容易造成“配置看起来存在但实际行为不符合预期”的排查错觉。

官方说明还指出，启动限流对所有启动方式生效，而不仅是 Restart=。因此，管理员手动执行 systemctl start 时，也可能遇到同一限制。

用一个最小服务单元限制快速重启

下面的示例假设服务程序出现异常时需要自动恢复，但不希望一分钟内无限拉起。限制值只是示例，应该依据服务的启动成本、依赖恢复时间和故障影响调整。

[Unit]
Description=Example worker with start rate limit
# 60 秒内最多允许 5 次启动尝试，避免故障进程密集重启。
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=simple
ExecStart=/usr/local/bin/example-worker
# 非正常退出时自动重启，但最终仍受上面的启动限流约束。
Restart=on-failure
# 给依赖服务和日志落盘留出短暂间隔，不能代替 StartLimit。
RestartSec=10s

[Install]
WantedBy=multi-user.target

这里的组合关系是：Restart=on-failure 提供自动恢复意图，RestartSec=10s 拉开尝试间隔，StartLimitIntervalSec=60 与 StartLimitBurst=5 提供总量上限。即使服务仍然每次都失败，systemd 也不会在观察区间内无限重试。

若服务只允许正常退出后保持停止，可以把 Restart=on-failure 换成更窄的策略；不要为了“看起来更可靠”一律使用 Restart=always。重启策略必须和程序的退出码、故障恢复方式相配合。

达到上限后，服务会发生什么

当 unit 在指定时间段内超过允许的启动次数，新的启动不会继续被接受；对于配置了 Restart= 的服务，自动重启尝试会停止。观察区间过去后，重启逻辑可以重新生效，管理员也可以在需要时手动启动服务。

这不是“把服务永久禁用”，也不是把应用错误吞掉。服务仍然可能处于 failed 状态，真正的退出原因要回到服务日志和状态信息中查找。限流只负责控制启动节奏，不能修复配置文件、权限、依赖不可用或程序崩溃。

# 重新读取 unit 文件，避免仍使用旧的配置内容。
sudo systemctl daemon-reload

# 查看服务状态和最近一段日志，判断是否触发了启动限流。
sudo systemctl status example-worker.service
sudo journalctl -u example-worker.service -n 80 --no-pager

# 需要人工恢复时，先清除 failed 状态及启动计数，再尝试启动。
sudo systemctl reset-failed example-worker.service
sudo systemctl start example-worker.service

systemctl reset-failed 会清空服务的失败状态和启动速率计数，适合故障已经处理完、需要立即重新尝试的场景。它不是解决故障的命令，也不应该被脚本无条件循环调用，否则会绕开限流保护。

为什么重启次数和想象的不一样

排查时不要只数日志中的“进程退出”行。systemd 的启动限流在条件检查之后执行，条件不满足而被跳过的激活不会计入速率限制。反过来，手动启动、定时器或 socket 发起的启动也可能计入，所以“我只配置了自动重启”并不代表计数只来自 Restart。

另一个容易忽略的边界是 unit 的生命周期。如果 unit 因为垃圾回收被卸载，相关的速率计数也会被清空；对于一直被引用、持续加载的服务，这个计数才会持续发挥作用。不要把一次状态输出中的次数直接当成跨所有生命周期的永久累计值。

实际检查可以围绕三组证据展开：

• 看 unit 文件：确认 StartLimit 参数确实位于 [Unit]，且没有被 drop-in 覆盖。
• 看服务状态：确认是否已经 failed、是否仍在等待下一次启动以及 Restart 策略是什么。
• 看时间线和触发者：区分 Restart、人工 start、timer 或 socket，避免把所有启动都归因于程序自身。

怎样选择区间和 Burst

限流值没有适合所有服务的固定答案，可以先按故障影响做一个保守起点：

如果使用 StartLimitIntervalSec=infinity，语义会变成限制总启动尝试，即使这些尝试分散在很长时间内也会受到影响。只有明确需要这种长期总量约束时才使用；普通故障恢复通常更适合有限观察区间。

常见问题

StartLimit 应该写在 [Unit] 还是 [Service]？

写在 [Unit]。它是通用 unit 的启动速率限制；Restart= 和 RestartSec= 才属于 [Service]。

StartLimitBurst=5 是每分钟最多重启五次吗？

更准确地说，是一个由 StartLimitIntervalSec= 定义的时间窗口中允许五次启动。它不仅覆盖自动重启，也可能覆盖手动、定时器或 socket 触发的启动。

修改 unit 文件后为什么限制没有变化？

先执行 systemctl daemon-reload 让 systemd 重新读取配置，再结合 drop-in、服务状态和日志检查实际生效的文件内容。不要只修改磁盘上的文件就直接推断运行时已经更新。

达到上限后怎样立即恢复？

先修复导致退出的真实原因，再按需执行 systemctl reset-failed 服务名 清理失败状态和启动计数，最后手动启动。无条件反复 reset-failed 会削弱限流的保护作用。

总结来看，StartLimitIntervalSec= 和 StartLimitBurst= 控制“单位时间允许多少次启动”，Restart= 控制“退出后是否继续尝试”，RestartSec= 控制“尝试之间等待多久”。把三者分开理解，才能既保留自动恢复，又避免故障服务在短时间内形成重启风暴。