Linux 环境下 Node.js 故障排查实战指南
一 快速定位流程
- 明确症状：是进程崩溃、接口超时、端口访问不通、内存飙升还是 CPU 打满。
- 先看“最近发生什么”：应用日志、进程输出、系统日志，优先定位错误栈与时间点。
- 复现与最小化：在测试环境用相同输入/请求复现，剥离无关模块，缩小问题范围。
- 在线诊断与修复：必要时以调试模式运行，抓取堆快照/CPU 采样，验证修复后再上线。
二 日志与信息收集
- 应用日志
- 约定日志路径与级别，使用结构化日志库（如 winston、pino、morgan），便于检索与聚合。
- 实时查看：tail -f /path/to/app.log；按时间窗口检索：grep/awk/sed 组合过滤错误关键字（如 ERROR、Exception、timeout）。
- 进程管理日志
- 使用 PM2：pm2 logs、pm2 logs --lines 1000、pm2 logs --follow；pm2 monit 观察内存/CPU。
- 系统日志
- Ubuntu/Debian：tail -f /var/log/syslog；systemd 服务：journalctl -u service_name -f。
- CentOS/RHEL：journalctl -u service_name -f；必要时查看 /var/log/messages。
- 环境与配置
- 核对环境变量：printenv；配置文件：cat config.json；依赖一致性：npm list；必要时切换/升级 Node 版本（如使用 nvm）。
三 常见症状与排查要点
- 端口与访问
- 端口占用：lsof -i :3000 或 ss -ltnp | grep 3000，必要时 kill PID；服务未监听：netstat -tulpen | grep 3000。
- 防火墙放行：Ubuntu/Debian：ufw allow 3000/tcp；CentOS/RHEL：firewall-cmd --zone=public --add-port=3000/tcp --permanent && firewall-cmd --reload。
- 绑定地址错误：服务仅绑定 127.0.0.1 会导致外部不可达，改为 0.0.0.0（示例：server.listen(3000, ‘0.0.0.0’)）。
- 依赖与运行环境
- 版本不兼容：Node 与依赖包版本冲突，使用 nvm 管理版本，必要时回退/升级依赖。
- 本地/私有包解析失败：检查 .npmrc、registry 配置与网络连通性。
- 本地模块缺失：npm install；全局包权限问题避免滥用 sudo，优先修复 PATH 或使用 nvm 用户级安装。
- 资源与异常
- 内存泄漏/OOM：观察 RSS、堆使用持续增长；抓取堆快照分析（如 heapdump/Chrome DevTools）。
- 高 CPU：用 –inspect 采样，定位热点函数；结合日志中的慢请求与堆栈定位业务瓶颈。
- 外部依赖异常：第三方接口超时/返回异常码，增加熔断/重试/降级并记录请求链路标识。
四 监控与在线调试
- 进程与性能
- PM2：进程守护、日志聚合、启动/重启策略、资源监控（pm2 monit、pm2 top）。
- 系统级：top/htop、vmstat、iostat、free、df、nmon 观察 CPU、内存、I/O、磁盘空间。
- APM 与指标
- New Relic、Datadog 等 APM 提供调用链、错误追踪、慢事务分析；自建可用 Prometheus + Grafana（配合 prom-client 暴露指标）。
- 远程调试与性能分析
- 调试：node --inspect 或 --inspect-brk，Chrome 打开 chrome://inspect 进行断点/观察表达式。
- CPU/内存分析：使用 node --inspect 采集 CPU Profile；生成堆快照分析对象泄漏与保留路径。
五 最小复现与修复验证
- 复现脚本：用 curl/postman 或 autocannon 构造相同请求；记录请求 ID、时间戳、入参与响应。
- 缩小范围：注释中间件/路由，逐步启用；在本地/预发环境复现后再回到线上灰度。
- 回归验证：上线后持续观察 PM2 日志、系统日志、关键指标 至少 1–2 个业务周期，确认错误率、延迟与资源使用回归正常。