Node.js HTTP 服务现代化:undici、keep-alive 调优与连接层故障排查
Node 26 把内置 fetch/HTTP 客户端 Undici 升到 8.0.2,服务端 http 模块也在持续演进(HTTP upgrades with bodies 修复、writeHeader 移除)。生产事故里"超时、连接泄漏、偶发 502"这类问题九成出在连接层而不是业务代码。本文给一套服务间调用的客户端配置基线与服务端 keep-alive 参数手册,以及故障定位路径。
一、客户端:globalDispatcher 的正确姿势
默认 fetch 的连接池配置面向通用场景,服务间高 QPS 调用需要显式收紧:
// bootstrap.mjs(用 --import ./bootstrap.mjs server.mjs 注入)
import { setGlobalDispatcher, Agent, Client } from "undici";
setGlobalDispatcher(new Agent({
connections: 128, // 每 origin 最大连接数,默认仅 'auto'(≈核心数)
pipelining: 1, // 非幂等/有状态服务保持 1;纯幂等 GET 可调高
keepAliveTimeout: 30_000, // 客户端侧空闲保活
keepAliveMaxTimeout: 60_000,
bodyTimeout: 10_000, // 响应体传输超时——默认无,是最大隐患
headersTimeout: 5_000, // 响应头超时
connect: { timeout: 3_000 },
}));
三个默认值陷阱:
connections太小:高并发下请求排队在本地队列,表现为"服务没满但延迟飙升";bodyTimeout缺省:对端慢速吐 body 会长期占住连接,配合服务端超时不一致就是连接泄漏的经典配方;- 重试不是内置行为:fetch 失败不会自动重试,幂等 GET 的重试策略要自己写(带退避与上限)。
async function fetchWithRetry(url, { tries = 3, ms = 100 } = {}) {
for (let i = 0; i < tries; i++) {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(2_000) });
if (res.status < 500) return res;
} catch (e) { if (i === tries - 1) throw e; }
await new Promise((r) => setTimeout(r, ms * 2 ** i + Math.random() * 50));
}
throw new Error("unreachable");
}
二、服务端:keep-alive 参数语义地图
Node http.Server 的相关参数,含义常被混淆:
const server = http.createServer(app);
server.keepAliveTimeout = 61_000; // 空闲 keep-alive 连接保持时长
server.headersTimeout = 65_000; // 收到完整请求头上限(必须 > keepAliveTimeout)
server.requestTimeout = 30_000; // 整个请求(含 body)上限,Node 18+ 默认 300s
server.timeout = 0; // socket 空闲超时(设了会干扰 keep-alive)
与中间层的对齐规则:上游 LB/网关的空闲超时 < 本服务的 keepAliveTimeout。若 nginx keepalive_timeout 60s 而 Node keepAliveTimeout 更小,Node 先断、nginx 复用已死连接,日志里就是间歇性 502 connect reset。经验序列:LB 空闲超时 60s → Node keepAliveTimeout 61s → headersTimeout 65s(Node 官方文档同款建议)。
三、TIME_WAIT 与连接风暴
短连接风暴(客户端不用 keep-alive、或每请求新建 Agent)会在服务端堆积 TIME_WAIT/CLOSE_WAIT:
ss -s # 汇总:timewait 数量
ss -tan state time-wait | wc -l
netstat -s | grep -iE "listen|timeout" # 监听队列溢出计数(溢出一次数 +1)
处置顺序:先修客户端复用(一个 Agent 全局复用,别每请求 new),再考虑内核参数(tcp_tw_reuse、somaxconn/net.core.somaxconn 与 Node listen(backlog))。"调内核参数掩盖连接滥用"是反模式——先证明连接数合理。
四、故障定位:一次 502 的排查树
- 看是谁断的:nginx error log 里
upstream prematurely closed connection(上游先断)vsno live upstreams(健康检查全挂);Node 侧开clientError/connection事件计数; - 对齐超时链:入口网关 → Node server → 业务 handler → 下游 fetch,每一跳的超时与重试画成表,找"上游比下游短"的倒挂点;
- 连接层指标:undici 的
getGlobalDispatcher().stats(或 per-Agent stats)看 pending/connected/poolSize;Node server 的getConnections()采样; - 复现工具:
autocannon -c N -p 10 --connectionResetTimeout 0压 keep-alive 行为;用curl -v观察连接复用是否生效(Re-using existing connection)。
五、HTTP/2 与 gRPC 的取舍
Node 内置 http2 可用但没有内置 HTTP/2 server push 之外的完整治理面(流控、连接迁移靠库)。服务间要多路复用优先评估 gRPC(配合另一篇 Node x gRPC 实践);对外入口的 HTTP/2 交给 LB 终结是多数场景的最优解——Node http2 与 nginx 同时终结会引入双层流控复杂度。
一个实用细节:http.Server 处理 Upgrade(WebSocket)时,Node 26 修复了 "HTTP upgrades with bodies" 边界问题;自研 WS 握手代码里要校验 Connection: upgrade + Sec-WebSocket-Key 再消费 body,否则畸形请求会打穿解析器。
六、配置基线汇总(可直接抄)
| 位置 | 参数 | 建议值 | 理由 |
|---|---|---|---|
| undici Agent | connections | 64~256/origin | 匹配下游容量,防本地排队 |
| undici Agent | bodyTimeout / headersTimeout | 10s / 5s | 默认无上限是最大隐患 |
| undici Agent | pipelining | 1(幂等读可调高) | 有状态服务防乱序 |
| http.Server | keepAliveTimeout | LB空闲超时+1s | 防竞态断连 502 |
| http.Server | headersTimeout | keepAlive+4s | Node 文档建议 >keepAlive |
| http.Server | requestTimeout | 按业务 P99×3 | 默认 300s 对 API 过长 |
小结
Node HTTP 连接层的可靠性 = 超时链对齐(每一跳显式设置、上游比下游长)+ 连接复用(全局 Agent、客户端 keep-alive)+ 参数语义清楚(keepAliveTimeout/headersTimeout/requestTimeout 各管什么)。故障排查按"谁先断 → 对齐表 → 连接指标 → 复现工具"四步走。Undici 8 时代这些能力都在内置件里,缺的只是把它们当生产参数而不是默认值来对待。
评论(0)
登录 后参与评论。