Meteor 3.5 DDP 传输层切换指南从 SockJS 到 uWebSockets.js 的配置、架构与运维实践【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteorMeteor 3.5 起DDP 服务器引入了可插拔传输层pluggable DDP transport layer传输层只负责在客户端与服务器之间搬运 DDP 消息订阅、方法调用、RPCDDP 协议本身完全不变。本文基于v3-docs/docs/performance/ddp-transport.md结合 packages/ddp-server 的源码实现系统讲解sockjs与uws两种传输的选择依据、配置方式、底层架构、负载均衡与多进程部署注意事项以及如何验证当前生效的传输方式。DDP 与传输层理解可插拔设计的前提DDPDistributed Data Protocol是 Meteor 的核心通信协议承载着订阅发布、方法调用RPC等全部实时数据交互。Meteor 3.5 的可插拔设计将协议逻辑与物理承载通道解耦DDP 层协议不变包括sub/unsub、method/result、ping/pong等消息语义传输层仅负责把 DDP 帧在客户端与服务器之间搬运可以整体替换而应用代码无需任何改动。从源码看传输层被抽象为统一接口。在 packages/ddp-server/transports/index.js 中维护了一张传输注册表sockjs与uws都是实现相同setup(httpServer, pathPrefix, options)签名的传输工厂const TRANSPORTS { sockjs: createSockJSTransport, uws: createUwsTransport, };StreamServerpackages/ddp-server/stream_server.js在启动时调用getTransport()解析出传输并执行setup()随后把emitter上的connection事件统一交给_onConnection处理——后续的 DDP 会话、心跳、订阅逻辑与具体传输完全无关。两种可用传输sockjs 与 uws传输本质适用场景sockjs默认SockJS带 HTTP 长轮询回退需要最大化兼容性——客户端位于严格代理之后、移动网络可能中断 WebSocket、或不支持 WebSocket 的环境uwsµWebSockets.js——原生 WebSocket无轮询回退网络路径可控、所有客户端都能维持原生 WebSocket且追求更低延迟与更高消息吞吐⚠️官方警告默认传输sockjs对大多数应用是正确的选择。只有在实测确认 WebSocket 帧处理或轮询回退存在真实瓶颈且你能完全掌控部署环境以端到端验证 WebSocket 连通性时才切换到uws。什么时候选择sockjs面向公网的应用部分用户位于企业代理、强制门户captive portal或屏蔽 WebSocket 的网络之后移动端流量占比高WebSocket 偶发失败时需要自动回退到长轮询部署环境中 Meteor 前端没有支持 WebSocket 感知的负载均衡器。什么时候uws能带来收益已实测服务器 CPU 偏高且可归因于 SockJS 帧处理或 JavaScript 实现的 SockJS 开销在热重连场景移动端、实时看板中SockJS 握手带来了可感知的延迟能保证每个客户端都具备 WebSocket 连通性例如内部应用、可控部署或你接受被代理屏蔽的客户端无法连接你的负载均衡器NGINX、HAProxy、AWS ALB、Galaxy能可靠地把 HTTP 升级为 WebSocket。配置传输方式方式一环境变量DDP_TRANSPORT# 切换到 uws DDP_TRANSPORTuws meteor run # 显式指定默认值 sockjs DDP_TRANSPORTsockjs meteor run方式二settings.json{ packages: { ddp-server: { transport: uws } } }这会把Meteor.settings.packages[ddp-server].transport填充到服务器端DDP 服务器正是读取该值。当两者同时设置时环境变量优先于settings.json。遗留别名DISABLE_SOCKJSDISABLE_SOCKJS1作为DDP_TRANSPORTuws的向后兼容别名仍然被支持但已废弃deprecated。新部署应优先使用DDP_TRANSPORT因为它为未来新增传输后端留出了空间且在部署配置中更易读。传输解析的源码级优先级getTransport()的解析顺序在 packages/ddp-server/transports/index.js 中实现与文档描述一致Meteor.settings.packages[ddp-server].transport环境变量DDP_TRANSPORTDISABLE_SOCKJS存在时 →uws向后兼容以上皆无 → 默认sockjs。需要注意上述优先级顺序与环境变量优先于 settings.json并不矛盾——resolveTransportName()的检查顺序是settings 在前、环境变量在后但若settings.json中同时存在transport配置环境变量同样能覆盖它。实际语义是只要任一来源设置了非空值即生效官方文档明确环境变量优先级更高。若配置了不存在的传输名getTransport()会直接抛出Unknown DDP transport错误transports/index.js。另外getTransport()会把解析结果写入__meteor_runtime_config__.DDP_TRANSPORTtransports/index.js让客户端知道该加载 SockJS 客户端还是使用原生 WebSocket。客户端如何感知传输类型传输选择并不只发生在服务器端。客户端通过__meteor_runtime_config__.DDP_TRANSPORT决定连接策略见 packages/socket-stream-client/browser.jsconst transport __meteor_runtime_config__.DDP_TRANSPORT || sockjs; if (transport sockjs) { this.socket new SockJS(toSockjsUrl(this.rawUrl), undefined, options); } else { // 所有非 SockJS 传输在客户端使用原生 WebSocket this.socket new WebSocket(toWebsocketUrl(this.rawUrl)); }这正是文档所述切换传输无需改动应用代码的机制服务器解析出uws后客户端自动改用原生 WebSocket 直连 DDP 端点使用sockjs时客户端走 SockJS 协议含轮询回退。browser.js还通过_sockjsProtocolsWhitelist()保留了对DISABLE_WEBSOCKETS的处理——该环境变量会从候选协议中剔除websocket强制回退到轮询。uws传输的架构双监听 Socket 与本地 TCP 代理uws与sockjs最本质的架构差异在于sockjs与 Meteor 已绑定的公共 HTTP 端口共用同一个http.Server实例作为 Connect 风格中间件存在见 packages/ddp-server/transports/sockjs.js 的installHandlers。uws在独立的内部端口默认127.0.0.1:5001上运行第二个监听 Socket。公共 HTTP 服务器上到达的 WebSocket 升级请求通过一条本地 TCP 连接被代理到该内部 Socket。该架构由 packages/ddp-server/transports/uws.js 中的proxyWebsocketToUws()实现拦截公共httpServer的upgrade事件若路径匹配pathPrefix /websocket则用net.createConnection(uwsPort, uwsHost)建立到内部 uWS 服务器的 TCP 连接将原始 HTTP 升级请求原样转发给 uWS并把客户端 socket 与 uWS socket 双向pipe若内部 uWS 服务器不可达向客户端返回502 Bad Gateway非/websocket路径的升级请求如 HMR继续交给原有 upgrade 监听器。同时uws.js通过WebApp.rawConnectHandlers.use拒绝了对/websocket的普通 HTTP 请求返回 400确保只有真正的 WebSocket 升级请求才能通过uws.js。正是这种公共端口保留 Meteor Connect 风格中间件 内部 uWS 原生处理 WebSocket I/O的双层设计让uWebSockets.js能以接近原生的速度处理 WebSocket而不牺牲 Meteor 公共端口上的中间件能力。运维考量负载均衡器配置uws不使用 HTTP 轮询。如果你的负载均衡器是按 SockJS 风格的粘性轮询配置的而不是 WebSocket 透传需要把配置切换为在 DDP 路径通常是/sockjs或自定义 DDP URL上把 HTTP 升级为 WebSocket禁用依赖 cookie 粘性的会话亲和session affinity——WebSocket 建立后没有 HTTP 请求来携带 cookie确保 WebSocket 空闲超时至少与 DDP 心跳间隔默认 35 秒一样长。与 WebSocket 压缩结合SERVER_WEBSOCKET_COMPRESSION设置对两种传输都适用。在 packages/ddp-server/stream_server.js 中压缩扩展通过permessage-deflate2配置默认threshold: 1024、Z_BEST_SPEED级别等并注入到 SockJS 的faye_server_options.extensions见 sockjs.js。如果你在 SockJS 下观察到了压缩开销同样的取舍在uws下依然成立——只是基线成本更低。详细说明见 WebSocket Compression。与 DDP 会话恢复Session Resumption结合Meteor 3.5 引入了 DDP 会话恢复当客户端在可配置的宽限期内重连时服务器恢复已有会话而非新建会话。已激活的订阅不会重新发布、在途方法调用会被重放连接保留其原始id。该特性与传输无关——sockjs和uws同等受益。启用与调优会话恢复默认开启。可以在服务器启动代码中调优两个参数import { Meteor } from meteor/meteor; // 让断开的会话存活 30 秒默认 15000 ms Meteor.server.options.disconnectGracePeriod 30000; // 每个断开会话最多排队 500 条消息默认 100 Meteor.server.options.maxMessageQueueLength 500;选项默认值作用disconnectGracePeriod15000ms断开的会话在被销毁前保留多久maxMessageQueueLength100每个会话最多排队多少条消息超出则丢弃该会话这两个默认值与源码一致packages/ddp-server/livedata_server.js消息队列超限逻辑实现在 livedata_server.js。要完全禁用会话恢复把disconnectGracePeriod设为0。延长宽限期前需要知道的事负载均衡器客户端必须重连到同一个物理 Meteor 实例。请确保负载均衡器配置了粘性会话sticky sessions或 IP hash。内存每条排队消息和活动的订阅游标在宽限期内都驻留内存。高流量服务器上设置过大的maxMessageQueueLength会增加内存压力。onConnection在恢复时不会被调用如果你用onConnection/onClose追踪在线状态请参考 API 文档中的 presence tracking pattern。热代码推送HCP不受影响HCP 是优雅断开总是开启全新会话让客户端拿到新代码。边界情况与存在性心跳模式详见 Reconnection reference。多进程与多租户部署⚠️警告如果在同一 Linux 主机的同一内核网络命名空间kernel network namespace中运行多个DDP_TRANSPORTuws的 Meteor 进程每个进程必须声明自己独立的uws.port或uws.host。内部 uWS 监听 Socket 是独占绑定的每个(host, port)元组只能有一个进程启动。与sockjs不同它活在 Meteor 已绑定的公共 HTTP 端口所在的同一个http.Server内uws在独立内部端口默认127.0.0.1:5001上运行第二个监听 Socket。内核按目标地址对进入的连接做多路分解因此只要元组互不相同每个进程就独占自己的监听 Socket流量路由无歧义。需要按进程配置的场景包括多租户容器Docker / Podman 下network_mode: host各容器有自己的数据库但共宿一机多进程水平扩展PM2、systemd 模板服务或单 VM 上的cluster风格运行器同节点共调度 Pod编排器把同一应用的两个 Pod 放到同一节点本地开发同时运行两个DDP_TRANSPORTuws的 Meteor 项目。单进程部署以及为每个实例提供独立内核网络命名空间的编排器Docker bridge 网络、Kubernetes Pod 的默认情形无需额外配置——默认的127.0.0.1:5001完全够用因为只有单个进程绑定它。为每个进程配置独立的 uws 端口通过METEOR_SETTINGS为每个进程指定内部uws.port# 进程 1 METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5001,host:127.0.0.1}}}} \ PORT8081 DDP_TRANSPORTuws meteor run # 进程 2 —— 同一主机、同一 netns METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5002,host:127.0.0.1}}}} \ PORT8082 DDP_TRANSPORTuws meteor run等价地也可以通过settings.json{ packages: { ddp-server: { uws: { port: 5001, host: 127.0.0.1 } } } }完整设置项如下源码解析见 packages/ddp-server/transports/uws.js字段默认值含义port5001内部 uWS 监听 Socket 的 TCP 端口host127.0.0.1内部 uWS 服务器绑定的地址payloadLength48最大 WebSocket 负载单位 KiB对应 uWS 的maxPayloadLengthtimeout45空闲超时单位秒对应 uWS 的idleTimeout如果实在无法避免端口冲突可以使用不同的回环主机127.0.0.2、127.0.0.3……——Linux 默认把整个127.0.0.0/8路由到lo因此每个进程绑定不同的(host, port)元组内核即可正确多路分解。示例多租户docker-compose.yml在一台共享内核 netnsnetwork_mode: host的 Linux 主机上运行多个 Meteor 3.5 容器时每个服务需要声明两个独立值公共PORT和METEOR_SETTINGS内的内部uws.port。两者相互独立且在整个 netns 内都必须唯一services: tenant1: image: my-meteor-app:latest network_mode: host environment: - PORT3039 # 公共 HTTP 端口 —— 每个服务唯一 - ROOT_URLhttps://app1.example.com - DDP_TRANSPORTuws # 内部 uws 代理端口 —— 每个服务唯一 - METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5001,host:127.0.0.1}}}} - MONGO_URLmongodb://…/tenant1 tenant2: image: my-meteor-app:latest network_mode: host environment: - PORT3040 # 不同的公共端口 - ROOT_URLhttps://app2.example.com - DDP_TRANSPORTuws - METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5002,host:127.0.0.1}}}} - MONGO_URLmongodb://…/tenant2 # tenant3 - uws.port 5003, tenant4 - 5004, 依此类推Meteor 前面的反向代理NGINX、Caddy、ALB……无需任何改动它仍然像对待sockjs一样与每个服务的公共PORT通信。内部uws.port永远不会暴露到容器之外。故障排查failed to listen on 127.0.0.1:5001 (address already in use)如果同一内核 netns 中的两个 Meteor 进程都尝试绑定相同的内部 uWS(host, port)元组——通常是因为都依赖默认的127.0.0.1:5001——后启动的那个会拒绝绑定Meteor 在启动时抛出异常Error: uWebSockets.js: failed to listen on 127.0.0.1:5001 (address already in use). Another Meteor instance in this network namespace is already bound to this port. Set a distinct Meteor.settings.packages[ddp-server].uws.port (or .host) for each instance. at packages/ddp-server/transports/uws.js:121:17 at Object.setup (packages/ddp-server/transports/uws.js:119:14) at new StreamServer (packages/ddp-server/stream_server.js:45:27) …该错误的根源与实现细节值得展开uWS 默认启用SO_REUSEPORT若不加处理同一 netns 内两个进程都能成功绑定同一(host, port)内核会把入站连接在进程间负载均衡导致 WebSocket 升级流量被拆分到无关的应用进程。为此uws.js在uwsApp.listen时显式传入uws.LIBUS_LISTEN_EXCLUSIVE_PORT第二个实例因此得到EADDRINUSEtoken为 falsy随即抛出上述可操作的错误而不是静默泄漏流量uws.js。该行为有专门测试覆盖见 packages/ddp-server/transports/uws_tests.js。解决办法推荐编辑服务的environment:块或编排器中的等价配置加入METEOR_SETTINGS{packages:{ddp-server:{uws:{port:不重复端口,host:127.0.0.1}}}}选择一个 netns 内其他进程未占用的端口后重启。备选对共享主机 netns 的每个服务改用DDP_TRANSPORTsockjs。SockJS 不运行独立内部端口永远不会冲突——代价是 DDP 吞吐量较低。任一路径都能让每个服务运行自己独立的 DDP 栈不会发生跨进程流量混合。验证内部监听 Socket从主机或任何共享 netns 的容器内cat /proc/net/tcp | awk $4 0A {print $2} | sort | uniq -c每个端口一行第二列是LOCAL_ADDR:PORT的小端十六进制表示。0x1389是端口 50010x138A是 5002。你期望看到每个端口至多一个监听者1 0100007F:1389 # 127.0.0.1:5001 —— 一个 Meteor 进程 1 0100007F:138A # 127.0.0.1:5002 —— 另一个 Meteor 进程如果看到2 0100007F:1389说明两个进程正在通过SO_REUSEPORT共享默认 uws 端口入站 DDP 流量被混合分发——请重新配置每个进程绑定自己的端口。反向代理的影响内部 uws 端口纯粹是本地的永远不会暴露给客户端。Meteor 前面的反向代理NGINX、Caddy、ALB、Galaxy……与每个进程的公共端口PORT环境变量通信方式与sockjs完全一致。按进程配置 uws 端口只影响同一进程内公共端口与内部 uWS 服务器之间的连接。验证当前生效的传输方式在服务器端可以通过 Meteor shell 检查配置的传输process.env.DDP_TRANSPORT || Meteor.settings?.packages?.[ddp-server]?.transport || sockjs;在客户端打开浏览器 Network 面板并按 WS 过滤可以看到sockjs—— 请求/sockjs/...包含类似/sockjs/info的握手 URLuws—— 到 DDP 端点的单个 WebSocket 请求无 SockJS 帧。这一判断依据是客户端 browser.js 在sockjs模式下使用 SockJS 客户端产生多条/sockjs/...请求并支持轮询回退在uws模式下直接new WebSocket(...)单条连接、无帧。迁移清单从sockjs切换到uws如果你正在把现有应用从sockjs迁移到uws确认负载均衡器 / 反向代理能升级 WebSocket不存在轮询回退确认 WebSocket 空闲超时 ≥ Meteor 心跳间隔在能代表你用户群的网络上测试移动网络、公共 Wi-Fi、企业网络若负载均衡器支持先对部分流量灰度保留sockjs作为回退方案切换环境变量后重新部署即可若有多个 Meteor 进程共享一台主机多租户、多进程扩展、Galaxy 共调度等为每个进程设置独立的Meteor.settings.packages[ddp-server].uws.port参见上文多进程与多租户部署。回退到sockjs取消环境变量或显式设置unset DDP_TRANSPORT # 或 DDP_TRANSPORTsockjs meteor run无需任何代码改动——传输在服务器启动时选择。参考链接本文主文档DDP Transport环境变量参考DDP_TRANSPORT与DISABLE_SOCKJSWebSocket 压缩WebSocket Compression会话恢复与存在性心跳Reconnection reference核心源码传输解析与注册表packages/ddp-server/transports/index.jsuWS 传输实现packages/ddp-server/transports/uws.jsSockJS 传输实现packages/ddp-server/transports/sockjs.js传输无关的会话层packages/ddp-server/stream_server.js会话恢复参数与消息队列packages/ddp-server/livedata_server.js客户端传输选择packages/socket-stream-client/browser.jsuWS 独占绑定测试packages/ddp-server/transports/uws_tests.js【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Meteor 3.5+ DDP 传输层切换指南：从 SockJS 到 uWebSockets.js 的配置、架构与运维实践
Meteor 3.5 DDP 传输层切换指南从 SockJS 到 uWebSockets.js 的配置、架构与运维实践【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteorMeteor 3.5 起DDP 服务器引入了可插拔传输层pluggable DDP transport layer传输层只负责在客户端与服务器之间搬运 DDP 消息订阅、方法调用、RPCDDP 协议本身完全不变。本文基于v3-docs/docs/performance/ddp-transport.md结合 packages/ddp-server 的源码实现系统讲解sockjs与uws两种传输的选择依据、配置方式、底层架构、负载均衡与多进程部署注意事项以及如何验证当前生效的传输方式。DDP 与传输层理解可插拔设计的前提DDPDistributed Data Protocol是 Meteor 的核心通信协议承载着订阅发布、方法调用RPC等全部实时数据交互。Meteor 3.5 的可插拔设计将协议逻辑与物理承载通道解耦DDP 层协议不变包括sub/unsub、method/result、ping/pong等消息语义传输层仅负责把 DDP 帧在客户端与服务器之间搬运可以整体替换而应用代码无需任何改动。从源码看传输层被抽象为统一接口。在 packages/ddp-server/transports/index.js 中维护了一张传输注册表sockjs与uws都是实现相同setup(httpServer, pathPrefix, options)签名的传输工厂const TRANSPORTS { sockjs: createSockJSTransport, uws: createUwsTransport, };StreamServerpackages/ddp-server/stream_server.js在启动时调用getTransport()解析出传输并执行setup()随后把emitter上的connection事件统一交给_onConnection处理——后续的 DDP 会话、心跳、订阅逻辑与具体传输完全无关。两种可用传输sockjs 与 uws传输本质适用场景sockjs默认SockJS带 HTTP 长轮询回退需要最大化兼容性——客户端位于严格代理之后、移动网络可能中断 WebSocket、或不支持 WebSocket 的环境uwsµWebSockets.js——原生 WebSocket无轮询回退网络路径可控、所有客户端都能维持原生 WebSocket且追求更低延迟与更高消息吞吐⚠️官方警告默认传输sockjs对大多数应用是正确的选择。只有在实测确认 WebSocket 帧处理或轮询回退存在真实瓶颈且你能完全掌控部署环境以端到端验证 WebSocket 连通性时才切换到uws。什么时候选择sockjs面向公网的应用部分用户位于企业代理、强制门户captive portal或屏蔽 WebSocket 的网络之后移动端流量占比高WebSocket 偶发失败时需要自动回退到长轮询部署环境中 Meteor 前端没有支持 WebSocket 感知的负载均衡器。什么时候uws能带来收益已实测服务器 CPU 偏高且可归因于 SockJS 帧处理或 JavaScript 实现的 SockJS 开销在热重连场景移动端、实时看板中SockJS 握手带来了可感知的延迟能保证每个客户端都具备 WebSocket 连通性例如内部应用、可控部署或你接受被代理屏蔽的客户端无法连接你的负载均衡器NGINX、HAProxy、AWS ALB、Galaxy能可靠地把 HTTP 升级为 WebSocket。配置传输方式方式一环境变量DDP_TRANSPORT# 切换到 uws DDP_TRANSPORTuws meteor run # 显式指定默认值 sockjs DDP_TRANSPORTsockjs meteor run方式二settings.json{ packages: { ddp-server: { transport: uws } } }这会把Meteor.settings.packages[ddp-server].transport填充到服务器端DDP 服务器正是读取该值。当两者同时设置时环境变量优先于settings.json。遗留别名DISABLE_SOCKJSDISABLE_SOCKJS1作为DDP_TRANSPORTuws的向后兼容别名仍然被支持但已废弃deprecated。新部署应优先使用DDP_TRANSPORT因为它为未来新增传输后端留出了空间且在部署配置中更易读。传输解析的源码级优先级getTransport()的解析顺序在 packages/ddp-server/transports/index.js 中实现与文档描述一致Meteor.settings.packages[ddp-server].transport环境变量DDP_TRANSPORTDISABLE_SOCKJS存在时 →uws向后兼容以上皆无 → 默认sockjs。需要注意上述优先级顺序与环境变量优先于 settings.json并不矛盾——resolveTransportName()的检查顺序是settings 在前、环境变量在后但若settings.json中同时存在transport配置环境变量同样能覆盖它。实际语义是只要任一来源设置了非空值即生效官方文档明确环境变量优先级更高。若配置了不存在的传输名getTransport()会直接抛出Unknown DDP transport错误transports/index.js。另外getTransport()会把解析结果写入__meteor_runtime_config__.DDP_TRANSPORTtransports/index.js让客户端知道该加载 SockJS 客户端还是使用原生 WebSocket。客户端如何感知传输类型传输选择并不只发生在服务器端。客户端通过__meteor_runtime_config__.DDP_TRANSPORT决定连接策略见 packages/socket-stream-client/browser.jsconst transport __meteor_runtime_config__.DDP_TRANSPORT || sockjs; if (transport sockjs) { this.socket new SockJS(toSockjsUrl(this.rawUrl), undefined, options); } else { // 所有非 SockJS 传输在客户端使用原生 WebSocket this.socket new WebSocket(toWebsocketUrl(this.rawUrl)); }这正是文档所述切换传输无需改动应用代码的机制服务器解析出uws后客户端自动改用原生 WebSocket 直连 DDP 端点使用sockjs时客户端走 SockJS 协议含轮询回退。browser.js还通过_sockjsProtocolsWhitelist()保留了对DISABLE_WEBSOCKETS的处理——该环境变量会从候选协议中剔除websocket强制回退到轮询。uws传输的架构双监听 Socket 与本地 TCP 代理uws与sockjs最本质的架构差异在于sockjs与 Meteor 已绑定的公共 HTTP 端口共用同一个http.Server实例作为 Connect 风格中间件存在见 packages/ddp-server/transports/sockjs.js 的installHandlers。uws在独立的内部端口默认127.0.0.1:5001上运行第二个监听 Socket。公共 HTTP 服务器上到达的 WebSocket 升级请求通过一条本地 TCP 连接被代理到该内部 Socket。该架构由 packages/ddp-server/transports/uws.js 中的proxyWebsocketToUws()实现拦截公共httpServer的upgrade事件若路径匹配pathPrefix /websocket则用net.createConnection(uwsPort, uwsHost)建立到内部 uWS 服务器的 TCP 连接将原始 HTTP 升级请求原样转发给 uWS并把客户端 socket 与 uWS socket 双向pipe若内部 uWS 服务器不可达向客户端返回502 Bad Gateway非/websocket路径的升级请求如 HMR继续交给原有 upgrade 监听器。同时uws.js通过WebApp.rawConnectHandlers.use拒绝了对/websocket的普通 HTTP 请求返回 400确保只有真正的 WebSocket 升级请求才能通过uws.js。正是这种公共端口保留 Meteor Connect 风格中间件 内部 uWS 原生处理 WebSocket I/O的双层设计让uWebSockets.js能以接近原生的速度处理 WebSocket而不牺牲 Meteor 公共端口上的中间件能力。运维考量负载均衡器配置uws不使用 HTTP 轮询。如果你的负载均衡器是按 SockJS 风格的粘性轮询配置的而不是 WebSocket 透传需要把配置切换为在 DDP 路径通常是/sockjs或自定义 DDP URL上把 HTTP 升级为 WebSocket禁用依赖 cookie 粘性的会话亲和session affinity——WebSocket 建立后没有 HTTP 请求来携带 cookie确保 WebSocket 空闲超时至少与 DDP 心跳间隔默认 35 秒一样长。与 WebSocket 压缩结合SERVER_WEBSOCKET_COMPRESSION设置对两种传输都适用。在 packages/ddp-server/stream_server.js 中压缩扩展通过permessage-deflate2配置默认threshold: 1024、Z_BEST_SPEED级别等并注入到 SockJS 的faye_server_options.extensions见 sockjs.js。如果你在 SockJS 下观察到了压缩开销同样的取舍在uws下依然成立——只是基线成本更低。详细说明见 WebSocket Compression。与 DDP 会话恢复Session Resumption结合Meteor 3.5 引入了 DDP 会话恢复当客户端在可配置的宽限期内重连时服务器恢复已有会话而非新建会话。已激活的订阅不会重新发布、在途方法调用会被重放连接保留其原始id。该特性与传输无关——sockjs和uws同等受益。启用与调优会话恢复默认开启。可以在服务器启动代码中调优两个参数import { Meteor } from meteor/meteor; // 让断开的会话存活 30 秒默认 15000 ms Meteor.server.options.disconnectGracePeriod 30000; // 每个断开会话最多排队 500 条消息默认 100 Meteor.server.options.maxMessageQueueLength 500;选项默认值作用disconnectGracePeriod15000ms断开的会话在被销毁前保留多久maxMessageQueueLength100每个会话最多排队多少条消息超出则丢弃该会话这两个默认值与源码一致packages/ddp-server/livedata_server.js消息队列超限逻辑实现在 livedata_server.js。要完全禁用会话恢复把disconnectGracePeriod设为0。延长宽限期前需要知道的事负载均衡器客户端必须重连到同一个物理 Meteor 实例。请确保负载均衡器配置了粘性会话sticky sessions或 IP hash。内存每条排队消息和活动的订阅游标在宽限期内都驻留内存。高流量服务器上设置过大的maxMessageQueueLength会增加内存压力。onConnection在恢复时不会被调用如果你用onConnection/onClose追踪在线状态请参考 API 文档中的 presence tracking pattern。热代码推送HCP不受影响HCP 是优雅断开总是开启全新会话让客户端拿到新代码。边界情况与存在性心跳模式详见 Reconnection reference。多进程与多租户部署⚠️警告如果在同一 Linux 主机的同一内核网络命名空间kernel network namespace中运行多个DDP_TRANSPORTuws的 Meteor 进程每个进程必须声明自己独立的uws.port或uws.host。内部 uWS 监听 Socket 是独占绑定的每个(host, port)元组只能有一个进程启动。与sockjs不同它活在 Meteor 已绑定的公共 HTTP 端口所在的同一个http.Server内uws在独立内部端口默认127.0.0.1:5001上运行第二个监听 Socket。内核按目标地址对进入的连接做多路分解因此只要元组互不相同每个进程就独占自己的监听 Socket流量路由无歧义。需要按进程配置的场景包括多租户容器Docker / Podman 下network_mode: host各容器有自己的数据库但共宿一机多进程水平扩展PM2、systemd 模板服务或单 VM 上的cluster风格运行器同节点共调度 Pod编排器把同一应用的两个 Pod 放到同一节点本地开发同时运行两个DDP_TRANSPORTuws的 Meteor 项目。单进程部署以及为每个实例提供独立内核网络命名空间的编排器Docker bridge 网络、Kubernetes Pod 的默认情形无需额外配置——默认的127.0.0.1:5001完全够用因为只有单个进程绑定它。为每个进程配置独立的 uws 端口通过METEOR_SETTINGS为每个进程指定内部uws.port# 进程 1 METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5001,host:127.0.0.1}}}} \ PORT8081 DDP_TRANSPORTuws meteor run # 进程 2 —— 同一主机、同一 netns METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5002,host:127.0.0.1}}}} \ PORT8082 DDP_TRANSPORTuws meteor run等价地也可以通过settings.json{ packages: { ddp-server: { uws: { port: 5001, host: 127.0.0.1 } } } }完整设置项如下源码解析见 packages/ddp-server/transports/uws.js字段默认值含义port5001内部 uWS 监听 Socket 的 TCP 端口host127.0.0.1内部 uWS 服务器绑定的地址payloadLength48最大 WebSocket 负载单位 KiB对应 uWS 的maxPayloadLengthtimeout45空闲超时单位秒对应 uWS 的idleTimeout如果实在无法避免端口冲突可以使用不同的回环主机127.0.0.2、127.0.0.3……——Linux 默认把整个127.0.0.0/8路由到lo因此每个进程绑定不同的(host, port)元组内核即可正确多路分解。示例多租户docker-compose.yml在一台共享内核 netnsnetwork_mode: host的 Linux 主机上运行多个 Meteor 3.5 容器时每个服务需要声明两个独立值公共PORT和METEOR_SETTINGS内的内部uws.port。两者相互独立且在整个 netns 内都必须唯一services: tenant1: image: my-meteor-app:latest network_mode: host environment: - PORT3039 # 公共 HTTP 端口 —— 每个服务唯一 - ROOT_URLhttps://app1.example.com - DDP_TRANSPORTuws # 内部 uws 代理端口 —— 每个服务唯一 - METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5001,host:127.0.0.1}}}} - MONGO_URLmongodb://…/tenant1 tenant2: image: my-meteor-app:latest network_mode: host environment: - PORT3040 # 不同的公共端口 - ROOT_URLhttps://app2.example.com - DDP_TRANSPORTuws - METEOR_SETTINGS{packages:{ddp-server:{uws:{port:5002,host:127.0.0.1}}}} - MONGO_URLmongodb://…/tenant2 # tenant3 - uws.port 5003, tenant4 - 5004, 依此类推Meteor 前面的反向代理NGINX、Caddy、ALB……无需任何改动它仍然像对待sockjs一样与每个服务的公共PORT通信。内部uws.port永远不会暴露到容器之外。故障排查failed to listen on 127.0.0.1:5001 (address already in use)如果同一内核 netns 中的两个 Meteor 进程都尝试绑定相同的内部 uWS(host, port)元组——通常是因为都依赖默认的127.0.0.1:5001——后启动的那个会拒绝绑定Meteor 在启动时抛出异常Error: uWebSockets.js: failed to listen on 127.0.0.1:5001 (address already in use). Another Meteor instance in this network namespace is already bound to this port. Set a distinct Meteor.settings.packages[ddp-server].uws.port (or .host) for each instance. at packages/ddp-server/transports/uws.js:121:17 at Object.setup (packages/ddp-server/transports/uws.js:119:14) at new StreamServer (packages/ddp-server/stream_server.js:45:27) …该错误的根源与实现细节值得展开uWS 默认启用SO_REUSEPORT若不加处理同一 netns 内两个进程都能成功绑定同一(host, port)内核会把入站连接在进程间负载均衡导致 WebSocket 升级流量被拆分到无关的应用进程。为此uws.js在uwsApp.listen时显式传入uws.LIBUS_LISTEN_EXCLUSIVE_PORT第二个实例因此得到EADDRINUSEtoken为 falsy随即抛出上述可操作的错误而不是静默泄漏流量uws.js。该行为有专门测试覆盖见 packages/ddp-server/transports/uws_tests.js。解决办法推荐编辑服务的environment:块或编排器中的等价配置加入METEOR_SETTINGS{packages:{ddp-server:{uws:{port:不重复端口,host:127.0.0.1}}}}选择一个 netns 内其他进程未占用的端口后重启。备选对共享主机 netns 的每个服务改用DDP_TRANSPORTsockjs。SockJS 不运行独立内部端口永远不会冲突——代价是 DDP 吞吐量较低。任一路径都能让每个服务运行自己独立的 DDP 栈不会发生跨进程流量混合。验证内部监听 Socket从主机或任何共享 netns 的容器内cat /proc/net/tcp | awk $4 0A {print $2} | sort | uniq -c每个端口一行第二列是LOCAL_ADDR:PORT的小端十六进制表示。0x1389是端口 50010x138A是 5002。你期望看到每个端口至多一个监听者1 0100007F:1389 # 127.0.0.1:5001 —— 一个 Meteor 进程 1 0100007F:138A # 127.0.0.1:5002 —— 另一个 Meteor 进程如果看到2 0100007F:1389说明两个进程正在通过SO_REUSEPORT共享默认 uws 端口入站 DDP 流量被混合分发——请重新配置每个进程绑定自己的端口。反向代理的影响内部 uws 端口纯粹是本地的永远不会暴露给客户端。Meteor 前面的反向代理NGINX、Caddy、ALB、Galaxy……与每个进程的公共端口PORT环境变量通信方式与sockjs完全一致。按进程配置 uws 端口只影响同一进程内公共端口与内部 uWS 服务器之间的连接。验证当前生效的传输方式在服务器端可以通过 Meteor shell 检查配置的传输process.env.DDP_TRANSPORT || Meteor.settings?.packages?.[ddp-server]?.transport || sockjs;在客户端打开浏览器 Network 面板并按 WS 过滤可以看到sockjs—— 请求/sockjs/...包含类似/sockjs/info的握手 URLuws—— 到 DDP 端点的单个 WebSocket 请求无 SockJS 帧。这一判断依据是客户端 browser.js 在sockjs模式下使用 SockJS 客户端产生多条/sockjs/...请求并支持轮询回退在uws模式下直接new WebSocket(...)单条连接、无帧。迁移清单从sockjs切换到uws如果你正在把现有应用从sockjs迁移到uws确认负载均衡器 / 反向代理能升级 WebSocket不存在轮询回退确认 WebSocket 空闲超时 ≥ Meteor 心跳间隔在能代表你用户群的网络上测试移动网络、公共 Wi-Fi、企业网络若负载均衡器支持先对部分流量灰度保留sockjs作为回退方案切换环境变量后重新部署即可若有多个 Meteor 进程共享一台主机多租户、多进程扩展、Galaxy 共调度等为每个进程设置独立的Meteor.settings.packages[ddp-server].uws.port参见上文多进程与多租户部署。回退到sockjs取消环境变量或显式设置unset DDP_TRANSPORT # 或 DDP_TRANSPORTsockjs meteor run无需任何代码改动——传输在服务器启动时选择。参考链接本文主文档DDP Transport环境变量参考DDP_TRANSPORT与DISABLE_SOCKJSWebSocket 压缩WebSocket Compression会话恢复与存在性心跳Reconnection reference核心源码传输解析与注册表packages/ddp-server/transports/index.jsuWS 传输实现packages/ddp-server/transports/uws.jsSockJS 传输实现packages/ddp-server/transports/sockjs.js传输无关的会话层packages/ddp-server/stream_server.js会话恢复参数与消息队列packages/ddp-server/livedata_server.js客户端传输选择packages/socket-stream-client/browser.jsuWS 独占绑定测试packages/ddp-server/transports/uws_tests.js【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考