Linux systemd StartLimitBurst 如何限制失败重启频率

systemd 服务反复失败时，真正要限制的是“一个时间窗口内允许启动多少次”，而不是简单把 RestartSec 调大。StartLimitBurst 负责次数，StartLimitIntervalSec 负责窗口；两者通常放在服务的 [Unit] 段，并与 Restart=on-failure 配合。官方文档入口：https://github.com/systemd/systemd/tree/main/man。

RestartSec 和 StartLimitBurst 管的不是同一件事

我排查这类服务时，最先看的是参数职责有没有混在一起。RestartSec 是每次失败后的等待时间；StartLimitIntervalSec 和 StartLimitBurst 组成启动速率限制。前者决定“隔多久再试”，后两者决定“这一段时间最多允许试几次”。

例如下面的组合代表一个明确边界：服务失败后等待 5 秒，60 秒窗口内最多允许 4 次启动。它不是保证服务 60 秒只重启 4 次的业务 SLA，而是 systemd 对 unit 启动行为的保护阈值。

在 Unit 段设置失败重启频率

建议用 drop-in 覆盖服务配置，避免直接改发行版提供的 unit 文件。下面的例子只表达配置方式；服务名 demo-worker.service 需要换成自己的实际单元。

# 为目标服务创建可回滚的 drop-in 配置
sudo systemctl edit demo-worker.service

# 将以下内容写入 [Unit] 和 [Service] 对应段
[Unit]
# 60 秒窗口内最多允许 4 次启动
StartLimitIntervalSec=60s
StartLimitBurst=4

[Service]
# 仅在异常退出时重启，避免正常停止也进入重启循环
Restart=on-failure
# 每次失败后先等待 5 秒
RestartSec=5s

保存后让 systemd 重新读取 unit，再查看生效配置。StartLimitIntervalSec 和 StartLimitBurst 属于 unit 级设置，写进 [Service] 往往会导致配置位置不对或被忽略；配置后应以 systemctl cat 和 systemctl show 的结果为准。

# 重新加载 unit 文件并查看最终合并结果
sudo systemctl daemon-reload
systemctl cat demo-worker.service
systemctl show demo-worker.service -p Restart -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst

用 systemctl 和 journalctl 判断限制是否触发

只看“服务没起来”还不够。状态命令负责告诉你当前结果，日志负责说明失败原因，属性查询负责确认参数是否真的进入了最终 unit。常见的误区是把应用本身的退出错误，误判成 systemd 的启动限流。

# 查看当前状态、失败原因和最近日志
systemctl status demo-worker.service --no-pager
journalctl -u demo-worker.service -b --no-pager -n 80

# 只抽取便于比较的属性；输出是排查入口，不代表固定阈值
systemctl show demo-worker.service -p Result -p NRestarts -p ExecMainStatus -p StartLimitBurst

# 修复启动命令或依赖后，清理失败状态再手动启动
sudo systemctl reset-failed demo-worker.service
sudo systemctl start demo-worker.service

如果日志持续出现启动失败，同时状态中的重启次数增长，说明根因仍在；如果出现启动速率限制相关提示而不再尝试重启，则说明保护阈值参与了结果。手动启动也受同一启动速率限制影响，不能用连续执行 systemctl start 来“撞开”它。

参数边界：先修故障，再决定是否调整窗口

生产环境里，我更愿意先修正退出码、环境变量、权限、依赖服务和端口冲突，再调整窗口。若确实需要容忍短暂依赖抖动，可以适当增大 RestartSec 或 StartLimitBurst，但要同步观察启动日志和业务可用性；不要把限流设成无限，除非你已经有外部熔断和告警兜底。

常见问题

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

它是 unit 级启动速率设置，通常写在 [Unit] 段；Restart= 和 RestartSec= 写在 [Service] 段。

为什么手动 systemctl start 也可能被拒绝？

启动速率限制适用于 unit 的启动行为，不只覆盖 Restart= 自动重启。等待窗口过去，或修复后执行 reset-failed 再启动。

只增加 StartLimitBurst 就能解决服务反复失败吗？

不能。它只是允许更多次尝试，不能修复命令、权限、依赖或配置错误。先从 journalctl -u 找到失败原因，再决定是否调整容忍度。

判断 StartLimitBurst 是否合适，关键不是追求一个通用数字，而是把服务的失败原因、重启等待、统计窗口和恢复动作放在一起看。配置完成后用最终 unit、状态和日志复查，才能知道限制的是频率，还是只是把故障拖得更久。