Nacos 服务端远程连接生命周期解析:从 gRPC 传输层到连接保护机制

原创2026-09-09 16:03:411,955 阅读
文章标签:后端服务注册发现配置中心微服务云原生前端DNS认证鉴权

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)

文档给出的五条身份规则,均可在源码中逐条印证:

  1. 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),这是"传输断开即注销"这一规则的执行点。

  1. 连接必须完成 ConnectionSetupRequest 处理后才接受普通一元请求。普通请求处理器 GrpcRequestAcceptor 会先校验 gRPC 上下文中的 connectionId 是否已在 ConnectionManager 注册,未注册则返回 UN_REGISTER 错误。

  2. labels 必须包含来源信息(SDK 或 cluster)。ConnectionMeta 的 isSdkSource() / isClusterSource() 方法正是读取 RemoteConstants.LABEL_SOURCE 这个 label 来判断来源。

  3. cluster 来源连接是内部连接,绕过 SDK 连接限制检查。ConnectionManager.checkLimit() 中第一行即 if (connection.getMetaInfo().isClusterSource()) { return false; }——集群连接直接放行,只有 SDK 连接会走 Control 插件的 ConnectionControlManager.check(...) 限连检查。

  4. 能力表在 setup 阶段协商,并通过 RequestMeta 传递给请求处理器。GrpcRequestAcceptor 构建 RequestMeta 时明确执行了 requestMeta.setAbilityTable(connection.getAbilityTable())。

  5. 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 中可完整追踪:

  1. 传输层在 gRPC transport ready 时创建连接属性——AddressTransportFilter.transportReady 生成 connectionId 与地址属性(第 2 节已述)。
  2. 客户端在双向流上发送 ConnectionSetupRequest。
  3. 服务端构建 ConnectionMeta:来源 payload 元数据中的 clientIp、setup 携带的 labels、客户端版本、appName(缺省为 "-")、tenant(命名空间)、远端/本地地址、连接类型(GRPC);TLS 状态则从 gRPC channel 的 TLS_PROTECTED 属性读取后写入 metaInfo.setTlsProtected(...)。
  4. 通过 ConnectionGeneratorService 创建 Connection——源码中为 ConnectionGeneratorServiceDelegate.getInstance().getConnection(metaInfo, responseObserver, channel),该委托机制允许以 SPI 方式替换连接实现。
  5. 若 setup 携带了能力表,则存到连接上:connection.setAbilityTable(setUpRequest.getAbilityTable())。
  6. 服务端仍在启动中时拒绝 SDK 连接:boolean rejectSdkOnStarting = metaInfo.isSdkSource() && !ApplicationUtils.isStarted(); 这一行精确实现了"启动期拒连"规则,且只针对 SDK 来源——集群连接不受影响。
  7. ConnectionManager.register 执行注册(源码):校验 connection.isConnected() → 幂等检查(已存在则直接成功)→ checkLimit 应用 Control 插件连接控制规则 → 若命中监控 IP 列表则打 trace 标记 → 存入注册表 → 该 clientIp 计数 +1 → 通知所有 ClientConnectionEventListener。
  8. 若使用了能力协商,服务端回发 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):

  1. 用 PushAckIdGenerator 生成推送请求 ID;
  2. 创建 DefaultRequestFuture 并注册进 RpcAckCallbackSynchronizer(syncCallback(connectionId, requestId, future));
  3. 调用 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):

  1. 活跃超时:now - lastActiveTime >= KEEP_ALIVE_TIME,其中 KEEP_ALIVE_TIME = 20000L(20 秒,定义在基类 RuntimeConnectionEjector 中,源码);
  2. 推送队列持续阻塞: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)时的直接检查清单:

  1. 只把运行时状态绑定到 connectionId——不绑定其他弱标识;
  2. 断开时清理连接绑定的状态——在 clientDisConnected 回调中完成;
  3. 断开处理必须幂等——同一 connectionId 可能因传输终止、剔除、显式移除等多条路径触发回调;
  4. 重连视为一条新连接,除非域 spec 显式定义了可恢复身份;
  5. 用 RequestMeta 的 labels、source、能力表、客户端版本做兼容决策,而不是重新解析传输内部细节——这正是能力表机制的意义:协商结果随 RequestMeta 下发到每个域处理器;
  6. 永远不要把连接存在当作持久化授权、所有权或持久性证据;
  7. 尽量把慢速远程 IO 移出监听器回调,避免阻塞连接注册或清理流程(unregister 是同步方法,监听器在其中串行执行);
  8. 让推送失败与连接忙(connection-busy)通过域的重试或重新同步语义可见——远程层只抛出 ConnectionBusyException,"如何追平"是域的问题。

10. 关联文档与延伸阅读

关键源码入口一览(均在 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。

登录后查看全文
nacos