用服务日志找出 Node.js 启动失败的原因

理解 Node.js 服务日志的来源,使用 journalctl 与 tail 查看日志,并排查启动失败的原因。

🎯 引言

Node.js 服务启动失败时,systemctl status 可以帮助我们判断服务是否正常运行,却不一定能直接说明失败的原因。例如,端口配置错误、启动文件不存在,都可能导致服务无法启动。

遇到这种情况,不必盲目修改配置。先查看日志,找到报错,再根据错误信息修复问题,通常更有效。

本篇继续使用前面创建的 linux-notes.service,学习如何使用 journalctl 查看服务日志、使用 tail 查看文件日志,并通过一次模拟故障,完成从定位原因到验证恢复的排查过程。


🧱 日志从哪里来

日志是程序运行时留下的记录,可以告诉我们服务何时启动、收到了哪些请求,以及出现了什么错误。

以之前创建的 Node.js 服务为例:当程序执行 console.log() 或 console.error() 时,会分别向标准输出和标准错误写入信息。这两个名称指的是程序输出信息的渠道,并不一定是磁盘上的文件。

当 Node.js 服务由 systemd 托管,并使用常见的默认日志配置时,这些输出通常会被 systemd 的日志系统(journald)收集。我们可以用 journalctl 查看。同时,systemd 自身产生的启动、停止、失败等记录,也可以通过它查看。

先访问一次健康检查接口,再查看服务的最近 20 条日志:

curl -i http://127.0.0.1:3000/health
sudo journalctl -u linux-notes.service -n 20 --no-pager

第二条命令中的参数分别表示:

  • -u linux-notes.service:只查看这个服务的日志。
  • -n 20:显示最近 20 条记录。
  • --no-pager:直接在终端输出,不进入翻页查看界面。

如果沿用前文会记录请求信息的示例程序,日志中应能找到类似内容:

下面是示例输出(时间、主机名、进程号会因环境不同而变化,并非在你的服务器上实际执行得到的结果):

Nov 12 14:10:03 ubuntu systemd[1]: Started linux-notes.service - Linux Notes API.
Nov 12 14:10:03 ubuntu node[2481]: Server listening on port 3000
Nov 12 14:10:15 ubuntu node[2481]: GET /health status=200

日志每行可以分成两部分来看:前面的 Nov 12 14:10:15 ubuntu node[2481] 表示时间、主机名、程序名和进程号;后面的 GET /health status=200 才是 Node.js 应用输出的请求记录。systemd[1] 开头的行则是 systemd 记录的服务启动事件。具体输出内容取决于前文示例程序实际打印了什么。

如果日志很多,可以缩小查看范围,例如只查看本次开机后、最近 10 分钟内的记录:

sudo journalctl -b -u linux-notes.service --since '10 minutes ago' --no-pager

这里的 -b 表示本次开机,--since 表示从指定时间开始查看。排查故障时,缩小时间范围能减少无关信息。


🛠 实时查看服务日志和文件日志

有时我们希望一边操作服务,一边观察它产生的新日志。此时可以使用 journalctl -f,其中 -f 表示持续等待并显示新增记录。

在连接 Ubuntu 实验机的第一个终端执行:

sudo journalctl -fu linux-notes.service

保持这个终端打开,再使用第二个终端发送请求:

curl -i http://127.0.0.1:3000/api/notes

返回第一个终端。如果示例程序仍然按前文方式记录请求,应能看到类似内容:

第一个终端可能新增下面这一行(示例输出):

Nov 12 14:12:08 ubuntu node[2481]: GET /api/notes status=200

新记录出现在终端底部,说明持续查看模式正在工作;其中 status=200 表示这次请求获得成功响应。若程序没有打印请求日志,就不会出现这行,需要检查前文是否已添加对应的日志代码。

这样就能直观看到:请求到达程序后,新日志会出现在正在查看的终端里。以后遇到请求异常,也可以用这种方式观察问题发生时的输出。

除了输出到终端,应用还可以主动把日志写入文件。如果你已经完成前面文件查看章节的练习,并创建了 app.log,可以执行:

tail -n 10 -f "$HOME/linux-lab/logs/app.log"

例如,假设文件中保存的是以下几行文本,终端最初可能显示:

2026-11-12 14:00:01 app started
2026-11-12 14:00:05 GET /health status=200
2026-11-12 14:00:08 GET /api/notes status=200

文件增加一行后,终端也会接着显示那一行。这里仅用于说明 tail -f 的显示方式,不代表前文的 app.log 一定有这些内容,也不表示访问 Node.js 接口一定会写入这个文件。

tail 用于查看文件末尾的内容,其中:

  • -n 10:先显示最后 10 行。
  • -f:继续等待并显示文件新增的内容。

两种工具的区别是:journalctl 查询日志系统收集的记录;tail 直接读取指定文件。它们并不是任何情况下都能看到完全相同的日志,应该根据日志实际存放的位置选择工具。

查看结束时,在对应终端按 Control + C 即可退出持续查看;这只会结束查看命令,不会停止 Node.js 服务。


🧰 根据日志排查启动失败

现在模拟一次真实问题:把服务端口改成无效值,让 Node.js 无法正常启动,再通过日志找到原因。

1. 制造端口配置错误

先打开前文创建的 systemd 服务配置文件:

sudo vim /etc/systemd/system/linux-notes.service

找到 [Service] 中的端口环境变量,将:

Environment=PORT=3000

临时改成:

Environment=PORT=70000

PORT 是传给 Node.js 程序的环境变量。端口号通常只能在 0 到 65535 之间,具体能否使用还取决于程序及系统的限制;这里设置为 70000,就是为了制造一个明显的无效端口。

保存文件后,让 systemd 重新读取配置,再重启服务:

sudo systemctl daemon-reload
sudo systemctl restart linux-notes.service

daemon-reload 的作用是让 systemd 重新读取修改过的服务单元文件;如果不执行,systemd 可能仍使用旧的单元配置。

2. 查看失败状态和错误日志

检查服务状态:

systemctl status linux-notes.service --no-pager

服务可能显示 failed,也可能短暂处于自动重启过程中。例如,status 的关键部分可能是下面这样(示例输出):

● linux-notes.service - Linux Notes API
     Loaded: loaded (/etc/systemd/system/linux-notes.service; enabled)
     Active: failed (Result: exit-code) since Thu 2026-11-12 14:15:04 CST
    Process: 2602 ExecStart=/usr/bin/node /home/ubuntu/linux-lab/app.js (code=exited, status=1/FAILURE)
   Main PID: 2602 (code=exited, status=1/FAILURE)

这里的 Active: failed 表示服务处于失败状态,status=1/FAILURE 表示启动进程以非零退出码结束。ExecStart 的路径仅是举例,以你之前实际配置的启动命令为准。状态告诉我们服务没有正常运行,但真正的原因要继续从日志中寻找。

先不要筛选关键字,直接查看最近 30 条日志:

sudo journalctl -u linux-notes.service -n 30 --no-pager

重点观察服务启动失败前后出现的错误信息。如果前文示例程序实现了端口范围校验,日志可能长这样(示例输出):

Nov 12 14:15:04 ubuntu systemd[1]: Starting linux-notes.service - Linux Notes API...
Nov 12 14:15:04 ubuntu node[2602]: PORT must be an integer from 1 to 65535
Nov 12 14:15:04 ubuntu systemd[1]: linux-notes.service: Main process exited, code=exited, status=1/FAILURE
Nov 12 14:15:04 ubuntu systemd[1]: linux-notes.service: Failed with result 'exit-code'.

看第二行:node[2602] 表示这条错误由 Node.js 程序输出;PORT must be ... 才是需要重点分析的报错。后两行是 systemd 记录的结果:进程退出,服务失败。

这段英文的意思是:PORT 必须是 1 到 65535 之间的整数。这里的具体报错文本取决于示例程序的校验代码,并不是 Node.js 固定输出的提示。 如果没有这样的自定义校验,也可能看到 Node.js 报出的无效端口错误。

无论错误文字是哪一种,只要日志指向端口不合法,再回头检查刚才修改的 Environment=PORT=70000,就能定位原因。

已经知道关键字后,还可以筛选日志,例如:

sudo journalctl -u linux-notes.service -n 30 --no-pager | grep -i 'port'

grep -i 'port' 用来查找包含 port 的行,并忽略字母大小写。实际排查时,应先阅读完整错误信息,再根据看到的内容决定搜索什么,不能假设所有问题都包含固定关键字。

3. 修复配置并验证恢复

重新编辑服务文件,将端口改回:

Environment=PORT=3000

然后重新加载配置并启动服务:

sudo systemctl daemon-reload
sudo systemctl restart linux-notes.service
systemctl status linux-notes.service --no-pager
curl -i http://127.0.0.1:3000/health

检查两个结果:

  1. systemctl status 显示服务正常运行,例如 Active: active (running)。
  2. /health 接口返回 HTTP 200,说明服务确实能够响应请求。

健康检查的终端输出可以参考下面的示例(响应体取决于前文的接口实现):

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"status":"ok"}

200 OK 是这一步最重要的验收信号,不要求响应头和响应体与示例完全相同。

如果 systemd 因短时间内多次启动失败而触发了启动限制,可以先执行:

sudo systemctl reset-failed linux-notes.service
sudo systemctl restart linux-notes.service

reset-failed 用于清除记录的失败状态及相关启动限速计数;它不是每次修复服务都必须执行的命令,也不能代替修正真正的配置错误。

到这里,我们就完成了一个完整的排查过程:发现服务异常 → 查看日志 → 找到错误配置 → 修复 → 验证服务恢复。


🧱 日志排查的注意事项

排查时不要只搜索 ERROR。不同程序的错误格式并不相同,例如端口占用可能出现 EADDRINUSE,权限问题可能出现 Permission denied。先看故障发生时间附近的完整日志,再根据实际内容缩小范围,更不容易遗漏关键线索。

另外,写入文件的日志会持续占用磁盘空间,长期运行的服务需要考虑日志保留和清理。普通文件日志可以由 logrotate 等工具管理;systemd 的 journal 有自己的存储与保留机制。本篇只需了解这一点,日志容量与轮转策略可以在后续运维内容中进一步学习。


❓ 知识问答

Q1:为什么 Node.js 已经启动失败,还能在 journalctl 中看到日志?

因为 systemd 除了收集应用输出,也会记录服务启动和退出等事件。即使应用没能正常提供接口,仍可能留下错误信息。若应用根本没有成功运行,则可能主要看到 systemd 自身的错误记录。

Q2:journalctl 和 tail -f 应该用哪个?

如果 Node.js 由 systemd 托管、输出被日志系统收集,就用 journalctl;如果需要查看应用自行写入的日志文件,就用 tail -f。首先确认日志写到了哪里。


🧪 小练习

本篇练习分为两步:

  1. 观察正常请求:使用 journalctl -fu linux-notes.service 持续查看日志,然后分别访问 /api/notes 和 /missing。在示例程序记录请求状态码的前提下,找到对应的 200 和 404 记录。
  2. 独立排查故障:再次把服务的 PORT 改为 70000,观察启动失败后的状态与日志。不直接搜索预设错误文字,而是先从完整日志中找出端口错误,再改回 3000,确认服务状态正常且 /health 返回 200。

验收标准: 能说明哪条日志由应用输出、哪类记录来自 systemd,并能根据错误信息找到需要修改的配置,而不是只记住操作命令。


🎉 恭喜你!现在你已经能够查看 Node.js 服务日志,并根据错误信息定位启动失败的原因,完成修复和验证。