Nacos 顶层设计规范深度解析从设计意图到资源模型、领域划分与模块架构【免费下载链接】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本文以仓库 specs/en/design/nacos-design-spec.md 为绝对主体结合 resource-model-spec.md、core-capabilities-spec.md、foundation-capabilities-spec.md 等配套规范与仓库源码展开。本文不是对 Nacos 全貌的泛泛介绍而是聚焦顶层设计意图这一层Nacos 为什么这样设计、资源如何被标识、领域如何划分、模块如何归属、一致性如何选型以及新特性如何被约束。读者读完可以掌握 Nacos 的资源层级模型、五大设计原则、五个核心领域、接口族与模块架构的对应关系以及判断一个新功能是否有资格成为稳定契约的完整检查清单。一、定位Nacos 是什么Nacos 是一个面向云原生与 AI 原生应用的动态服务发现、配置管理、服务管理与 AI 智能体Agent管理平台。它首先是为以服务为中心的应用架构提供的基础设施infrastructure。在 Nacos 的顶层设计语境里服务是一个广义概念可以是微服务microservice、RPC 服务可通过 DNS 发现的端点endpoint网关后端MCP ServerA2A AgentPrompt、Skill、AgentSpec等 AI 运行时资源也可以是任何需要被发现、需要动态配置、需要生命周期管理、需要治理、需要安全分发的运行时资源。这一服务即一等公民的定位直接决定了后续所有设计目标与领域划分——Nacos 不止管理微服务它把 AI 资源也纳入了同一套资源治理框架。二、设计目标六大目标Nacos 顶层设计明确提出了六个设计目标Design Goals易于注册/发现/配置/治理/观测让运行时资源容易被注册、发现、配置、治理和观测免重部署变更让应用可以在不重新部署的情况下修改配置、路由、发现策略以及 AI 资源选择例如将某个 Skill 的latest标签从版本 v3 重指到 v4统一控制面为配置、命名、服务元数据、AI 注册表AI Registry资源提供统一控制面多租户与多环境隔离通过命名空间namespace和权限边界支持多租户、多环境隔离生产级能力面向大规模集群与高并发负载保持生产级可用性开放生态通过标准协议、SDK、API 与插件扩展点保持开放生态。值得注意的是这六大目标与仓库根目录 README.md 中dynamic service discovery and configuration and service management的传统定位一脉相承但设计规范进一步把AI RegistryMCP Server、A2A Agent、Prompt、Skill、AgentSpec明确为与配置、命名平级的一等公民领域这正是当前版本2026 版权声明下的核心演进方向。三、设计原则六条约束一切实现的红线3.1 易用性Easy To UseNacos 应提供简单的 API、SDK、命令行工具与控制台工作流来完成常见运行时和管理任务。用户不需要理解内部存储、共识协议或传输细节就能正确使用 Nacos。这是一条对外隐藏复杂性的原则——后续所有领域规范、接口规范都以此为前提。3.2 面向标准Standards Oriented凡是业界已有标准与生态协议的地方Nacos 都应与之对齐包括云原生服务发现HTTP APIgRPC 传输MCPModel Context ProtocolA2AAgent-to-AgentKubernetes / Spring / Dubbo / Spring AI 集成模式。原则中有一条关键约束当 Nacos 增加协议适配层时Nacos 资源模型是内部语义的唯一真源source of semantic truth协议模型只是该模型的适配器adapters。也就是说MCP 模型、A2A AgentCard 模型等在内部都只是视图/适配不能反向定义资源语义。这一点在 resource-model-spec.md 与 AI Registry Spec 中会被反复强化。3.3 运行时动态Runtime DynamicNacos 资源预期会在运行时发生变化配置内容、服务实例、端点、AI 资源、标签、可见性、元数据都可能变化且无需应用重新部署。面向运行时的 API 与 SDK 应支持订阅subscription推送push本地缓存local cache安全的降级safe fallback。3.4 高可用High Availability单机模式standalone面向本地开发与测试场景集群模式cluster面向生产场景通过每个领域合适的一致性consistency与复制replication机制提供可用性与水平扩展。注意措辞通过每个领域合适的机制——不同领域配置、命名、AI、核心运维可以选用不同的一致性策略而不是一刀切。3.5 可扩展ExtensibleNacos 应保持清晰的模块边界并为横切关注点暴露插件扩展点认证authentication可见性visibility数据源datasource加密encryption链路追踪tracing控制control环境environmentAI 发布流水线AI publish pipelines。同时明确一条不可逾越的边界扩展不得重新定义核心资源身份、API 响应语义或授权边界。例如 plugin/ai 目录下的 AI 相关插件只能在资源语义之上做能力扩展而不能发明新的资源身份。3.6 安全与可治理Secure And GovernableNacos 管理着敏感的运行时与 AI 资产安全是设计的一部分而不是可选附加项受保护 API 的认证与授权应默认启用且显式化AI 资源应支持所有权ownership、可见性visibility、版本治理version governance、评审review、分发distribution与审计auditability宽泛的读与管理类 API 属于 Admin / Maintainer 面surface运行时客户端面应只暴露最小权限能力。从源码结构看这一原则已落地为 auth 模块与 plugin/auth 目录含默认认证插件、LDAP 插件、OIDC 插件以及 plugin/visibility 可见性插件具体语义由 specs/en/auth/auth-permission-spec.md 与 specs/en/auth/visibility-plugin-spec.md 定义。四、统一资源层级一切资源的身份骨架设计规范给出了 Nacos 所有资源的顶层统一层级NamespaceId - Group/resourceType - resourceName层级含义适用范围NamespaceId租户、团队、环境或管理域的隔离边界所有租户级资源Group/resourceType二级分类器微服务资源用GroupAI 资源用resourceType领域相关resourceName父作用域内标识具体资源的稳定名称所有具名资源规范特别强调Group与resourceType不是同一个字段Group是微服务资源的业务分组主要用于配置与命名资源resourceType是共享治理模型下资源的类型分类器主要用于 AI Registry 资源。由此衍生出两条资源模型分支微服务资源模型NamespaceId - Group - resourceNameAI 资源模型NamespaceId - resourceType - resourceName。版本version、标签label、状态status、可见性visibility、所有者owner与元数据metadata都是资源的治理属性除非领域规范明确声明否则不参与顶层三层身份。详细的层级语义、命名空间字段别名如tenant/tenantId、DEFAULT_GROUP默认值、各领域 concrete resourceName配置的dataId、命名的serviceName、MCP 的mcpName、Agent 的agentName、Prompt 的promptKey等见 specs/en/design/resource-model-spec.md。4.1 配置领域Configuration Domain管理以namespace group dataId标识的动态配置资源拥有配置内容、类型、md5、元数据监听器listener与模糊监听fuzzy watch灰度/测试gray/beta发布历史history、回滚rollback、转储dump与故障转移failover行为。详细规则由 specs/en/config/config-spec.md 定义。实现侧由 config 模块承载对外 API 由 api/src/main/java/com/alibaba/nacos/api/config/ConfigService.java 等 SDK 接口暴露。4.2 命名领域Naming Domain管理以namespace group serviceName标识的服务发现资源拥有服务元数据、实例、集群健康状态临时服务ephemeral与持久服务persistent语义订阅者、客户端视图与服务变更推送。详细规则由 specs/en/naming/naming-spec.md 定义实现位于 naming 模块SDK 接口见 api/src/main/java/com/alibaba/nacos/api/naming/NamingService.java。4.3 AI Registry 领域管理 MCP Server、A2A AgentCard、Prompt、Skill、AgentSpec 等 AI 资源顶层身份为NamespaceId - resourceType - resourceName。领域拥有AI 资源元数据、版本、标签、可见性、端点工具/Skill 描述符发布流水线状态下载/分发与面向审计的追踪信息。规范特别强调AI Registry 不是 Nacos 内部独立的产品模型而是 Nacos 的一等公民领域与配置、命名共用同一套命名空间、API、SDK、认证、插件与资源治理原则。实现侧可以从 ai/src/main/java/com/alibaba/nacos/ai/controller 下的控制器族得到印证McpAdminController/McpClientController、AgentAdminController/AgentClientController、PromptAdminController/PromptClientController、SkillAdminController/SkillClientController、AgentSpecAdminController/AgentSpecClientController分别对应 Admin 与 Client 两个 API 面持久化层见 ai/src/main/java/com/alibaba/nacos/ai/service/repository/AiResourcePersistService.java。详细规范见 specs/en/ai/ai-registry-spec.md。4.4 核心与运维领域Core And Operation Domain拥有命名空间管理、集群成员、服务器状态、就绪/存活readiness/liveness、服务器生命周期与环境、连接管理、请求过滤与运行时上下文、内部 RPC、日志级别操作、插件状态等控制面资源。这些能力本质上是管理性质的应通过 Admin API、Console API 或 Maintainer SDK 暴露而不是运行时 Client SDK 面。对应规范见 specs/en/core/core-operations-spec.md 与 specs/en/design 目录下的 foundation 系列子规范。4.5 安全与可见性领域Security And Visibility Domain拥有认证、授权、身份传播、API 分类、动作分类与可见性执行并且应一致地应用于 HTTP API、gRPC 调用、SDK、控制台操作与插件提供的 API。这解释了为什么仓库中 auth 是一个独立模块而非散落在各领域内——安全是横切关注点。五、接口架构同一套资源语义多族接口Nacos 通过多个接口族暴露相同的资源语义接口族定位HTTP APIOpen / Admin / Console / Auth / 插件 APIgRPC API高频运行时通信、推送、订阅、客户端-服务器控制消息Client SDK运行时应用与 Agent 框架使用Maintainer SDK管理、UI、网关与运维集成使用Console 与 CLI人与自动化工作流关键约束接口可以使用不同的传输模型但必须保持相同的资源身份、校验、授权、生命周期与错误语义。例如配置资源在 HTTP 与 gRPC 下的dataId必须指向同一个资源。相关接口规范见 specs/en/http-api/api-spec.md、specs/en/grpc-api/api-spec.md、specs/en/sdk/sdk-spec.md。从源码印证AI 领域同时存在 HTTP 控制器ai/src/main/java/com/alibaba/nacos/ai/controller与 gRPC 请求处理器ai/src/main/java/com/alibaba/nacos/ai/remote/handler两者共享同一套OperationService/PersistService业务层正是同一语义、多传输的落地形态。六、模块架构所有权规则设计规范为每个顶层模块划定了明确的所有权api、client、client-basic定义公开客户端模型、SDK 接口与传输契约对应仓库 api、client、client-basic 目录config、naming、ai拥有各自资源的领域行为config、naming、aicore拥有集群、命名空间、服务器、插件与运维基础corecommon、consistency、persistence提供事件、任务、AP/CP 协议与存储等共享基础能力common、consistency、persistenceauth与插件模块拥有可扩展的安全与策略行为auth、pluginmaintainer-client在 Admin API 语义之上提供类型化的 Java 管理入口maintainer-clientconsole暴露面向 UI 的后端 API不得独立重新定义领域语义console。规范同时给出两条模块治理规则共享模型应放在其 API 兼容性要求明确的地方服务器专属实现细节不得泄漏进公开 SDK 契约。这两条规则与上文协议模型是资源模型的适配器一脉相承保证客户端 SDK 不受服务端存储/共识实现变更的影响。七、一致性与存储按资源语义选型设计规范明确每个领域应根据资源语义选择一致性与存储行为资源类型一致性/存储要求配置资源需要持久化存储、版本/历史感知、可靠的变更通知命名资源需要快速运行时更新、健康驱动的可用性、清晰的临时/持久语义AI 资源需要持久化元数据、不可变已发布版本如适用、基于标签的路由、可见性与评审/审计元数据服务器与集群资源需要显式的管理控制与运维安全实现上可以使用数据库持久化、本地缓存、Distro、Raft或其他机制但公开语义必须由领域规范表达而不是由存储实现细节表达。这是一个语义与实现解耦的强约束存储选型属于 foundation 层能力领域规范负责决策与约束。在 specs/en/design/foundation-capabilities-spec.md 中选型被进一步归纳为一张决策表运行时、高频、客户端持有、一次性、最终收敛状态→ AP 一致性Distro 风格协议持久化、管理持有、可快照恢复、强有序状态→ CP 一致性Raft/JRaft 风格协议带本地服务缓存的持久化数据库状态→ 持久化 dump 领域定义的缓存失效。源码侧可以找到对应的协议实现AP 路径 core/src/main/java/com/alibaba/nacos/core/distributed/distro/DistroProtocol.javasync/onQuery/onSnapshot等方法对应 Distro 数据同步、查询与快照CP 路径 core/src/main/java/com/alibaba/nacos/core/distributed/raft/JRaftProtocol.javawrite/getData/memberChange/shutdown对应强有序写入、读取、成员变更与关闭协议路由 core/src/main/java/com/alibaba/nacos/core/distributed/ProtocolManager.javagetCpProtocol()/getApProtocol()供领域按需取用。规范还提醒协议选择是语义决策领域不能因为实现路径方便就随意使用 Distro 或 Raft。共享基础能力服务器生命周期、成员、连接生命周期、请求过滤、内部 RPC、AP/CP 一致性、持久化与 dump、任务执行、事件分发、观测钩子的完整边界由 specs/en/design/foundation-capabilities-spec.md 及其子规范定义。7.1 请求过滤与运行时上下文源码佐证在设计规范中请求过滤与运行时上下文是 foundation 层的关键能力之一HTTP 与 gRPC 入口必须填充RequestContext协议、目标、身份、应用、用户代理、远端地址等认证、控制、参数检查与命名空间校验是横切守卫而非领域实现。源码印证core/src/main/java/com/alibaba/nacos/core/context/RequestContext.java请求上下文模型core/src/main/java/com/alibaba/nacos/core/paramcheck/ParamCheckerFilter.javaHTTP 参数校验过滤器doFilter中校验失败时通过generate400Response返回 400参数抽取器族McpServerRequestParamExtractor、ConfigRequestParamExtractor、PromptRequestParamExtractor、AgentRequestParamExtractor、InstanceRequestParamExtractor等与ExtractorManager/ParamExtractor接口共同组成公共结构校验下沉到共享过滤器与抽取器领域校验留在领域表单/请求/服务/处理器的分层实现。八、新特性设计规则成为稳定契约的八问设计规范最后给出了一套新特性准入门槛。每一个新的 Nacos 特性都必须定义拥有该特性的领域domain资源类型与资源身份resource type identity该特性是运行时面向、管理面向还是两者兼具API 受众Open / Admin / Console / Auth / 插件 / gRPC / Client SDK / Maintainer SDK相关的命名空间、组、版本、标签、状态与可见性行为认证、授权与审计要求对现有 API 与 SDK 的兼容性与弃用影响使规范可执行的测试或校验规则。规范以一句极具约束力的话收尾如果一个特性无法回答这些问题它就没有准备好成为 Nacos 的稳定契约stable Nacos contract。配套的 specs/en/design/core-capabilities-spec.md 将能力组织为设计意图 - 资源模型 - 基础能力 - 领域能力 - HTTP/gRPC/SDK 接口 - 扩展与安全规则六个层次并给出了能力边界检查清单拥有领域与模块、资源身份与第二层是groupName还是resourceType、受众、暴露面、持久化/缓存/事件/一致性/恢复预期、安全要求、兼容性影响。此外specs/en/design/resource-model-spec.md 第十节新资源检查清单与 specs/en/design/foundation-capabilities-spec.md 第十二节基础边界规则共同构成三层约束任何新资源、新能力、新基础设施都不能越界重新定义资源身份与领域语义。九、总结与阅读路径Nacos 顶层设计规范的价值不在于罗列功能而在于建立一套从设计意图到具体实现的约束链条设计原则约束一切实现的红线易用、面向标准、运行时动态、高可用、可扩展、安全可治理统一资源层级NamespaceId - Group/resourceType - resourceName是所有领域的身份骨架五个领域配置、命名、AI Registry、核心运维、安全可见性各司其职AI Registry 是复用了同一套治理原则的一等公民领域五族接口共享同一资源语义模块所有权明确、服务器细节不泄漏进 SDK一致性与存储按资源语义选型AP/Distro、CP/Raft、持久化dump语义表达在领域规范而非存储实现新特性八问确保任何新增功能在成为稳定契约前完成领域、身份、受众、安全与兼容性论证。建议的进一步阅读顺序资源身份细化specs/en/design/resource-model-spec.md能力分层与领域清单specs/en/design/core-capabilities-spec.md基础能力清单与协议选型specs/en/design/foundation-capabilities-spec.md各领域详细规范specs/en/config/config-spec.md、specs/en/naming/naming-spec.md、specs/en/ai/ai-registry-spec.md、specs/en/core/core-operations-spec.md接口规范specs/en/http-api/api-spec.md、specs/en/grpc-api/api-spec.md、specs/en/sdk/sdk-spec.md对应实现源码apiSDK 契约、core集群/共识/过滤、config配置领域、naming命名领域、aiAI Registry 领域、plugin扩展点。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nacos 顶层设计规范深度解析：从设计意图到资源模型、领域划分与模块架构
Nacos 顶层设计规范深度解析从设计意图到资源模型、领域划分与模块架构【免费下载链接】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本文以仓库 specs/en/design/nacos-design-spec.md 为绝对主体结合 resource-model-spec.md、core-capabilities-spec.md、foundation-capabilities-spec.md 等配套规范与仓库源码展开。本文不是对 Nacos 全貌的泛泛介绍而是聚焦顶层设计意图这一层Nacos 为什么这样设计、资源如何被标识、领域如何划分、模块如何归属、一致性如何选型以及新特性如何被约束。读者读完可以掌握 Nacos 的资源层级模型、五大设计原则、五个核心领域、接口族与模块架构的对应关系以及判断一个新功能是否有资格成为稳定契约的完整检查清单。一、定位Nacos 是什么Nacos 是一个面向云原生与 AI 原生应用的动态服务发现、配置管理、服务管理与 AI 智能体Agent管理平台。它首先是为以服务为中心的应用架构提供的基础设施infrastructure。在 Nacos 的顶层设计语境里服务是一个广义概念可以是微服务microservice、RPC 服务可通过 DNS 发现的端点endpoint网关后端MCP ServerA2A AgentPrompt、Skill、AgentSpec等 AI 运行时资源也可以是任何需要被发现、需要动态配置、需要生命周期管理、需要治理、需要安全分发的运行时资源。这一服务即一等公民的定位直接决定了后续所有设计目标与领域划分——Nacos 不止管理微服务它把 AI 资源也纳入了同一套资源治理框架。二、设计目标六大目标Nacos 顶层设计明确提出了六个设计目标Design Goals易于注册/发现/配置/治理/观测让运行时资源容易被注册、发现、配置、治理和观测免重部署变更让应用可以在不重新部署的情况下修改配置、路由、发现策略以及 AI 资源选择例如将某个 Skill 的latest标签从版本 v3 重指到 v4统一控制面为配置、命名、服务元数据、AI 注册表AI Registry资源提供统一控制面多租户与多环境隔离通过命名空间namespace和权限边界支持多租户、多环境隔离生产级能力面向大规模集群与高并发负载保持生产级可用性开放生态通过标准协议、SDK、API 与插件扩展点保持开放生态。值得注意的是这六大目标与仓库根目录 README.md 中dynamic service discovery and configuration and service management的传统定位一脉相承但设计规范进一步把AI RegistryMCP Server、A2A Agent、Prompt、Skill、AgentSpec明确为与配置、命名平级的一等公民领域这正是当前版本2026 版权声明下的核心演进方向。三、设计原则六条约束一切实现的红线3.1 易用性Easy To UseNacos 应提供简单的 API、SDK、命令行工具与控制台工作流来完成常见运行时和管理任务。用户不需要理解内部存储、共识协议或传输细节就能正确使用 Nacos。这是一条对外隐藏复杂性的原则——后续所有领域规范、接口规范都以此为前提。3.2 面向标准Standards Oriented凡是业界已有标准与生态协议的地方Nacos 都应与之对齐包括云原生服务发现HTTP APIgRPC 传输MCPModel Context ProtocolA2AAgent-to-AgentKubernetes / Spring / Dubbo / Spring AI 集成模式。原则中有一条关键约束当 Nacos 增加协议适配层时Nacos 资源模型是内部语义的唯一真源source of semantic truth协议模型只是该模型的适配器adapters。也就是说MCP 模型、A2A AgentCard 模型等在内部都只是视图/适配不能反向定义资源语义。这一点在 resource-model-spec.md 与 AI Registry Spec 中会被反复强化。3.3 运行时动态Runtime DynamicNacos 资源预期会在运行时发生变化配置内容、服务实例、端点、AI 资源、标签、可见性、元数据都可能变化且无需应用重新部署。面向运行时的 API 与 SDK 应支持订阅subscription推送push本地缓存local cache安全的降级safe fallback。3.4 高可用High Availability单机模式standalone面向本地开发与测试场景集群模式cluster面向生产场景通过每个领域合适的一致性consistency与复制replication机制提供可用性与水平扩展。注意措辞通过每个领域合适的机制——不同领域配置、命名、AI、核心运维可以选用不同的一致性策略而不是一刀切。3.5 可扩展ExtensibleNacos 应保持清晰的模块边界并为横切关注点暴露插件扩展点认证authentication可见性visibility数据源datasource加密encryption链路追踪tracing控制control环境environmentAI 发布流水线AI publish pipelines。同时明确一条不可逾越的边界扩展不得重新定义核心资源身份、API 响应语义或授权边界。例如 plugin/ai 目录下的 AI 相关插件只能在资源语义之上做能力扩展而不能发明新的资源身份。3.6 安全与可治理Secure And GovernableNacos 管理着敏感的运行时与 AI 资产安全是设计的一部分而不是可选附加项受保护 API 的认证与授权应默认启用且显式化AI 资源应支持所有权ownership、可见性visibility、版本治理version governance、评审review、分发distribution与审计auditability宽泛的读与管理类 API 属于 Admin / Maintainer 面surface运行时客户端面应只暴露最小权限能力。从源码结构看这一原则已落地为 auth 模块与 plugin/auth 目录含默认认证插件、LDAP 插件、OIDC 插件以及 plugin/visibility 可见性插件具体语义由 specs/en/auth/auth-permission-spec.md 与 specs/en/auth/visibility-plugin-spec.md 定义。四、统一资源层级一切资源的身份骨架设计规范给出了 Nacos 所有资源的顶层统一层级NamespaceId - Group/resourceType - resourceName层级含义适用范围NamespaceId租户、团队、环境或管理域的隔离边界所有租户级资源Group/resourceType二级分类器微服务资源用GroupAI 资源用resourceType领域相关resourceName父作用域内标识具体资源的稳定名称所有具名资源规范特别强调Group与resourceType不是同一个字段Group是微服务资源的业务分组主要用于配置与命名资源resourceType是共享治理模型下资源的类型分类器主要用于 AI Registry 资源。由此衍生出两条资源模型分支微服务资源模型NamespaceId - Group - resourceNameAI 资源模型NamespaceId - resourceType - resourceName。版本version、标签label、状态status、可见性visibility、所有者owner与元数据metadata都是资源的治理属性除非领域规范明确声明否则不参与顶层三层身份。详细的层级语义、命名空间字段别名如tenant/tenantId、DEFAULT_GROUP默认值、各领域 concrete resourceName配置的dataId、命名的serviceName、MCP 的mcpName、Agent 的agentName、Prompt 的promptKey等见 specs/en/design/resource-model-spec.md。4.1 配置领域Configuration Domain管理以namespace group dataId标识的动态配置资源拥有配置内容、类型、md5、元数据监听器listener与模糊监听fuzzy watch灰度/测试gray/beta发布历史history、回滚rollback、转储dump与故障转移failover行为。详细规则由 specs/en/config/config-spec.md 定义。实现侧由 config 模块承载对外 API 由 api/src/main/java/com/alibaba/nacos/api/config/ConfigService.java 等 SDK 接口暴露。4.2 命名领域Naming Domain管理以namespace group serviceName标识的服务发现资源拥有服务元数据、实例、集群健康状态临时服务ephemeral与持久服务persistent语义订阅者、客户端视图与服务变更推送。详细规则由 specs/en/naming/naming-spec.md 定义实现位于 naming 模块SDK 接口见 api/src/main/java/com/alibaba/nacos/api/naming/NamingService.java。4.3 AI Registry 领域管理 MCP Server、A2A AgentCard、Prompt、Skill、AgentSpec 等 AI 资源顶层身份为NamespaceId - resourceType - resourceName。领域拥有AI 资源元数据、版本、标签、可见性、端点工具/Skill 描述符发布流水线状态下载/分发与面向审计的追踪信息。规范特别强调AI Registry 不是 Nacos 内部独立的产品模型而是 Nacos 的一等公民领域与配置、命名共用同一套命名空间、API、SDK、认证、插件与资源治理原则。实现侧可以从 ai/src/main/java/com/alibaba/nacos/ai/controller 下的控制器族得到印证McpAdminController/McpClientController、AgentAdminController/AgentClientController、PromptAdminController/PromptClientController、SkillAdminController/SkillClientController、AgentSpecAdminController/AgentSpecClientController分别对应 Admin 与 Client 两个 API 面持久化层见 ai/src/main/java/com/alibaba/nacos/ai/service/repository/AiResourcePersistService.java。详细规范见 specs/en/ai/ai-registry-spec.md。4.4 核心与运维领域Core And Operation Domain拥有命名空间管理、集群成员、服务器状态、就绪/存活readiness/liveness、服务器生命周期与环境、连接管理、请求过滤与运行时上下文、内部 RPC、日志级别操作、插件状态等控制面资源。这些能力本质上是管理性质的应通过 Admin API、Console API 或 Maintainer SDK 暴露而不是运行时 Client SDK 面。对应规范见 specs/en/core/core-operations-spec.md 与 specs/en/design 目录下的 foundation 系列子规范。4.5 安全与可见性领域Security And Visibility Domain拥有认证、授权、身份传播、API 分类、动作分类与可见性执行并且应一致地应用于 HTTP API、gRPC 调用、SDK、控制台操作与插件提供的 API。这解释了为什么仓库中 auth 是一个独立模块而非散落在各领域内——安全是横切关注点。五、接口架构同一套资源语义多族接口Nacos 通过多个接口族暴露相同的资源语义接口族定位HTTP APIOpen / Admin / Console / Auth / 插件 APIgRPC API高频运行时通信、推送、订阅、客户端-服务器控制消息Client SDK运行时应用与 Agent 框架使用Maintainer SDK管理、UI、网关与运维集成使用Console 与 CLI人与自动化工作流关键约束接口可以使用不同的传输模型但必须保持相同的资源身份、校验、授权、生命周期与错误语义。例如配置资源在 HTTP 与 gRPC 下的dataId必须指向同一个资源。相关接口规范见 specs/en/http-api/api-spec.md、specs/en/grpc-api/api-spec.md、specs/en/sdk/sdk-spec.md。从源码印证AI 领域同时存在 HTTP 控制器ai/src/main/java/com/alibaba/nacos/ai/controller与 gRPC 请求处理器ai/src/main/java/com/alibaba/nacos/ai/remote/handler两者共享同一套OperationService/PersistService业务层正是同一语义、多传输的落地形态。六、模块架构所有权规则设计规范为每个顶层模块划定了明确的所有权api、client、client-basic定义公开客户端模型、SDK 接口与传输契约对应仓库 api、client、client-basic 目录config、naming、ai拥有各自资源的领域行为config、naming、aicore拥有集群、命名空间、服务器、插件与运维基础corecommon、consistency、persistence提供事件、任务、AP/CP 协议与存储等共享基础能力common、consistency、persistenceauth与插件模块拥有可扩展的安全与策略行为auth、pluginmaintainer-client在 Admin API 语义之上提供类型化的 Java 管理入口maintainer-clientconsole暴露面向 UI 的后端 API不得独立重新定义领域语义console。规范同时给出两条模块治理规则共享模型应放在其 API 兼容性要求明确的地方服务器专属实现细节不得泄漏进公开 SDK 契约。这两条规则与上文协议模型是资源模型的适配器一脉相承保证客户端 SDK 不受服务端存储/共识实现变更的影响。七、一致性与存储按资源语义选型设计规范明确每个领域应根据资源语义选择一致性与存储行为资源类型一致性/存储要求配置资源需要持久化存储、版本/历史感知、可靠的变更通知命名资源需要快速运行时更新、健康驱动的可用性、清晰的临时/持久语义AI 资源需要持久化元数据、不可变已发布版本如适用、基于标签的路由、可见性与评审/审计元数据服务器与集群资源需要显式的管理控制与运维安全实现上可以使用数据库持久化、本地缓存、Distro、Raft或其他机制但公开语义必须由领域规范表达而不是由存储实现细节表达。这是一个语义与实现解耦的强约束存储选型属于 foundation 层能力领域规范负责决策与约束。在 specs/en/design/foundation-capabilities-spec.md 中选型被进一步归纳为一张决策表运行时、高频、客户端持有、一次性、最终收敛状态→ AP 一致性Distro 风格协议持久化、管理持有、可快照恢复、强有序状态→ CP 一致性Raft/JRaft 风格协议带本地服务缓存的持久化数据库状态→ 持久化 dump 领域定义的缓存失效。源码侧可以找到对应的协议实现AP 路径 core/src/main/java/com/alibaba/nacos/core/distributed/distro/DistroProtocol.javasync/onQuery/onSnapshot等方法对应 Distro 数据同步、查询与快照CP 路径 core/src/main/java/com/alibaba/nacos/core/distributed/raft/JRaftProtocol.javawrite/getData/memberChange/shutdown对应强有序写入、读取、成员变更与关闭协议路由 core/src/main/java/com/alibaba/nacos/core/distributed/ProtocolManager.javagetCpProtocol()/getApProtocol()供领域按需取用。规范还提醒协议选择是语义决策领域不能因为实现路径方便就随意使用 Distro 或 Raft。共享基础能力服务器生命周期、成员、连接生命周期、请求过滤、内部 RPC、AP/CP 一致性、持久化与 dump、任务执行、事件分发、观测钩子的完整边界由 specs/en/design/foundation-capabilities-spec.md 及其子规范定义。7.1 请求过滤与运行时上下文源码佐证在设计规范中请求过滤与运行时上下文是 foundation 层的关键能力之一HTTP 与 gRPC 入口必须填充RequestContext协议、目标、身份、应用、用户代理、远端地址等认证、控制、参数检查与命名空间校验是横切守卫而非领域实现。源码印证core/src/main/java/com/alibaba/nacos/core/context/RequestContext.java请求上下文模型core/src/main/java/com/alibaba/nacos/core/paramcheck/ParamCheckerFilter.javaHTTP 参数校验过滤器doFilter中校验失败时通过generate400Response返回 400参数抽取器族McpServerRequestParamExtractor、ConfigRequestParamExtractor、PromptRequestParamExtractor、AgentRequestParamExtractor、InstanceRequestParamExtractor等与ExtractorManager/ParamExtractor接口共同组成公共结构校验下沉到共享过滤器与抽取器领域校验留在领域表单/请求/服务/处理器的分层实现。八、新特性设计规则成为稳定契约的八问设计规范最后给出了一套新特性准入门槛。每一个新的 Nacos 特性都必须定义拥有该特性的领域domain资源类型与资源身份resource type identity该特性是运行时面向、管理面向还是两者兼具API 受众Open / Admin / Console / Auth / 插件 / gRPC / Client SDK / Maintainer SDK相关的命名空间、组、版本、标签、状态与可见性行为认证、授权与审计要求对现有 API 与 SDK 的兼容性与弃用影响使规范可执行的测试或校验规则。规范以一句极具约束力的话收尾如果一个特性无法回答这些问题它就没有准备好成为 Nacos 的稳定契约stable Nacos contract。配套的 specs/en/design/core-capabilities-spec.md 将能力组织为设计意图 - 资源模型 - 基础能力 - 领域能力 - HTTP/gRPC/SDK 接口 - 扩展与安全规则六个层次并给出了能力边界检查清单拥有领域与模块、资源身份与第二层是groupName还是resourceType、受众、暴露面、持久化/缓存/事件/一致性/恢复预期、安全要求、兼容性影响。此外specs/en/design/resource-model-spec.md 第十节新资源检查清单与 specs/en/design/foundation-capabilities-spec.md 第十二节基础边界规则共同构成三层约束任何新资源、新能力、新基础设施都不能越界重新定义资源身份与领域语义。九、总结与阅读路径Nacos 顶层设计规范的价值不在于罗列功能而在于建立一套从设计意图到具体实现的约束链条设计原则约束一切实现的红线易用、面向标准、运行时动态、高可用、可扩展、安全可治理统一资源层级NamespaceId - Group/resourceType - resourceName是所有领域的身份骨架五个领域配置、命名、AI Registry、核心运维、安全可见性各司其职AI Registry 是复用了同一套治理原则的一等公民领域五族接口共享同一资源语义模块所有权明确、服务器细节不泄漏进 SDK一致性与存储按资源语义选型AP/Distro、CP/Raft、持久化dump语义表达在领域规范而非存储实现新特性八问确保任何新增功能在成为稳定契约前完成领域、身份、受众、安全与兼容性论证。建议的进一步阅读顺序资源身份细化specs/en/design/resource-model-spec.md能力分层与领域清单specs/en/design/core-capabilities-spec.md基础能力清单与协议选型specs/en/design/foundation-capabilities-spec.md各领域详细规范specs/en/config/config-spec.md、specs/en/naming/naming-spec.md、specs/en/ai/ai-registry-spec.md、specs/en/core/core-operations-spec.md接口规范specs/en/http-api/api-spec.md、specs/en/grpc-api/api-spec.md、specs/en/sdk/sdk-spec.md对应实现源码apiSDK 契约、core集群/共识/过滤、config配置领域、naming命名领域、aiAI Registry 领域、plugin扩展点。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考