Node.js日志中网络错误排查

Node.js 日志中网络错误排查手册

一 快速定位流程

• 查看应用日志：实时跟踪日志，优先检索关键错误关键字，如 ETIMEDOUT、ECONNREFUSED、ECONNRESET、ENOTFOUND、EADDRINUSE。示例：tail -f app.log | egrep 'ETIMEDOUT|ECONNREFUSED|ECONNRESET|ENOTFOUND|EADDRINUSE'。
• 查看系统日志：定位系统层面的网络异常与进程事件。示例：sudo tail -f /var/log/syslog；若使用 systemd 托管服务：journalctl -u your-nodejs-service -f。
• 验证网络连通与解析：
  • 连通性：ping -c 4 <host>；路由路径：traceroute <host> 或 mtr <host>。
  • DNS：nslookup <host> 或 dig <host>。
• 检查监听与端口占用：
  • 监听状态：netstat -tulpen | grep <port> 或 ss -ltnp | grep <port>。
  • 占用排查：lsof -iTCP:<port> -sTCP:LISTEN 或 ss -ltnp | grep <port>。
• 直连目标服务：用 curl -v http://<host>:<port>/health 或 nc -vz <host> <port> 验证端口与服务是否可达。
• 防火墙与安全组：核对本机与云侧策略是否放行相关端口与协议。
  以上步骤能在分钟级内把问题收敛到“应用配置/代码、系统网络、对端服务、DNS/防火墙”四大类之一。

二 常见错误与对应处置

三 深入排查工具与命令

• 系统与服务日志：journalctl -u your-nodejs-service -f、tail -f /var/log/syslog、/var/log/kern.log、/var/log/dmesg，用于发现服务崩溃、OOM、驱动/内核网络事件。
• 网络连通与路径：ping、traceroute、mtr 定位延迟与丢包节点；ip a、ip route、route -n 检查地址与默认网关。
• 端口与监听：netstat -tulpen、ss -ltnp、lsof -iTCP:<port> -sTCP:LISTEN 确认监听地址与占用进程。
• 防火墙与安全组：sudo ufw status、iptables -S、firewall-cmd --list-all 核对放行规则。
• 抓包与深度分析：sudo tcpdump -i <iface> -nn port <port> 或 sudo tcpdump -i any 'tcp[tcpflags] & (tcp-syn|tcp-rst) != 0'，必要时配合 Wireshark 分析重传、RST、零窗口等异常。
• 应用层调试：启动时加 --inspect 或 --inspect-brk，用 Chrome DevTools/VS Code 设置断点，复现错误并查看调用栈与网络面板。
  这些工具能系统化验证“链路—端口—进程—策略—抓包”五个层面，快速定位根因。

四 代码与配置层面的加固建议

• 统一日志与上下文：使用 Winston/Morgan/Pino 输出结构化日志，记录 host、port、url、method、statusCode、duration、retry、stack，便于检索与聚合分析。
• 正确监听地址：对外服务避免使用 127.0.0.1，改为 0.0.0.0；容器内确认端口映射与 Host 网络配置一致。
• 超时与重试：为客户端设置合理 connect/read/write timeout；对幂等场景加入 指数退避 + 抖动 重试；对 ECONNRESET/ETIMEDOUT 区分可重试与不可重试。
• 连接复用与健康检查：启用 HTTP Keep-Alive、合理设置 maxSockets；对上游做 主动健康检查 与熔断降级。
• 优雅停机：在进程退出前停止接收新请求，等待进行中请求完成，减少 ECONNRESET 与半开连接。
• 监控与告警：接入 Prometheus/Grafana 记录请求耗时、失败率、TCP 重传等指标；异常触发 告警。
  这些措施能显著降低网络类故障的发生率，并在问题发生时加速定位与恢复。