Nacos 服务端远程连接生命周期解析:从 gRPC 传输层到连接保护机制
Nacos 服务端远程连接生命周期解析:从 gRPC 传输层到连接保护机制
本文基于 Nacos 的设计文档 Foundation Remote Connection Spec,系统梳理 Nacos 服务端远程连接(remote connection)的完整生命周期:连接模型与身份规则、SDK/Cluster 双 gRPC 服务面、连接建立(Setup)与注册、一元请求处理、服务端推送与确认(Ack)匹配、注销与监听器回调、活性检测与运行时剔除。读完本文,你可以理解 Nacos 长连接服务端每一环的源码级实现(位于 core 模块),并在排查连接异常、配置 gRPC 参数、或为业务域接入连接生命周期事件时拥有明确的实现依据。
1. 能力边界:远程连接层负责什么,不负责什么
Nacos 的远程连接层是"基础设施层"(foundation level)能力,它细化了 Foundation Capabilities Spec 中远程连接的部分。其职责范围包括:
- SDK 与 Cluster 两类来源的 gRPC 传输启动;
- 连接 ID 生成与传输地址捕获;
- 连接的建立(setup)、注册、拒绝与注销;
- 连接元数据与能力表(ability table)的传递;
- 请求元数据与请求上下文的构建;
- 服务端到客户端的推送(push)与确认(ack)匹配;
- 活跃时间刷新、僵尸连接检测与运行时剔除;
- 面向域运行时状态的连接监听器回调。
同时,文档明确划定了它不负责的内容:Config、Naming、AI 或 Auth 的 payload 语义;公开 HTTP API 行为;持久化域状态;SDK 侧重试、故障转移与服务器列表选择(这部分由 Client Connection And Failover Spec 定义);以及 AP/CP 一致性成员管理。公开 gRPC 信封(envelope)与 JSON payload 策略则由 gRPC API Spec 定义——本文档只定义承载这些请求的服务端连接生命周期。
一句话概括其分层哲学:连接层拥有传输状态与连接保护,域模块拥有请求语义。
2. 连接模型:四个核心抽象
| 模型 | 职责 |
|---|---|
Connection |
暴露连接元数据、labels、能力表、trace 标记、同步请求、异步请求、免确认推送、关闭与连通性检查 |
ConnectionMeta |
保存连接 ID、来源、客户端 IP、远端端点、本地端口、版本、应用名、命名空间、labels、TLS 标记、创建时间、最后活跃时间、推送队列阻塞时间戳 |
ConnectionManager |
拥有内存连接注册表、按客户端 IP 的计数器、连接控制检查、监听器回调、活跃时间刷新与运行时剔除 |
ClientConnectionEventListener |
允许业务域在连接注册/注销时挂载或释放运行时状态 |
对应的源码实现位于 core 模块:
- Connection 是服务端对一条存活远程连接的抽象,默认 gRPC 实现为 GrpcConnection;
- ConnectionMeta 逐字段承载了上表所列元信息;
- ConnectionManager 以
ConcurrentHashMap<String, Connection>维护注册表,并以Map<String, AtomicInteger>维护每个客户端 IP 的连接计数。
连接身份规则(connection identity rules)
文档给出的五条身份规则,均可在源码中逐条印证:
connectionId在 gRPC 传输就绪时生成,由时间戳、远端 IP 与远端端口拼接。AddressTransportFilter 的transportReady回调中可以看到生成逻辑:
Attributes attrWrapper = transportAttrs.toBuilder()
.set(ATTR_TRANS_KEY_CONN_ID,
System.currentTimeMillis() + "_" + remoteIp + "_" + remotePort)
.set(ATTR_TRANS_KEY_REMOTE_IP, remoteIp)
.set(ATTR_TRANS_KEY_REMOTE_PORT, remotePort)
.set(ATTR_TRANS_KEY_LOCAL_PORT, localPort).build();
同一个 Filter 的 transportTerminated 回调会在传输终止时调用 connectionManager.unregister(connectionId),这是"传输断开即注销"这一规则的执行点。
-
连接必须完成
ConnectionSetupRequest处理后才接受普通一元请求。普通请求处理器 GrpcRequestAcceptor 会先校验 gRPC 上下文中的 connectionId 是否已在ConnectionManager注册,未注册则返回UN_REGISTER错误。 -
labels 必须包含来源信息(SDK 或 cluster)。ConnectionMeta 的
isSdkSource()/isClusterSource()方法正是读取RemoteConstants.LABEL_SOURCE这个 label 来判断来源。 -
cluster 来源连接是内部连接,绕过 SDK 连接限制检查。
ConnectionManager.checkLimit()中第一行即if (connection.getMetaInfo().isClusterSource()) { return false; }——集群连接直接放行,只有 SDK 连接会走 Control 插件的ConnectionControlManager.check(...)限连检查。 -
能力表在 setup 阶段协商,并通过
RequestMeta传递给请求处理器。GrpcRequestAcceptor 构建RequestMeta时明确执行了requestMeta.setAbilityTable(connection.getAbilityTable())。 -
lastActiveTime必须由被接受的一元请求和推送确认刷新。一元路径中connectionManager.refreshActiveTime(...)在域处理器执行之前被调用;双向流收到Response(即推送 ack)时同样会调用refreshActiveTime(见 GrpcBiStreamRequestAcceptor 中RpcAckCallbackSynchronizer.ackNotify(connectionId, response)之后的connectionManager.refreshActiveTime(connectionId))。
3. 双 gRPC 服务面:SDK 与 Cluster
Nacos 暴露两个 gRPC 服务器来源,二者均继承自 BaseGrpcServer:
| 来源 | 服务端类 | 端口偏移 | 用途 |
|---|---|---|---|
| SDK | GrpcSdkServer | SDK_GRPC_PORT_DEFAULT_OFFSET = 1000 |
客户端到服务端请求与服务端推送 |
| Cluster | GrpcClusterServer | CLUSTER_GRPC_PORT_DEFAULT_OFFSET = 1001 |
服务端到服务端(集群内部)请求 |
端口偏移常量定义在 Constants:默认主端口 8848 之上,SDK gRPC 端口为 9848、集群 gRPC 端口为 9849。
两个服务面在 BaseGrpcServer.addServices() 中注册了完全对称的两组方法:
- 一元方法
Request/request:普通请求/响应调用,最终进入GrpcRequestAcceptor.request(...); - 双向流方法
BiRequestStream/requestBiStream:承载连接 Setup、服务端推送与推送确认,进入GrpcBiStreamRequestAcceptor; AddressTransportFilter:捕获远端/本地地址,并在传输终止时注销连接(见第 2 节);GrpcConnectionInterceptor(源码):把连接 ID 与地址属性写入 gRPC 上下文,供后续处理器以GrpcServerConstants.CONTEXT_KEY_CONN_ID.get()读取;- 来源专属的拦截器、传输过滤器、keepalive 配置与入站消息大小配置。
可配置的传输保护参数
BaseGrpcServer 以 NettyServerBuilder 构建服务时应用了 keepalive 与入站消息限制(startServer):
server = builder.maxInboundMessageSize(getMaxInboundMessageSize())
.fallbackHandlerRegistry(handlerRegistry)
.keepAliveTime(getKeepAliveTime(), TimeUnit.MILLISECONDS)
.keepAliveTimeout(getKeepAliveTimeout(), TimeUnit.MILLISECONDS)
.permitKeepAliveTime(getPermitKeepAliveTime(), TimeUnit.MILLISECONDS).build();
GrpcSdkServer / GrpcClusterServer 分别覆写这些取值方法,支持按来源独立配置。配置项键名与默认值集中定义在 GrpcServerConstants:
| 配置项 | 作用 | 默认值 |
|---|---|---|
nacos.remote.server.grpc.sdk.max-inbound-message-size |
SDK 面入站消息大小上限 | 10 MB(DEFAULT_GRPC_MAX_INBOUND_MSG_SIZE = 10 * 1024 * 1024) |
nacos.remote.server.grpc.sdk.keep-alive-time |
SDK 面 keepalive ping 周期 | gRPC 默认值 |
nacos.remote.server.grpc.sdk.keep-alive-timeout |
keepalive ping 等待超时 | gRPC 默认值 |
nacos.remote.server.grpc.sdk.permit-keep-alive-time |
允许的最小客户端 keepalive 间隔 | 5 分钟(TimeUnit.MINUTES.toMillis(5L)) |
nacos.remote.server.grpc.cluster.*(同名四项) |
Cluster 面对应配置 | 同上 |
值得注意的是,SDK 面与 Cluster 面还通过 SPI 加载器(NacosGrpcServerInterceptorServiceLoader / NacosGrpcServerTransportFilterServiceLoader)分别挂载 SDK_INTERCEPTOR / CLUSTER_INTERCEPTOR 类型的扩展拦截器与过滤器,允许以插件方式增强鉴权等横切能力,同时各自使用独立的协议协商器(SdkProtocolNegotiatorBuilderSingleton / ClusterProtocolNegotiatorBuilderSingleton)以支持 TLS 等传输增强。
文档还强调:服务端 keepalive 配置属于传输保护,域模块必须消费连接生命周期事件,而不是自己实现 gRPC 心跳。这与第 2 节"域不拥有传输语义"的边界一致。
4. 连接建立与注册(Setup And Registration)
连接 Setup 走双向流,完整流程在 GrpcBiStreamRequestAcceptor 中可完整追踪:
- 传输层在 gRPC transport ready 时创建连接属性——
AddressTransportFilter.transportReady生成 connectionId 与地址属性(第 2 节已述)。 - 客户端在双向流上发送
ConnectionSetupRequest。 - 服务端构建
ConnectionMeta:来源 payload 元数据中的 clientIp、setup 携带的 labels、客户端版本、appName(缺省为"-")、tenant(命名空间)、远端/本地地址、连接类型(GRPC);TLS 状态则从 gRPC channel 的TLS_PROTECTED属性读取后写入metaInfo.setTlsProtected(...)。 - 通过
ConnectionGeneratorService创建Connection——源码中为ConnectionGeneratorServiceDelegate.getInstance().getConnection(metaInfo, responseObserver, channel),该委托机制允许以 SPI 方式替换连接实现。 - 若 setup 携带了能力表,则存到连接上:
connection.setAbilityTable(setUpRequest.getAbilityTable())。 - 服务端仍在启动中时拒绝 SDK 连接:
boolean rejectSdkOnStarting = metaInfo.isSdkSource() && !ApplicationUtils.isStarted();这一行精确实现了"启动期拒连"规则,且只针对 SDK 来源——集群连接不受影响。 ConnectionManager.register执行注册(源码):校验connection.isConnected()→ 幂等检查(已存在则直接成功)→checkLimit应用 Control 插件连接控制规则 → 若命中监控 IP 列表则打 trace 标记 → 存入注册表 → 该 clientIp 计数 +1 → 通知所有ClientConnectionEventListener。- 若使用了能力协商,服务端回发
SetupAckRequest携带当前服务端能力表:
if (setUpRequest.getAbilityTable() != null) {
// finish register, tell client has set up successfully
connection.sendRequestNoAck(new SetupAckRequest(
NacosAbilityManagerHolder.getInstance().getCurrentNodeAbilities(AbilityMode.SERVER)));
}
注册失败(超限或服务未就绪)时的行为是直接关闭连接(connection.close()),且由于注册未成功、监听器未被通知,不会有任何域运行时状态挂在这个被拒绝的 connectionId 上——这正对应文档"Registration failure closes the connection. It must not leave domain runtime state attached to the rejected connection id"的要求。
5. 一元请求处理规则
普通一元请求由 GrpcRequestAcceptor 处理。其 request(Payload, StreamObserver) 方法按文档所列规则依次执行(以下行号均指该文件):
| 规则 | 源码印证 |
|---|---|
| 服务启动中拒绝请求,ServerCheck 除外 | L92-L103:!ApplicationUtils.isStarted() 时返回 INVALID_SERVER_STATUS |
ServerCheckRequest 直接处理并返回连接 ID |
L106-L115:返回 ServerCheckResponse(connectionId, true),不走域处理器 |
| 处理器按请求类简单名解析 | L117:requestHandlerRegistry.getByRequestType(type),type 即请求类 simpleName |
| gRPC 上下文中的 connectionId 必须已注册 | L134-L149:connectionManager.checkValid(connectionId) 失败返回 UN_REGISTER |
| 畸形/未知/非 Request 的 payload 返回错误响应 | L151-L197:解析失败返回 BAD_GATEWAY,无处理器返回 NO_HANDLER |
RequestMeta 必须含 clientIp、connectionId、clientVersion、labels、能力表 |
L203-L208:五个字段全部取自已注册连接 |
| 请求过滤(filters)先于域处理器执行 | 由 RequestHandlerRegistry 中登记的 filter 链完成,详见 Request Filtering And Runtime Context Spec |
| 被接受的一元请求先刷新活跃时间再做域处理 | L209:connectionManager.refreshActiveTime(...) 位于 requestHandler.handleRequest(...) 之前 |
另一个值得注意的细节:当域处理器返回 OVER_THRESHOLD(TPS 限流命中)时,响应会被放入 CONTROL_SCHEDULER 延迟 1 秒后再发出(L214-L220),用一次可控的延迟代替立即失败,避免客户端在限流窗口内形成重试风暴。
文档同时强调:请求处理器拥有 payload 语义,远程层只负责路由、元数据、上下文、过滤与响应转换。
6. 推送与确认(Push And Acknowledgement)
服务端到客户端的推送复用已注册 Connection 上的双向流。GrpcConnection 实现了文档中的全部推送规则:
6.1 免确认推送与写队列就绪检查
sendRequestNoAck(Request)(L71-L100)先把 Nacos Request 转换为 gRPC Payload 并写入双向流。写入前有 sendQueueBlockCheck():
if (streamObserver instanceof ServerCallStreamObserver) {
// if bytes on queue is greater than 32k ,isReady will return false.
boolean ready = ((ServerCallStreamObserver<?>) streamObserver).isReady();
if (!ready) {
// record TPS point "SERVER_PUSH_BLOCK", record block time
getMetaInfo().recordPushQueueBlockTimes();
throw new ConnectionBusyException("too much bytes on sending queue of this stream.");
} else {
getMetaInfo().clearPushQueueBlockTimes();
}
}
这印证了文档中三条规则:写队列(isReady(),阈值 32KB,由 gRPC 内部 DEFAULT_ONREADY_THRESHOLD 固定)必须在推送前检查;不就绪时记录 push-queue 阻塞时间戳(recordPushQueueBlockTimes,落到 ConnectionMeta 的 firstPushQueueBlockTime / lastPushQueueBlockTime),并以 ConnectionBusyException 表达"连接忙"语义;此外还注册了 SERVER_PUSH_BLOCK TPS 监控点,使推送阻塞成为 Control 插件可观测、可限流的保护点。
6.2 流写入必须串行化
StreamObserver.onNext 并非线程安全,源码中用 synchronized (streamObserver) 包裹写入,并注释了原因——避免直接内存泄漏(L73-L79)。写入被提交到 channel 的 eventLoop 上执行,保证序列化。
6.3 带确认的推送与 Ack 匹配
request() / requestFuture() / asyncRequest() 均收敛到 sendRequestInner()(L147-L166):
- 用
PushAckIdGenerator生成推送请求 ID; - 创建
DefaultRequestFuture并注册进RpcAckCallbackSynchronizer(syncCallback(connectionId, requestId, future)); - 调用
sendRequestNoAck实际写流;若写失败则cancel该 future,防止悬挂。
双向流方向上,客户端回传的 Response payload 被识别为推送确认:GrpcBiStreamRequestAcceptor 中对 Response 分支调用 RpcAckCallbackSynchronizer.ackNotify(connectionId, response),完成或清理匹配的 future,同时刷新活跃时间。断开清理方面,sendRequestInner 中 future 的取消钩子即 RpcAckCallbackSynchronizer.clearFuture(connectionId, requestId);request() 的 finally 块中也显式 clearFuture,保证连接断开后该连接不再残留 ack 状态。
最后一条边界规则同样被严格遵守:推送与确认管线不定义任何域订阅语义。"推什么、何时推"分别由 Config、Naming、AI 各自的 spec 决定(如 config-listener-watch-spec),远程层只提供可靠的推送信道。
7. 注销与监听器回调
连接在以下情形被注销:传输终止、活性检测失败、超限剔除关闭连接,或其他服务端逻辑显式移除。
ConnectionManager.unregister 完整实现了文档列出的注销规则:
public synchronized void unregister(String connectionId) {
Connection remove = this.connections.remove(connectionId);
if (remove != null) {
String clientIp = remove.getMetaInfo().clientIp;
AtomicInteger atomicInteger = connectionForClientIp.get(clientIp);
if (atomicInteger != null) {
int count = atomicInteger.decrementAndGet();
if (count <= 0) {
connectionForClientIp.remove(clientIp);
}
}
remove.close();
clientConnectionEventListenerRegistry.notifyClientDisConnected(remove);
}
}
逐条对应:先从注册表移除(connections.remove),再递减 per-client-ip 计数器并在归零时删除该 key,然后关闭底层传输(remove.close() 内部依次关闭双向流与 gRPC channel),最后回调 ClientConnectionEventListener。ClientConnectionEventListenerRegistry 的实现保证单个监听器抛错只记录日志、不阻断其他监听器。
由此推导出文档对域运行时的两条纪律:域管理器可以通过 clientConnected 把状态挂到 connectionId 上,但必须通过 clientDisConnected 释放或重建该状态;持久化状态不得依赖连接生命周期——连接只是运行时信道,不是持久化的授权、所有权或数据证据。
8. 活性检测与运行时剔除(Active Detection And Runtime Ejection)
ConnectionManager 在 @PostConstruct start()(L255-L279)中启动周期性剔除任务:初始延迟 1 秒、每 3 秒执行一次 runtimeConnectionEjector.doEject(),并顺带把连接总数上报指标。剔除器本身通过 SPI 加载:ControlConfigs 指定 ejector 名称,NacosServiceLoader.load(RuntimeConnectionEjector.class) 匹配加载,找不到则回退到默认的 NacosRuntimeConnectionEjector——这对应文档"runtime ejector 实现可通过 SPI 加载,但必须保持 ConnectionManager 注册表与监听器语义"的要求。
8.1 僵尸连接检测(stale detection)
默认剔除器的候选规则有两条(ejectOutdatedConnection):
- 活跃超时:
now - lastActiveTime >= KEEP_ALIVE_TIME,其中KEEP_ALIVE_TIME = 20000L(20 秒,定义在基类RuntimeConnectionEjector中,源码); - 推送队列持续阻塞:
pushQueueBlockTimesLastOver(300 * 1000),即写队列阻塞窗口达到 300 秒。
对候选连接,剔除器下发 ClientDetectionRequest(5 秒超时)做活性探测:收到成功响应则刷新活跃时间并视为存活;未成功响应的连接最终被 unregister。整个过程用 CountDownLatch 汇聚并发探测结果,单次探测统一等待 5 秒上限,避免剔除任务本身拖长。
8.2 过载剔除(overload ejection)
ejectOverLimitConnection() 的规则同样与文档逐条对应:
- 仅当设置了目标负载数(
getLoadClient() > 0,由ConnectionManager.loadCount(loadClient, redirectAddress)注入,通常来自集群负载均衡指令)才生效; - 逐条比较
currentConnectionCount - loadClient,对仅 SDK 来源的连接调用loadSingle(id, redirectAddress); loadSingle(ConnectionManager L293-L319)向客户端发送ConnectResetRequest,若携带重定向地址(ip:port)则拆分为 serverIp/serverPort 一并下发,让 SDK 客户端按 Client Connection And Failover Spec 重新连接目标节点;集群连接明确不在 SDK 负载均衡剔除范围内;- 一轮剔除完成后重置
loadClient = -1与重定向地址,保证指令一次性。
最后,连接控制规则与 TPS 检查属于 Control 插件定义的横切保护点(见 Control Plugin Spec):它们可以拒绝或拖慢连接路径(如注册时的连接数限制、推送阻塞时的 SERVER_PUSH_BLOCK 限流),但不得改变域数据的所有权归属。
9. 域消费方守则(Domain Consumer Rules)
文档第 9 节为 Config、Naming、AI 等消费连接生命周期的域模块列出了八条守则,这是编写域侧运行时管理器(runtime manager)时的直接检查清单:
- 只把运行时状态绑定到
connectionId——不绑定其他弱标识; - 断开时清理连接绑定的状态——在
clientDisConnected回调中完成; - 断开处理必须幂等——同一 connectionId 可能因传输终止、剔除、显式移除等多条路径触发回调;
- 重连视为一条新连接,除非域 spec 显式定义了可恢复身份;
- 用
RequestMeta的 labels、source、能力表、客户端版本做兼容决策,而不是重新解析传输内部细节——这正是能力表机制的意义:协商结果随RequestMeta下发到每个域处理器; - 永远不要把连接存在当作持久化授权、所有权或持久性证据;
- 尽量把慢速远程 IO 移出监听器回调,避免阻塞连接注册或清理流程(
unregister是同步方法,监听器在其中串行执行); - 让推送失败与连接忙(connection-busy)通过域的重试或重新同步语义可见——远程层只抛出
ConnectionBusyException,"如何追平"是域的问题。
10. 关联文档与延伸阅读
- 上层能力总览:Foundation Capabilities Spec
- 集群成员管理:Cluster Membership Spec
- 集群内部请求:Internal RPC And Cluster Request Spec
- 请求过滤与运行时上下文:Request Filtering And Runtime Context Spec
- 公开 gRPC 协议:gRPC API Spec
- 保护点插件:Control Plugin Spec、Trace Plugin Spec
关键源码入口一览(均在 core 模块):
| 关注点 | 文件 |
|---|---|
| 连接注册/注销/剔除调度 | ConnectionManager.java |
| 连接元数据 | ConnectionMeta.java |
| 默认运行时剔除器 | NacosRuntimeConnectionEjector.java |
| gRPC 服务器基类 | BaseGrpcServer.java |
| SDK / Cluster 服务面 | GrpcSdkServer.java、GrpcClusterServer.java |
| 连接 ID 与传输生命周期 | AddressTransportFilter.java |
| Setup 与 SetupAck | GrpcBiStreamRequestAcceptor.java |
| 一元请求处理 | GrpcRequestAcceptor.java |
| 推送、写队列检查与 Ack future | GrpcConnection.java |
| gRPC 配置键与默认值 | GrpcServerConstants.java |
单元测试同样覆盖了上述核心路径,可用于验证行为假设:ConnectionManagerTest、GrpcRequestAcceptorTest、GrpcConnectionTest、ConnectionMetaTest。