企业官网建设流程全解析

Nacos Client Runtime 规范全解：连接、能力协商、本地缓存与断线重连的运行时语义

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos

本篇技术指南系统解读 Nacos 客户端运行时（Client Runtime）的共享规则，涵盖 SDK 初始化与生命周期、服务器地址解析与刷新、HTTP/gRPC 传输选择、连接生命周期与故障转移（failover）、TLS 与请求身份传播、基于连接的能力协商、本地快照与 failover 数据、监听器/订阅/redo 状态恢复以及客户端指标与诊断钩子。读完本文，你将掌握 Nacos Client SDK 在应用运行期如何保持对配置、命名、AI 与分布式锁资源的"可用视图"，以及如何依据官方规范排查连接与重连问题。

1. 运行时（Client Runtime）是什么：边界与分层

1.1 职责边界：Runtime 拥有什么、不拥有什么

client-runtime-spec.md 明确定义：公共 Client SDK 接口之下的共享运行时规则构成 Client Runtime，而公共 SDK 的能力边界由 SDK Spec 定义。Client Runtime 拥有：

• SDK 初始化、命名空间绑定、属性解析与生命周期关闭；
• 服务器地址列表的解析与刷新；
• 客户端侧 HTTP 与 gRPC 传输的选择；
• 连接生命周期、failover、TLS 与身份传播；
• 连接维度的能力协商（ability negotiation）；
• 本地快照、本地 failover 数据、监听器状态、订阅状态与 redo 状态；
• 客户端侧指标与诊断钩子。

同时它不拥有：Config/Naming/AI/Lock 的资源语义、服务端 AP/CP 一致性、持久化与 dump 顺序、Admin API 与 Maintainer SDK 的管理契约，以及插件语义（只调用客户端侧插件扩展点，不定义插件内部行为）。

一句话概括边界：领域规范定义"资源是什么"，Client Runtime 定义"SDK 如何在应用正常运行期间让资源的视图保持可用"。

1.2 分层结构

规范给出的运行时分层如下：

Public SDK interface -> Service implementation and client proxy -> Server list, authentication, and transport runtime -> Connection, ability, cache, listener, and redo runtime -> Domain request or local recovery view

值得强调的是：Service 实现可以使用 gRPC、HTTP、本地文件或它们的组合，但公共 SDK 行为必须在传输层变化时保持稳定——这是"语义契约而非传输契约"的体现，与 SDK Spec 第 7 节"SDK contract is a semantic contract, not a transport contract"完全一致。

2. 四条核心设计规则

2.1 运行时客户端不是管理面

Client Runtime 面向应用执行场景优化，提供已知资源的快速访问、订阅、本地恢复与连接修复。它不得静默引入大范围的命名空间、集群或领域管理能力——管理行为归属于 Admin API 或 Maintainer SDK。这也是 SDK Spec 中 Client SDK 与 Maintainer SDK 两大家族划分的运行时体现。

2.2 运行时数据是派生数据，除非显式声明

本地缓存、failover 文件、监听器状态、订阅状态与 redo 条目都派生于客户端意图或服务端响应，不是服务端权威状态。唯一的例外是用户显式维护的本地 failover 文件：它可以临时覆盖远程读取视图，但本身不会回写服务端。

2.3 连接状态是恢复信号

gRPC 连接事件是监听器 resync、模糊监听（fuzzy watch）resync、命名订阅 redo、临时实例 redo、AI 端点 redo 以及其他运行时修复的触发器。领域客户端必须把重连视为一个新的服务端挂载点，除非其领域规范定义了更强的契约。

2.4 传输安全是运行时基础设施

客户端侧认证插件、请求身份头、TLS 与双向 TLS 都是运行时基础设施。领域请求对象不应重复实现传输安全逻辑；领域规范可以定义权限检查使用哪种资源身份，但"请求如何携带登录身份到达所选传输"由 Client Runtime 负责。

3. 运行时组件全景：四个子规范

Client Runtime 由四个子规范分别展开，它们在仓库中的位置如下：

4. 服务器地址解析与刷新（Connection & Failover）

4.1 地址解析：ServerListProvider

客户端 SDK 通过ServerListProvider解析 Nacos 服务器地址。当前 Java 实现支持三种来源：

1. 来自serverAddr的固定地址；
2. 来自 endpoint/address server 的动态地址；
3. 用于扩展场景的 SPI 提供者。

固定地址列表在初始化后保持稳定；动态地址提供者可以周期性刷新，并在有效列表变化时发布ServerListChangeEvent。

4.2 地址规范化规则

有效地址列表在使用前必须规范化：

• 不带端口的地址使用 Nacos 默认服务器端口；
• 固定地址中的 HTTP/HTTPS 协议头为 HTTP 调用保留；
• gRPC 使用所选服务器端口加上配置的 gRPC 端口偏移量（grpc port offset）；
• context path 与 namespace 属于客户端身份的一部分，但不属于 gRPC 的 host/port 对。

4.3 动态列表刷新语义

动态刷新是本地且非权威的：它只改变客户端可连接的服务器，绝不改变 Config/Naming/AI/Lock 的资源状态。动态提供者收到变化后的流程为：

1. 原子替换本地列表；
2. 发布ServerListChangeEvent；
3. 现有 RPC 客户端检查当前服务器是否仍在列表中；
4. 若当前服务器已失效，RPC 客户端启动重连。

若使用固定列表，提供者不应发布刷新事件。

5. gRPC 连接生命周期与重连（Connection & Failover）

5.1 状态机

WAIT_INIT -> INITIALIZED -> STARTING -> RUNNING -> UNHEALTHY -> reconnect -> RUNNING -> SHUTDOWN

启动时应尝试一次初始同步连接。若在配置的重试预算内无法建立 RUNNING 连接，可以继续异步重连，但公共 SDK 调用必须按照领域契约暴露连接不可用状态。

5.2 何时触发重连

重连可由以下事件触发：

• 请求流错误或完成；
• 健康检查失败；
• 服务端显式 reset 请求；
• 服务器列表刷新将当前服务器排除；
• 请求失败且随后健康检查不成功；
• 客户端生命周期重启。

服务端 reset 请求可携带推荐的目标服务器：若该服务器仍在有效列表中，客户端可优先尝试；失败后回到正常的列表轮转（rotation）。

5.3 健康检查与半开连接检测

当连接在配置的 keepalive 窗口内处于空闲时，客户端周期性检查连接活性；失败的健康检查将 RPC 客户端标记为UNHEALTHY并调度重连。gRPC 传输层的 keepalive 用于抵御半开（half-open）TCP 连接，领域模块不应在 Naming/Config/AI/Lock 请求之上自行实现 gRPC 心跳，而应响应连接事件与领域推送。

5.4 HTTP 传输的定位

HTTP 仍是受支持的兼容传输，适用场景包括：

• 服务器不支持所需的 gRPC 能力；
• 操作属于遗留兼容操作；
• 公共 SDK 方法有意映射到 Open API；
• 功能不需要长连接推送或连接状态。

HTTP fallback 必须在领域客户端中显式声明：一次失败的 gRPC 请求不得自动通过 HTTP 变更资源状态，除非领域客户端定义了该 fallback。

5.5 TLS 与请求身份传播

客户端 gRPC TLS 属于传输基础设施，运行时可能支持：禁用 TLS 的明文通道、带协议与密码套件配置的 TLS 通道、受控测试环境的 trust-all 模式、生产环境的 trust collection 证书文件、以及带客户端证书链/私钥/私钥密码的双向 TLS。TLS 使能时，所选 Nacos 服务器必须在 gRPC 端口上支持 TLS；TLS 不匹配属于连接失败，而非领域操作失败。

身份传播方面：客户端侧认证插件通过运行时安全代理登录，并为每个请求资源提供LoginIdentityContext。运行时客户端必须在发送领域请求前将身份参数附加到 HTTP 或 gRPC 请求头。若服务器返回"无权限"且表明身份过期或无效，客户端可以标记登录上下文待刷新并按领域重试规则重试，但绝不能把授权失败伪装成本地缓存成功的读取结果。

5.6 失败可见性：failover 不等于已提交

连接 failover 只修复传输路径，不保证领域写入已被应用，除非收到了领域响应并完成校验。SDK 应区分五种情形：

• 连接不可用；
• 请求超时且服务端结果未知；
• 服务器拒绝了请求；
• 读取使用了本地 failover 或本地快照；
• 重连后 redo 尚未恢复运行时意图。

6. 能力协商：连接维度的特性门控（Ability Negotiation）

6.1 能力模型

能力（ability）是一个命名的布尔特性标志，按AbilityMode划定作用域：

能力名在同一 mode 内必须唯一。能力键定义本身就是连接双方的兼容性注册表。在源码中，能力键由 AbilityKey.java 枚举约束，其注释明确要求getName()在指定的AbilityMode下唯一。

6.2 当前 SDK 与服务端能力表

当前 Java SDK 声明支持：

当前服务器声明支持：

以 AbilityKey.java 中的实际定义为例，SERVER_FUZZY_WATCH的 wire key 为fuzzyWatch，SERVER_DISTRIBUTED_LOCK为lock，SERVER_MCP_REGISTRY为mcp，SERVER_AGENT_REGISTRY为agent，SERVER_AGENT_CARD_V1为agentCardV1。

6.3 Agent/RAD 能力（Nacos 3.3 线）

Agent API Spec 为 Nacos 3.3 线批准了以下服务端能力：SERVER_RAD_V1，wire key 为radV1，表示服务器接受完整的 Nacos 3.3 RAD v1 契约。首个subscribeAgent通过本地轮询 Discover 实现，不定义 SDK 客户端能力；未来的服务端 Watch/Push 设计必须单独评审其客户端能力、载荷与确认契约。遗留的SERVER_AGENT_REGISTRY、SERVER_AGENT_CARD_V1、SDK_AGENT_REGISTRY仅门控旧 A2A 契约，不是任何 RAD 操作的 fallback。

6.4 gRPC 协商流程

能力在 gRPC 连接建立期间协商：

1. 客户端向所选服务器打开 channel，发送ServerCheckRequest；
2. 服务器返回带连接 id 与"是否支持能力协商"标志的ServerCheckResponse；
3. 客户端打开双向流，发送带客户端版本、labels、namespace/tenant 与当前连接模式客户端能力表的ConnectionSetupRequest；
4. 若服务器支持能力协商，客户端等待SetupAckRequest；
5. SetupAckRequest携带服务端能力表，客户端将其存储在当前连接上；
6. 若服务器声明支持能力协商但在配置超时前未收到能力表，客户端必须放弃该连接尝试；
7. 若服务器不支持能力协商，客户端可出于兼容性完成 setup；该连接上的能力检查解析为UNKNOWN，除非实现定义了显式遗留 fallback。

这些请求对象在源码中均有对应：ServerCheckRequest、ConnectionSetupRequest、SetupAckRequest位于 api 模块的 remote/request 包。能力状态是连接维度的：重连创建新连接，必须刷新能力表。

6.5 能力状态语义与门控规则

客户端代码观察到的能力状态有三种：

UNKNOWN 不等于成功。新特性应优先选择快速失败的 unsupported 错误，而不是向可能无法理解的服务器发送请求。对应源码见 AbilityStatus.java。

领域客户端在使用可选或版本化特性前必须检查服务端能力，典型规则包括：

• Naming 持久化实例注册仅在SERVER_PERSISTENT_INSTANCE_BY_GRPC受支持时走 gRPC，否则使用文档化的 HTTP 兼容路径；
• Config 与 Naming 模糊监听必须要求SERVER_FUZZY_WATCH；
• 分布式锁必须要求SERVER_DISTRIBUTED_LOCK（该特性是实验性的，并非普遍可用）；
• AI MCP registry 操作必须要求SERVER_MCP_REGISTRY；
• RAD 的定义发布、Search/Discover 与运行时 Endpoint 发布必须要求SERVER_RAD_V1。

特性代码不应跨连接缓存能力肯定结果，应在操作即将执行时查询运行时连接能力。重连后必须先重新协商能力，再恢复 Endpoint 发布。

7. 本地缓存与 redo：断线恢复的运行时意图（Local Cache & Redo）

7.1 本地数据类别总览

除非领域规范显式说明，本地数据不得被视为服务端已提交状态。

7.2 Config 本地恢复与读取优先级

Config 读取优先级为：

1. 用户维护的本地 failover 文件；
2. 服务端查询；
3. 本地快照。

failover 文件不会由客户端自动创建，它仅用于应急场景：Nacos 服务器不可用或远程变更不安全时，应用必须用本地覆盖值启动或继续运行。快照在服务端查询成功后写入，并在服务端确认 Config 项不存在时移除；加密数据键快照与内容快照分开存储；Config 过滤器（含加密过滤器）在选定本地或远程内容之后应用。

监听器在发送监听检查前必须检查本地 failover 文件；failover 文件出现、变化或消失时，必须更新监听器状态，并按CacheDataMD5 规则决定是否触发监听器回调。

7.3 Config 监听器与模糊监听恢复

Config gRPC 客户端注册 Config 变更通知、客户端指标请求与模糊监听通知三类 handler。连接建立时须通知监听上下文与模糊监听上下文，使已知订阅被 resync；断连时须将受影响的CacheData条目与模糊监听上下文标记为与服务端不一致。Config 监听器恢复不是写入的 redo，而是读/监听运行时意图的 resync。

7.4 Naming 本地缓存与 failover 视图

Naming service-info 缓存以分组服务名 + 集群为键存储ServiceInfo对象。服务端推送或查询响应更新内存 map，并在实例视图变化时调度磁盘缓存刷新。缓存的定位是恢复辅助：可在启用 load-cache 选项时于启动加载；可在网络中断期间提供临时发现视图；磁盘缓存刷新是异步且与内存视图最终一致的；绝不能创建、更新或删除 Naming 服务端资源。Push-empty 保护可忽略空或无效推送，避免用意外空视图替换已知可用视图。

Naming failover 是本地发现覆盖：failover 开关开启且某服务存在有效 failover 数据时，SDK 返回 failover 视图而非正常服务端驱动视图。切换开关或变更数据导致可见实例集合变化时应发布实例变更事件。Naming failover不得用作服务端数据修复机制。

7.5 Redo 模型：重连后恢复运行时意图

Redo 数据记录四类信息：

• 期望的最终状态（如已注册/已注销）；
• 上一连接上是否已成功注册；
• 是否有注销操作正在进行；
• 重复操作所需的领域载荷。

Redo 操作包括：再次注册、再次注销、移除过期 redo 数据、当前运行时意图已满足时什么都不做。Redo 任务只在运行时连接已连接时执行；断连时已注册的 redo 数据必须标记为未注册，以便下一连接周期修复服务端挂载点。

源码层面，公共 redo 抽象由 AbstractRedoService.java 实现：它以ScheduledThreadPoolExecutor运行固定延迟的 redo 任务（默认延迟 3 秒、默认 1 个线程，见 Constants.java 中DEFAULT_REDO_DELAY_TIME与DEFAULT_REDO_THREAD_COUNT），实现ConnectionEventListener：onConnected置connected = true，onDisConnect将全部 redo 数据setRegistered(false)并记录 warn 日志。Naming 侧的具体实现为 NamingGrpcRedoService.java。

7.6 领域 redo 规则

• Naming redo覆盖：临时实例注册、批量临时实例注册、服务订阅、模糊监听一致性状态。持久化 Naming 服务状态归服务端所有，除非领域将操作显式视为运行时意图，否则不应由客户端 redo 恢复。
• AI redo覆盖运行时端点与订阅意图（如 MCP 或 Agent Endpoint 注册）；AI 资源发布/删除语义由 AI Registry Spec 管辖。
• Config监听器通过监听器 resync 与模糊监听 resync 恢复；Config 发布/删除操作不会由 Client SDK 自动 redo。

7.7 Agent/RAD 目标恢复契约（要点）

• Endpoint 发布 redo 身份：按发布身份(namespaceId, agentName, protocol)保存完整 Batch 载荷；Register 是原子的"整体替换"，不合并 upsert；Deregister 按 Endpoint 自然键移除成员。
• HTTP/gRPC 发布者恢复：HTTP Agent publisher 为 SDK 实例生成一个跨重试、切服、failover、心跳与 redo 保持稳定的X-Nacos-Client-Id；gRPC Endpoint 意图归当前连接 id 所有，重连后须在新连接下重放完整期望组。HTTP 与 gRPC 发布记录互相独立，一种传输不得注销另一种传输拥有的贡献。
• 本地软水位：默认保留 100 条 Runtime Endpoint 条目（可用nacosAiAgentEndpointMaxPublications配置）；本地轮询订阅缓存默认最多保留 300 个规范化订阅键（可用nacosAiAgentDiscoveryMaxSubscriptions配置）。容量拒绝是确定性的写入失败，被拒身份会从发布管理与 redo 缓存中移除。
• 本地轮询订阅身份：首个 SDK 不创建服务端 Watch，也不存储连接维度的watchKey；轮询键为(namespaceId, canonicalAgentReference, canonicalFilter, listenerIdentity)，gRPC 重连不会新增订阅 redo，因为下一次轮询天然使用新连接。
• 遗留 A2A 兼容恢复：命名空间绑定的A2aService使用(agentName, exactVersion)作为遗留 Endpoint 发布的本地 redo 身份，不同精确版本互不覆盖。

7.8 关闭（Shutdown）

SDK 关闭必须：清空内存 redo 状态、停止后台重试任务、关闭传输客户端、停止本地缓存/failover 刷新任务。关闭不应删除用户维护的 failover 文件或服务端派生的快照，除非用户显式调用缓存清理操作。

8. 推送与重连恢复：通知不是权威状态（Push & Reconnect）

8.1 推送的定位

推送消息只是通知运行时客户端"服务端视图可能已变化"，不能作为领域资源的唯一权威副本：

• Config 推送携带变更身份，客户端收到通知后必须查询Config 内容；
• Naming 推送携带订阅服务的当前发现视图，它仍是派生的服务状态，可通过重新查询或重新订阅刷新；
• AI 推送行为由各 AI 资源规范按版本定义，必须与对应查询 API 保持相同的身份规则；
• 目标 RAD Watch 携带完整发现快照，该快照对本地 RAD 发现缓存的替换是权威的，但 Registry 仍是资源权威，Discover 重查可刷新快照。

8.2 服务端连接状态清理

运行时监听器/订阅状态按服务端连接 id 隔离。连接关闭时服务端必须清理连接维度状态：Config 清除该连接的 config listen context 与 fuzzy watch context；Naming 移除连接客户端派生的已发布临时实例、订阅者与索引；AI 运行时端点与订阅状态遵循同样的连接归属规则。清理必须发布本地事件以更新派生索引与推送视图。

8.3 推送重试

推送重试是当前连接生命周期内的尽力而为投递：

• Config 常规变更推送使用ConfigChangeNotifyRequest，模糊监听推送使用模糊监听通知请求；重试次数受配置上限约束，超出上限服务端可能注销该连接以强制客户端恢复；
• Naming 服务变更推送通过按服务的合并延迟任务调度；失败推送可为目标客户端排队延迟重试，除非失败明确说明无需重试；重试不得变更 Naming 资源状态。

8.4 重连恢复与失败规则

重连后客户端必须恢复运行时意图：Config 在断连时标记监听器与模糊监听状态不一致、重连后 resync 已知监听器；Naming 断连时标记 redo 数据未注册、重连后 redo 临时注册与订阅；AI 运行时客户端在特性定义可重连状态时 redo 端点与订阅意图。

失败规则要点：缺失连接应取消或跳过该连接的推送；推送超时不能证明客户端未观察到变更，只说明服务端未及时收到成功 ack；客户端必须能通过重查、resync 或 redo 从遗漏推送中恢复；服务端推送不得隐藏底层查询路径中的授权失败。

8.5 排序语义

推送投递顺序限定在单节点的本地事件与任务路径内，不是跨集群的全局全序。领域规范各自定义本地服务视图何时可见：Config 写入可见性见 config-consistency-dump-visibility-spec.md；Naming 临时服务收敛见 naming-ephemeral-distro-consistency-spec.md；Naming 持久化服务与元数据可见性见 naming-persistent-cp-consistency-spec.md。

9. 领域对齐与插件对齐

9.1 领域对齐

• Config运行时行为：已知配置读取、监听器注册、模糊监听、本地 failover 文件、加密数据键快照与服务端查询快照；内容语义由 config-spec.md 定义。
• Naming运行时行为：服务订阅、推送处理、本地 service-info 缓存、failover 视图、临时实例 redo 与订阅者 redo；资源语义由 naming-spec.md 定义。
• AI运行时行为：端点注册、资源查询、订阅、能力检查与对快速演进的 AI 协议的兼容处理；资源语义由 ai-registry-spec.md 定义。
• 分布式锁：可选且实验性。客户端在发送锁操作前必须检查服务端锁能力；语义由 lock-spec.md 定义。

9.2 插件对齐

Client Runtime 可调用客户端侧插件：addressing 插件可参与服务器列表解析；auth 插件可登录并提供请求身份上下文；config encryption 插件可转换 Config 载荷与加密数据键。插件行为必须遵循 plugin/README.md；客户端运行时必须按对应插件契约处理插件失败，而不能把失败隐藏成领域成功。

10. 待解决问题与演进方向

规范明确标注的 Pending Issues 包括：

• 多语言 SDK 尚未在服务器列表刷新、failover、redo、能力协商与 TLS 行为上完全对齐；
• 客户端运行时指标与 trace 字段应遵循 foundation-observability-hooks-spec.md 的共享字段与标签指引；
• 客户端侧 auth、TLS 与加密行为若超出当前插件与连接契约，可能需要独立的子规范；
• 能力键公共列表应从源码生成以避免文档漂移；
• Naming redo 与 AI redo 应收敛到共享 redo 模型。

结语

Client Runtime 规范的价值在于把"SDK 如何活下来"这件事从各领域资源语义中剥离出来，形成一套跨 Config、Naming、AI 与分布式锁的共享运行时契约：地址解析与连接生命周期保证传输可达，能力协商保证跨版本兼容与特性门控，本地缓存与 failover 保证断网可用，redo 与推送恢复保证重连后意图不失。对于开发者而言，无论是排查"重连后订阅丢失""failover 未生效"还是"能力协商失败导致连接放弃"，都可以从 specs/en/client/ 下的五份规范文档及其引用的源码（AbilityKey.java、AbstractRedoService.java、NamingGrpcRedoService.java）中找到精确的语义依据。

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos