systemd 服务启动失败排查：为什么手动执行正常，开机自启却报错？

很多人第一次踩 systemd 的坑，都会陷入一种很烦躁的状态：

• 在终端里手动执行，程序能跑
• 写进 systemd 以后，服务启动失败
• systemctl start 偶尔能过，重启机器后又挂
• 看起来像代码问题，实际上改了半天代码也没用

这类故障最容易把人带偏。因为你会天然觉得：

既然命令一样，手动能跑，systemd 也应该能跑。

但现实恰恰相反。

systemd 启动程序时，运行上下文和你在终端里手动执行，根本不是一回事。

一、先把根因想明白：systemd 不是你的 shell

你在终端里执行命令时，背后其实带着一整套"隐形加成"：

• 你当前所在目录是对的
• 你的 shell 已经加载了 ~/.bashrc、~/.zshrc 或其他 profile
• 你的 PATH 很可能已经被你改过
• 你是用自己的用户身份执行
• 某些环境变量早就被 export 过
• 这个时候网络、磁盘挂载、数据库等外部条件通常也已经准备好了

但 systemd 不会自动照抄你这套上下文。

它按 unit 文件定义的规则起服务。没写清楚的地方，它就按自己的默认逻辑来。

所以，"手动正常，systemd 报错"这件事，本质上不是玄学，而是：

你启动的不是同一个运行环境。

二、最常见的 7 个原因，基本都在这里

1. 环境变量和 PATH 不一样

这是第一大坑。

你手动执行时，Node、Python、Java、PHP 能找到，往往是因为你的 shell 已经帮你把路径准备好了。但 systemd 启动时，进程环境是按 unit 规则组装出来的，不会天然继承你交互式终端那套变量。

典型症状：

或者：

或者程序里直接报：

这不是代码突然坏了，而是 systemd 起服务时根本没拿到你手动执行时那套变量。

2. 工作目录不对，导致相对路径全废

很多程序写得很随意，默认认为当前目录就是项目目录：

• 相对路径读配置
• 相对路径写日志
• 相对路径加载证书
• 相对路径找 .env
• 相对路径找 dist/、public/、templates/

你在项目目录里手动执行当然没问题。 但 systemd 如果没设置 WorkingDirectory=，系统服务默认工作目录是 /。于是程序一启动，所有相对路径都失效。

常见报错：

或者：

这时候别急着怀疑文件丢了，先怀疑服务根本没在你以为的目录里跑。

3. ExecStart= 不是 shell，很多写法在 unit 里根本不成立

这个坑杀伤力特别大。

很多人把终端里能跑的命令，原样塞进 ExecStart=：

或者：

终端里能跑，不代表 unit 里能跑。因为 ExecStart= 默认不是交给 shell 解释的。

正确写法通常是两种：

第一种，尽量不用 shell，把事情拆清楚：

[Service]
WorkingDirectory=/opt/app
EnvironmentFile=/opt/app/.env
ExecStart=/usr/bin/python3 /opt/app/app.py

第二种，确实需要 shell 时，明确写：

[Service]
ExecStart=/bin/sh -c 'cd /opt/app && . /opt/app/.env && python3 app.py'

4. 执行用户不同，权限也就不同

你手动运行时，往往是自己的用户；systemd 跑服务时，可能是 root，也可能是 www-data、nobody、某个专门的服务用户。

于是马上就会出现这些差异：

• 能不能读项目目录
• 能不能写日志目录
• 能不能绑定端口
• 能不能访问用户家目录
• 能不能读 SSH key、证书、socket 文件

有时候你手动执行没问题，仅仅是因为你那个用户权限更高，或者正好能读那些文件；换成 unit 里配置的 User=，马上就暴露。

5. 启动时序不对：你手动执行时网络已经好了，开机阶段未必

这是"开机自启报错"最经典的锅。

你平时手动执行程序，通常是在系统已经启动完、网络已经连上、磁盘已经挂好、数据库也准备好了之后。

但开机自启阶段不一样。

所以这类症状很常见：

你以为是数据库抽风、Redis 抽风、第三方接口抽风。 实际上只是你的服务启动得太早了。

6. Type= 选错，systemd 对服务状态判断就会错

很多长驻进程写 unit 时，默认没写 Type=，systemd 一般按 Type=simple 处理。这意味着一种非常坑的现象：

• systemctl start myapp 显示好像成功了
• 但实际上程序可执行文件路径错了、用户不存在、准备阶段失败了
• 你随后只看到服务很快进入 failed

这时候，如果仍然用默认 simple，排查体验会比 Type=exec 差很多。

7. unit 文件改了，却没 daemon-reload

这个坑不复杂，但命中率极高。

你改了 /etc/systemd/system/myapp.service，保存了，重启服务，结果发现配置像没生效一样。

不是 systemd 瞎了，而是 unit 配置修改后，应该先执行：

sudo systemctl daemon-reload

三、真正有效的排查顺序，不要一上来就改代码

系统服务问题最怕乱猜。 下面这套顺序，基本能覆盖 90% 的实战场景。

第一步：先看 unit 当前状态

systemctl status myapp.service

先看三件事：

• Active 是什么状态
• Main PID 有没有起来
• 最后几行日志报的是什么

这一步不是为了找最终答案，而是先判断：它是没启动起来，还是启动后立刻退出，还是因为依赖问题被阻塞。

第二步：直接看 journal，不要只盯 status

journalctl -u myapp.service -n 100 --no-pager

实时看就用：

journalctl -u myapp.service -f

很多看似"神秘"的启动失败，日志里其实已经把锅点明了：

• executable 不存在
• 用户不存在
• 工作目录不存在
• 环境变量缺失
• 文件权限不足
• 网络未就绪
• 依赖服务没起来

第三步：把 unit 文件完整展开看一遍

systemctl cat myapp.service

重点核对：

• User=
• WorkingDirectory=
• Environment= / EnvironmentFile=
• ExecStart=
• After= / Wants=
• Restart=
• Type=

第四步：验证 unit 文件本身有没有语法或逻辑问题

systemd-analyze verify /etc/systemd/system/myapp.service

这一步能快速发现：

• 拼错的字段名
• 引号或语法问题
• 缺失依赖
• 某些逻辑不成立的配置

第五步：确认工作目录、执行文件、用户是否真实存在

这是最容易被忽略的一步。

直接查：

ls -ld /opt/myapp
ls -l /opt/myapp/bin/start.sh
id myapp

然后再核对 unit：

[Service]
User=myapp
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/bin/start.sh

只要这里有一个不存在，就足以让服务挂掉。

第六步：把"手动成功"的条件完整复刻出来，再对照 unit

很多人说"我手动执行正常"，但这句话本身往往不完整。

你最好把成功的手动条件写全：

cd /opt/myapp
export NODE_ENV=production
export DATABASE_URL=...
/usr/bin/node /opt/myapp/server.js

然后逐项对照 systemd：

• cd /opt/myapp 对应 WorkingDirectory=
• export ... 对应 Environment= 或 EnvironmentFile=
• /usr/bin/node ... 对应 ExecStart=
• 你用什么用户执行，对应 User=

第七步：怀疑启动时序时，优先查网络和依赖

如果错误和数据库、DNS、远端接口、挂载盘有关，先看 unit 是否写了这类依赖：

[Unit]
Wants=network-online.target
After=network-online.target

第八步：改完 unit 后，别忘了真正让 systemd 重新吃进去

标准动作是：

sudo systemctl daemon-reload
sudo systemctl restart myapp.service
sudo systemctl status myapp.service

四、一个非常典型的错误示例

很多人最初会这么写：

[Unit]
Description=My App

[Service]
User=myapp
ExecStart=cd /opt/myapp && source .env && npm start
Restart=always

[Install]
WantedBy=multi-user.target

这份配置的问题非常集中：

1. ExecStart= 不是 shell，cd、source、&& 这种写法不能按你终端里的理解直接工作
2. 没写 WorkingDirectory=
3. 没用 EnvironmentFile=
4. npm 路径也未必在 systemd 的执行环境里可见

更稳妥的写法通常是这样：

[Unit]
Description=My App
Wants=network-online.target
After=network-online.target

[Service]
Type=exec
User=myapp
WorkingDirectory=/opt/myapp
EnvironmentFile=/opt/myapp/.env
ExecStart=/usr/bin/node /opt/myapp/server.js
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

这里的思路很明确：

• 用 WorkingDirectory= 固定目录
• 用 EnvironmentFile= 明确加载变量
• 用绝对路径执行程序
• 用 Type=exec 提高启动错误可见性
• 用 network-online.target 处理严格网络依赖

五、再补一个高频误区：systemctl start 成功，不等于服务真的准备好了

这也是很多人会误判的地方。

默认 Type=simple 会在主进程 fork 出来后就认为服务已开始处理启动流程，甚至可能在目标二进制真正 execve() 之前就放行后续依赖；而 exec 会等到主服务二进制执行成功。

也就是说，"启动命令返回成功"并不天然代表"程序已稳定可用"。

这也是为什么很多服务看起来"能启动"，但立刻又 failed。 不是 systemd 反复横跳，而是你选的服务类型和程序行为不匹配。

六、给你一套能直接套用的排查命令

遇到"手动正常，systemd 报错"，先不要慌，按这组命令走：

systemctl status myapp.service
journalctl -u myapp.service -n 100 --no-pager
systemctl cat myapp.service
systemd-analyze verify /etc/systemd/system/myapp.service
sudo systemctl daemon-reload
sudo systemctl restart myapp.service
journalctl -u myapp.service -f

如果你怀疑目录或权限问题，再补这组：

ls -ld /opt/myapp
ls -l /opt/myapp/server.js
id myapp

如果你怀疑环境变量和路径问题，再核对：

[Service]
WorkingDirectory=/opt/myapp
EnvironmentFile=/opt/myapp/.env
ExecStart=/usr/bin/node /opt/myapp/server.js

这一整套比"盯着代码发呆"有效得多。

七、真正该记住的一句话

这类问题最核心的认知只有一句：

systemd 跑的是"你写给它的环境"，不是"你脑子里默认的环境"。

你在终端里手动启动时，很多条件是隐形成立的。 但 systemd 不会替你猜：

• 你想在哪个目录运行
• 你想用哪个用户运行
• 你依赖哪些环境变量
• 你是否需要 shell
• 你是否要等网络真正就绪
• 你是否改过 unit 却忘了 reload

只要这些东西没有写进 unit，或者写得不严谨，手动执行正常、systemd 失败，就是很自然的结果。

结语

systemd 服务启动失败，最容易让人误入歧途的地方就在于：

命令看起来一样，场景却完全不同。

你以为问题在程序，其实问题在启动方式。 你以为是代码 bug，其实是工作目录、环境变量、用户权限、启动顺序或 Type= 配错了。

所以以后再碰到这类故障，别再一句"systemd 抽风了"带过。

正确的判断应该是：

终端能跑，只能说明"在你的 shell 条件下能跑"；systemd 能不能跑，取决于你有没有把这些条件完整、明确、规范地写进 unit 文件。

这才是关键。