用 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,否则查问题时要在两个地方对照。 二选一,保持单一事实来源。
八、排错顺序
systemctl status my-app看退出码和最近几行日志;journalctl -u my-app -n 200看完整上下文;systemd-analyze verify /etc/systemd/system/my-app.service检查单元语法;- 手动用同样的
User、WorkingDirectory和环境跑一遍ExecStart; - 权限问题优先怀疑
User与目录属主,而不是代码。
九、上线检查清单
- 单元文件里没有相对路径,运行时用绝对路径;
WorkingDirectory明确,数据目录属主正确;Restart与启动频率限制配套;- 停止信号和超时时间与程序的实际收尾逻辑匹配;
- 日志只有一个来源;
- 重启机器后服务能自己回来(真机验证一次,不要只信
enable)。
systemd 不神秘,它只是把「进程管理」这件事的默认值定得比较严格。 把这些默认值理解清楚之后,自写服务的运维成本会明显下降——至少不用再半夜登录上去看 screen 还在不在了。