升级Node.js 23后Gremlin连接Amazon Neptune出现网络错误

问题根源 #

Node.js 23内置的undici库（处理HTTP/WebSocket请求的核心依赖）对WebSocket握手的默认行为做了变更，不再自动适配Amazon Neptune要求的Gremlin子协议，导致握手时返回非101状态码，触发网络错误。

解决方案 #

1. 显式指定WebSocket子协议 #

修改DriverRemoteConnection的配置，添加Sec-WebSocket-Protocol请求头，指定值为gremlin-v3（Neptune要求的Gremlin WebSocket子协议）：

export function getGremlinTraversal() {
    if (!g) {
        const neptuneEndpoint = process.env.NEPTUNE_DB_ENDPOINT || '';
        const dc = new DriverRemoteConnection(neptuneEndpoint, { 
            rejectUnauthorized: false,
            headers: {
                'Sec-WebSocket-Protocol': 'gremlin-v3'
            }
        });
        const graph = new Graph();
        g = graph.traversal().withRemote(dc);
    }

    return g;
}

2. 升级Gremlin Driver到兼容版本 #

确保你的gremlin包是最新版本，新版本已经针对Node.js 23的undici变更做了适配：

npm update gremlin

如果更新后仍有问题，可以尝试锁定版本到3.7.2及以上（该版本开始优化了WebSocket握手逻辑）。

3. 调整WebSocket超时与负载配置（可选） #

如果握手超时或负载限制导致问题，可以添加undici的WebSocket专属配置：

const dc = new DriverRemoteConnection(neptuneEndpoint, { 
    rejectUnauthorized: false,
    headers: {
        'Sec-WebSocket-Protocol': 'gremlin-v3'
    },
    websocket: {
        handshakeTimeout: 10000, // 延长握手超时时间至10秒
        maxPayloadLength: 10485760 // 调整最大负载长度为10MB
    }
});

内容的提问来源于stack exchange，提问作者Niño Niel Iroc