2026-10-05 · DevOps · 约 7 分钟

用 systemd 托管自写服务:单元文件里的几个坑

自己写的小服务,最开始的启动方式往往是 nohup node app.js &,再配一个 screen。 能跑,但机器重启就没了,日志散落在终端里,出问题只能靠回忆。 迁到 systemd 之后,这些都能收敛成几个文件,代价是得弄明白单元文件里那些选项到底在做什么。

一、一个最小的可用单元

[Unit]
Description=my app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=app
WorkingDirectory=/opt/my-app
ExecStart=/usr/bin/node /opt/my-app/src/index.js
Restart=always
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now my-app
systemctl status my-app

这段配置已经覆盖了 90% 的日常需求:开机自启、崩溃重拉、停止时先发 SIGTERM 给程序自己收尾。

二、坑一:PATH 和绝对路径

systemd 启动服务时用的环境和你登录 shell 的环境不是一回事。 用 nvm、pyenv 装的运行时,经常出现「终端里能跑,服务里找不到命令」。

最省事的做法是 ExecStart 里写绝对路径,再显式补一个 PATH:

Environment=PATH=/home/app/.nvm/versions/node/v20.11.0/bin:/usr/local/bin:/usr/bin:/bin
Environment=HOME=/home/app
ExecStart=/home/app/.nvm/versions/node/v20.11.0/bin/node src/index.js

代价是运行时版本升级后要同步改这一行。如果不想改,可以写一个 start.sh, 在脚本里自己 source 版本管理器,但那样就多了一层间接,排错时要多看一个地方。

三、坑二:工作目录与相对路径

程序里所有 ./data、../config.json 都是相对当前工作目录的。 不写 WorkingDirectory 时,systemd 默认在 / 下启动,于是读配置直接失败。

建议总是显式写上,并且让程序内部尽量使用基于 __dirname / import.meta.url 的绝对路径——这样无论从哪个目录启动都不受影响。

四、坑三:重启策略与退出码

Restart=always 最省心,但要注意「配置错误导致的秒退」会变成重启风暴。 可以用启动频率限制兜底:

[Unit]
StartLimitIntervalSec=60
StartLimitBurst=10

[Service]
Restart=always
RestartSec=5

另一种做法是区分退出码:正常退出(例如执行完一次任务)用 OnSuccess=, 异常退出才重拉。对常驻服务来说差别不大,对定时任务差别很大。

五、坑四:优雅停止

默认 KillSignal=SIGTERM 是对的,但很多程序收到信号后并不会立刻退出, 而是在完成收尾。如果 TimeoutStopSec 太短,systemd 会直接 SIGKILL, 于是「重启后状态文件损坏」这类问题就出现了。

我的经验值:TimeoutStopSec=20 到 30,并且让程序在收到信号后 尽快释放锁、写完状态、关闭连接。如果程序需要几十秒才能停, 那多半是设计问题,而不是 systemd 的问题。

六、坑五:单实例锁

服务自己写 PID 锁文件时,进程被 SIGKILL 后锁文件会残留。 下次启动如果只判断「文件存不存在」,就会永远起不来。 正确的做法是读 PID 并检查进程是否还活着;判断不了时,再用「端口是否被占用」做二次确认。

if kill -0 "$(cat "$LOCK")" 2>/dev/null; then
    echo "already running"; exit 2
fi

顺带一提:既然 systemd 已经保证单实例,应用层的锁可以简化成「检测端口占用」, 让重复启动直接失败并返回一个明确的退出码。

七、日志去哪了

不配置 StandardOutput 时,stdout/stderr 会进 journald:

journalctl -u my-app -f
journalctl -u my-app --since today

如果程序自己写日志文件,就不要再把同样的内容复制进 journal,否则查问题时要在两个地方对照。 二选一,保持单一事实来源。

八、排错顺序

  1. systemctl status my-app 看退出码和最近几行日志;
  2. journalctl -u my-app -n 200 看完整上下文;
  3. systemd-analyze verify /etc/systemd/system/my-app.service 检查单元语法;
  4. 手动用同样的 User、WorkingDirectory 和环境跑一遍 ExecStart;
  5. 权限问题优先怀疑 User 与目录属主,而不是代码。

九、上线检查清单

systemd 不神秘,它只是把「进程管理」这件事的默认值定得比较严格。 把这些默认值理解清楚之后,自写服务的运维成本会明显下降——至少不用再半夜登录上去看 screen 还在不在了。

← 返回首页