systemd.service SuccessExitStatus 自定义正常退出码的配置方法

有些维护脚本会用非零退出码表示“任务已完成，但没有继续动作”，例如 42 表示“没有待处理对象”。如果 unit 没有额外配置，systemd 会把它当成失败；此时 Restart=on-failure 还可能反复拉起任务。处理这种场景的关键是给 unit 增加 SuccessExitStatus=42，把业务约定的退出码纳入成功集合。它不会修改程序实际返回值，只改变 systemd 对这次退出的分类。

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

SuccessExitStatus 先把退出码归类为成功

SuccessExitStatus=接受数值退出码，也接受 systemd 认识的信号或状态名称。多个值用空格分隔；它表达的是“哪些结果算正常结束”，不是“把错误吞掉”。例如，程序仍然会返回 42，日志也可能记录实际退出状态，但 unit 的结果会按成功处理。

这项配置适合有明确业务协议的退出码，不适合把所有非零值都写成成功。一个安全的边界是：先在脚本或程序中固定退出码含义，再只登记确实代表“无需重试”的值。真正的错误码仍应留在失败集合中，否则排障和监控都会失真。

Restart=on-failure 要和成功状态一起判断

Restart=on-failure的含义不是“只要退出码非零就重启”。它依赖 systemd 对退出原因的分类；被 SuccessExitStatus=声明为成功的结果，不再按失败触发这个策略。相反，未声明的异常退出、未处理信号或 watchdog 超时仍可能触发重启。

用 unit 配置固定语义并检查状态

下面的 unit 把 42 定义为“本轮没有工作”，并保留失败自动重启。示例只表达配置关系，不代表在本机执行过。

[Unit]
Description=批处理维护任务

[Service]
# 42 表示本轮没有待处理对象，按业务约定视为正常结束
SuccessExitStatus=42
# 真正失败时才尝试恢复；不要用 always 掩盖错误
Restart=on-failure
RestartSec=5s
# 示例程序必须自行返回约定的 42
ExecStart=/usr/local/bin/maintenance-job

改完文件后按下面顺序检查。命令中的注释说明每一步目的，不是日志输出：

# 让 systemd 重新读取 unit 文件
sudo systemctl daemon-reload
# 重新启动服务以使用新配置
sudo systemctl restart maintenance-job.service
# 查看最终状态、Result 和主进程退出状态
systemctl show maintenance-job.service -p ActiveState -p SubState -p Result -p ExecMainStatus
# 结合本次启动的日志确认退出原因
journalctl -u maintenance-job.service -b --no-pager

重点看三组信息：Result是否符合预期，ExecMainStatus是否仍保留程序的真实 42，以及服务是否因为未声明的错误继续重启。若修改后仍出现旧行为，先检查实际加载的 unit 路径和展开值，再怀疑程序本身。

常见问题与边界

SuccessExitStatus 会把程序的退出码改成 0 吗？

不会。它只改变 systemd 的结果分类，程序的退出码仍可通过 ExecMainStatus或日志观察。

SuccessExitStatus 和 RestartPreventExitStatus 应该怎么选？

前者定义哪些退出算成功，适合建立完整的业务语义；后者只阻止指定退出码触发重启。需要让状态也显示为成功时，优先明确配置 SuccessExitStatus。

为什么配置正确仍然反复重启？

常见原因是实际退出码不是 42、unit 没有重新加载，或触发了信号、watchdog、启动速率限制等另一条路径。用 systemctl show和 journalctl把退出状态与重启原因分开看。