Nacos V3 HTTP API 全貌前缀体系、四大 API 家族与 Agent/MCP 生命周期契约解析【免费下载链接】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 仓库 v3-api-surface.md 为核心系统梳理 Nacos 3.x 在 Web context path 之后以/v3/client、/v3/admin、/v3/console、/v3/auth为前缀的 HTTP API 覆盖范围、实现位置与已批准契约。读完本文你将掌握 Nacos v3 HTTP API 的家族划分与鉴权域、Open/Admin/Console/Auth 四大 API 的已实现行为、Agent/RAD 与 MCP 生命周期管理面的路径与参数约定以及兼容性端点的废弃与重新开放策略可直接指导 SDK 集成、运维自动化与二次开发选型。1. V3 HTTP API 的定位与设计规则V3 HTTP API 是 Nacos 3.x 主发行版对外暴露的新一代 HTTP 接口体系。它与 HTTP API Spec定义设计规则、HTTP Authorization Spec定义端点鉴权、Response And Error Spec定义响应与错误形态三者互为补充本文描述覆盖范围与行为后三者定义如何设计与如何鉴权、响应。该体系有一个重要背景v1/v2 兼容 API 已不在主发行版中被外部化为独立的 nacos-api-legacy-adapter 适配器gRPC 请求/响应契约、未暴露为 v3 HTTP Controller 的内部集群 API以及拥有独立兼容面的 AI Registry 适配器 API均不在本文范围内。1.1 四大 API 前缀所有 v3 HTTP 端点的路径都在 Nacos web context path 之后以以下前缀之一开头前缀API 类型主要使用方当前鉴权范围/v3/clientOpen APISDK 与自定义客户端ApiType.OPEN_API/v3/adminAdmin API运维人员与 maintainer 工具ApiType.ADMIN_API/v3/consoleConsole APINacos 控制台 UI 的后端调用ApiType.CONSOLE_API/v3/authAuth 插件 API插件提供的鉴权与引导 APIdefault auth pluginApiType枚举在 api/src/main/java/com/alibaba/nacos/api/common/ApiType.java 中定义了ADMIN_API、CONSOLE_API、OPEN_API三种类型控制台、管理端、开放客户端三者的鉴权与流量治理互不混淆。2. 当前实现的事实来源Source of Truthv3 HTTP 行为目前由以下源码位置定义这是排查问题与阅读实现的入口领域代码来源Admin corecore/src/main/java/com/alibaba/nacos/core/controller/v3Admin configconfig/src/main/java/com/alibaba/nacos/config/server/controller/v3Admin namingnaming/src/main/java/com/alibaba/nacos/naming/controllers/v3Admin AIai/src/main/java/com/alibaba/nacos/ai/controllerConsoleconsole/src/main/java/com/alibaba/nacos/console/controller/v3Auth v3plugin-default-impl/nacos-default-auth-plugin/src/main/java/.../controller/v3路径常量Commons、configConstants、namingUtilsAndCommons、AIConstants、AuthConstants例如路径常量集中定义了各类前缀config 模块的 config/src/main/java/com/alibaba/nacos/config/server/constant/Constants.java 中BASE_ADMIN_V3_PATH /v3/admin/cs并派生/ops、/capacity、/config、/history、/listener、/metrics等管理端点Open API 侧CONFIG_V3_CLIENT_API_PATH /v3/client/cs/confignaming 模块的 naming/src/main/java/com/alibaba/nacos/naming/misc/UtilsAndCommons.java 中V3_CLIENT_API_PATH /v3/client、INSTANCE_V3_CLIENT_API_PATH /v3/client/ns/instanceAdmin 侧则定义了 service/instance/cluster/health/ops/client 六组管理路径AI 模块的 ai/src/main/java/com/alibaba/nacos/ai/constant/Constants.java 为 MCP、A2A、Agent、Skill、AgentSpec、Pipeline、Prompt 等资源统一生成/v3/admin、/v3/console、/v3/client三套前缀。此外文档原稿还记录了对应的网站源码文件admin/admin-api.md、admin/console-api.md、user/open-api.md用于对外发布时生成官方 API 手册。3. 当前 API 家族总览下表是脚本辅助统计的 Spring mapping 清单基于src/main/java下控制器注释的盘点应作为评审指南而非最终 OpenAPI 导出结果。统计口径以当前仓库为准家族约 mapping 数方法说明/v3/client/cs/config1GET自定义 HTTP 客户端查询配置/v3/client/ns/instance3GET, POST, DELETE注册、心跳、注销与列出服务实例/v3/client/ai/resources1GET协议无关的跨资源 Search/v3/client/ai/prompt2GET运行时 Prompt 查询与 Search/v3/client/ai/skills2GET运行时 Skill zip 下载与 Search/v3/client/ai/agentspecs2GET运行时 AgentSpec 获取与 Search/v3/client/ai/mcp1GET运行时 MCP Search/v3/admin/core/*25GET, POST, PUT, DELETELoader、集群、运维、命名空间、状态、插件/v3/admin/cs/*25GET, POST, PUT, DELETE配置 CRUD、历史、监听、容量、指标、运维/v3/admin/ns/*29GET, POST, PUT, DELETE服务、实例、客户端、集群、健康、运维/v3/admin/ai/*101GET, POST, PUT, DELETEMCP、A2A、Agent、Prompt、Skill、AgentSpec、Pipeline/v3/console/core/*7GET, POST, PUT, DELETE集群与命名空间控制台操作/v3/console/cs/*17GET, POST, DELETE配置与历史控制台操作/v3/console/ns/*11GET, POST, PUT, DELETENaming 控制台服务与实例操作/v3/console/ai/*79GET, POST, PUT, DELETE控制台 AI 管理、导入、生命周期、Pipeline/v3/console/copilot/*6GET, POST配置与 SSE Copilot 操作/v3/auth/user7GET, POST, PUT, DELETE默认 auth 插件中的用户登录与管理/v3/auth/role4GET, POST, DELETE默认 auth 插件中的角色管理/v3/auth/permission4GET, POST, DELETE默认 auth 插件中的权限管理/v3/auth/visibility2POST, DELETE默认 auth 插件中的插件自有可见性授权管理4. Open API 已实现行为Open API 是面向 SDK 与自定义客户端的稳定接口面默认鉴权域为ApiType.OPEN_API。已实现的端点及行为如下端点行为GET /v3/client/cs/config查询单个配置。不提供 HTTP 长轮询监听需走 gRPC。POST /v3/client/ns/instance注册实例当heartBeattrue时发送心跳。DELETE /v3/client/ns/instance注销实例实例不存在也返回成功。GET /v3/client/ns/instance/list列出服务的启用实例enabledfalse的实例会被过滤。GET /v3/client/ai/resources/search通过一个游标式 facade 搜索当前可见的 Agent、AgentSpec、Skill、Prompt 与 MCP 资源。GET /v3/client/ai/prompt按版本、标签或最新版本查询 Prompt。GET /v3/client/ai/prompt/search数字分页搜索当前可见的 Prompt。GET /v3/client/ai/skills以 zip 响应下载在线 Skill 包。GET /v3/client/ai/skills/search数字分页搜索当前可见的 Skill。GET /v3/client/ai/agentspecs按版本、标签或最新版本查询 AgentSpec可能允许匿名访问。GET /v3/client/ai/agentspecs/search搜索启用中的 AgentSpec 供运行时使用。GET /v3/client/ai/mcp/search以协议与能力过滤器搜索当前可见的 MCP Server。4.1 配置查询的源码实现GET /v3/client/cs/config由 config/src/main/java/com/alibaba/nacos/config/server/controller/v3/ConfigOpenApiController.java 实现。该控制器显式声明为不支持 gRPC 的编程语言提供获取远端配置的 HTTP 通道并遵循以下约定通过TpsControl(pointName ConfigQuery)接入统一限流通过Secured(action ActionTypes.READ, signType SignType.CONFIG, apiType ApiType.OPEN_API)声明读写类型、签名类型与 API 类型内部走ConfigQueryChainService查询链并将请求 IP 注入CLIENT_IP_LABEL从而支持 Beta 灰度规则与 Tag 灰度规则的命中检测命中灰度的响应会置betatrue或返回编码后的 tag配置未命中时返回RESOURCE_NOT_FOUND错误码并通过ConfigTraceService记录 PULL 事件PULL_TYPE_NOTFOUND/PULL_TYPE_OK。值得注意的是该控制器缺少多数 v3 控制器都有的NacosApi注解这一点被记录在文档缺口清单中见第 9 节Open API 文档假设其返回统一响应格式。4.2 实例注册 / 心跳 / 注销的源码实现/v3/client/ns/instance三端点由 naming/src/main/java/com/alibaba/nacos/naming/controllers/v3/InstanceOpenApiController.java 实现用于不支持 gRPC 的语言自注册/注销并获取实例列表同样不支持 HTTP 订阅订阅走 gRPC。关键行为POST接口通过heartBeat查询参数区分注册与心跳heartBeattrue时执行handleBeat若实例不存在则返回错误码INSTANCE_NOT_FOUND21003提示调用方应以heartBeatfalse重新注册DELETE接口注销实例实例不存在也返回成功remove successGET /list通过NamingInstanceListHttpParamExtractor做参数校验并明确过滤enabledfalse的实例——被禁用的实例视为已下线不应被客户端发现注册/注销均通过NotifyCenter发布RegisterInstanceTraceEvent/DeregisterInstanceTraceEvent追踪事件便于审计与可观测。5. Admin API 已实现行为Admin API 面向运维人员默认鉴权域为ApiType.ADMIN_API标准路径为/v3/admin/*。v1/v2 Admin API 已从当前 Nacos 主发行版中移除新集成应迁移到 v3 Admin API若迁移期间仍需要 v1/v2应使用 nacos-api-legacy-adapter。需要特别澄清的配置项nacos.core.auth.admin.enabled只控制 Admin API 鉴权是否启用它不是旧版 Admin API 的兼容开关。当前 Admin 模块划分core连接 Loader、集群节点数据、Raft 与 ID 运维、命名空间、插件、服务器状态cs配置 CRUD、元数据、批量操作、历史、监听、容量、指标与运维ns服务、实例、集群、健康、客户端与命名运维aiMCP、A2A、Agent、Prompt、Skill、AgentSpec 与 Pipeline 管理。5.1 值得显式文档化的行为命名服务创建会创建持久化服务元数据命名实例心跳复用同一POST /v3/client/ns/instance端点需要重新注册时返回INSTANCE_NOT_FOUND配置查询在返回 Admin API 详情前会先解密加密内容配置发布在未提供加密数据密钥且配置了加密处理器时会对内容进行加密AI Prompt在同一控制器中同时包含已废弃的兼容端点与较新的生命周期端点Agent 管理在/v3/admin/ai/agents下暴露定义 CRUD、有界的 Agent 与 Version 读取、草稿与 Version 生命周期操作、自定义标签以及只读的运行时 Endpoint 快照缺失或为空的namespaceId会被归一化为public插件详情在既有config字段中返回当前生效的插件配置并可能在不改变既有字段的前提下补充来源、覆盖状态等元数据插件配置更新保持完整覆盖映射替换语义运行时更新拒绝需要重启才生效的变更包括因省略导致的删除且仅从同一目标来源保留脱敏后的敏感输入若该来源无值则忽略脱敏项而不是创建覆盖已接受的来源更新若在插件应用阶段失败将返回明确的服务器错误且不会自动回滚。6. Console API 已实现行为Console API 服务于 Nacos Web 控制台不属于与 Open API 相同的稳定性面。它们默认鉴权域为ApiType.CONSOLE_API经常使用控制台专属资源名、ONLY_IDENTITY或面向 UI 的响应模型。控制台的部署、UI 与处理器边界由 Console Spec 定义。Console API 模块镜像了 UI 需要的 Admin 模块服务器状态与健康core 的集群、命名空间与插件配置与历史命名服务与实例AI 资源与 copilot。文档建议自动化用户应优先使用 Admin API除非某功能被刻意设计为仅控制台可用否则不要把仅控制台的端点当作推荐自动化 API 来使用。6.1 控制台专属的 MCP 导入辅助端点GET /v3/console/ai/mcp/importToolsFromMcp是一个控制台专属辅助端点它会从 Console 进程发起出站连接因此引入了额外的安全约束公共目标默认允许私有或本地目标需要运维配置nacos.console.ai.mcp.import.allowed-private-addressesIP/CIDR 允许列表运维可通过nacos.console.ai.mcp.import.enabled整体禁用该辅助端点。这三个配置共同构成了该出站能力的权限边界任何自动化脚本若需要调用该端点都应先确认上述配置已按安全基线设置。7. Auth API 已实现行为v3 Auth API位于默认 auth 插件中而非 core路径集中在四个子面/v3/auth/user /v3/auth/role /v3/auth/permission /v3/auth/visibility已实现行为用户管理创建、删除、修改密码、登录、列表与搜索角色管理新增、删除、列表与搜索权限管理新增、删除与列表可见性授权管理为显式资源可见性访问提供授权grant与撤销revoke首个管理员引导first-admin bootstrap由POST /v3/auth/user/admin实现。路径常量集中在 plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/constant/AuthConstants.java控制器分别位于.../controller/v3/下的UserControllerV3、RoleControllerV3、PermissionControllerV3与VisibilityGrantControllerV3。默认 auth 插件随 Nacos 一起发布因此其 v3 auth 端点应遵循 Nacos HTTP API 规则及 Auth Plugin Spec。8. 已批准的 Agent/RAD 面以下路径是来自 Agent API Spec 的已批准 Experimental 面。Admin 管理路径已包含在第 3 节的实现清单与控制器计数中而Client 传输绑定与 Console facade 仍属目标面直至其控制器、鉴权、传输绑定与测试落地。8.1 客户端目标路径方法路径契约GET/v3/client/ai/agents/search搜索 Agent 目录。GET/v3/client/ai/agents发现单个 Agent支持可选发现过滤器。POST/v3/client/ai/agents/endpoints替换当前发布者的完整运行时 Endpoint 批次。DELETE/v3/client/ai/agents/endpoints按 JSON body 标识移除当前发布者的整批运行时 Endpoint 发布。PUT/v3/client/ai/agents/endpoints/heartbeat刷新单个 HTTP 发布者客户端的存活状态。该目标面不新增Client HTTP Watch 或 Endpoint-list GET APIWatch 与推送使用协商后的 gRPC 绑定运行时检查使用 Admin 或 Console 的/runtime-endpoints路径。8.2 管理相对路径Admin 路径使用已实现的/v3/admin/ai/agents前缀Console 目标路径使用/v3/console/ai/agentsConsole 是同一相对管理契约之上的 UI facade相对路径方法契约(基础路径)GET, PUT, DELETE读取或更新 Agent 元数据或删除 Agent 定义。/listGET列出 Agent 摘要。/versionsGET列出 Version 摘要。/versionGET读取单个精确 Version 定义。/runtime-endpointsGET读取一份完整、不分页的运行时 Endpoint 快照。/draftPOST, PUT, DELETE创建新草稿元数据缺失时一并创建、更新当前草稿内容或删除草稿。/submitPOST提交草稿。/publishPOST发布已评审的 Version。/force-publishPOST执行经审计的 Pipeline 绕过。/redraftPOST将已评审 Version 退回草稿。/onlinePOST将离线 Version 上线。/offlinePOST将在线 Version 下线。/labelsPUT更新自定义 Version 标签。9. 已批准的 MCP 生命周期面以下路径是依据 MCP Server Spec 实现的 Experimental 管理面仅在单向 MCP 管理权达到LIFECYCLE_MANAGED之后可用在此切换之前有效请求会以RESOURCE_CONFLICT失败且不会变更遗留 MCP 状态。Admin 使用/v3/admin/ai/mcpConsole 使用/v3/console/ai/mcp作为同一相对生命周期契约的 UI facade相对路径方法契约/versionsGET列出有界的 MCP Version 元数据与生命周期状态。/versionGET读取单个精确 Version 内容与元数据。/draftPOST, PUT, DELETE创建草稿、仅更新当前草稿或删除草稿。/submitPOST通过常规发布 Pipeline 提交草稿。/publishPOST发布已评审的 Version。/force-publishPOST执行经审计的管理 Pipeline 绕过。/redraftPOST将已评审 Version 退回草稿。/onlinePOST将离线 Version 上线并使其成为最新。/offlinePOST将在线 Version 下线必要时修复 latest 指针。/labelsPUT更新自定义标签忽略客户端传入的latest。9.1 参数与响应约定所有路由使用form/query 参数公共身份字段namespaceId可选默认public、必填的mcpName以及除/versions与/labels外必填的精确version/versions额外接受可选的status以及有界的pageNo与pageSizePOST/PUT /draft额外接受必填 JSONserverSpecification以及可选的 JSONtoolSpecification、resourceSpecification、endpointSpecification外层的mcpName与version是规范来源serverSpecification中重复的名称或 Version 字段必须与之匹配且serverSpecification.id会被拒绝/labels接受 JSON 字符串 map空输入会清除自定义标签同时保留服务端管理的标签。9.2 响应模型与兼容性Version 列表结果使用PageMcpServerVersionSummary精确读取与草稿写入返回McpServerVersionDetail包含生命周期元数据与 Server/Tools/Resources 内容不含内部 MCP ID并投影出资源状态、owner、scope、标签、编辑/评审指针与在线 Version 数等生命周期感知管理端所需信息生命周期命令返回结果摘要草稿删除返回空成功结果标签替换返回生效后的标签 map既有 MCP 创建/更新/删除路径与参数形态保持为仅兼容的直接在线 facade不会被复制进新的生命周期形态特别是同 Version 内容覆盖仍只能通过历史更新路由完成。新的生命周期形态用namespaceId mcpName标识 Resource用额外的精确version标识 Version不引入mcpId。历史上已接受mcpId的 Admin、Console 与 Maintainer HTTP 输入仍是已废弃的兼容字段服务器通过AiResource.ext解析它们校验同时提供的名称并进入同一套基于名称的鉴权与生命周期服务既有响应 ID 字段保持线上兼容。该目标面不新增MCP Client HTTP 查询、发布、Endpoint、心跳或订阅路径——与既有 gRPC/Java Client 面的 HTTP 对等能力将推迟到生命周期托管完成后的独立设计中。在嵌入式或独立 Console 进程中Console facade 与 Admin 委托给同一个生命周期应用服务仅远程部署的 Console 需要下一阶段规划的 Maintainer 生命周期传输在该传输就绪前远程模式下这些新的 Console 生命周期路由返回API_FUNCTION_DISABLED而不是回退到遗留或基于 ID 的写入路径。10. 文档缺口记录非 Bug 清单以下条目并非缺陷清单而是记录当前文档与代码描述的表面对不一致便于读者在查阅官方文档时留意Admin AI Prompt 生命周期代码新增了/governance、/version、/draft、/submit、/publish、/force-publish、/online、/offline、/labels、/description、/biz-tags文档大多只覆盖遗留的/detail、/label、/metadata及列表与版本。Console AI Prompt 生命周期console 代码在/v3/console/ai/prompt下镜像了 Admin 生命周期文档大多只覆盖遗留/detail、/label、/metadata。Pipeline 列表/详情代码暴露/v3/*/ai/pipelines/list、/detail与/{pipelineId}文档展示的是/v3/*/ai/pipelines与/{pipelineId}。Force publish代码为 Prompt、Skill、AgentSpec 提供了POST /force-publish文档未一致描述这一特权操作。AgentSpec 版本元数据代码有GET /v3/admin/ai/agentspecs/version/meta未在 Admin API 文档中说明。Auth v3代码暴露/v3/auth/user、/role、/permission与/v3/auth/visibility三个网站 API 文件未覆盖该面。Config Open API 异常处理ConfigOpenApiController缺少多数 v3 控制器带有的NacosApiOpen API 文档假设统一响应。Config 与 Naming 异常处理器两模块仍有历史遗留的模块级ControllerAdvice可能返回纯文本错误体v3 API 应统一收敛到NacosApiExceptionHandler。11. 废弃兼容性说明部分 v3 AI API 在本规范出现之前就已发布随后被更清晰的生命周期或 REST 风格 API 取代这些旧端点应视为已废弃的兼容 APIAI Prompt 遗留端点如/detail、/label、/metadata不符合当前/list、/detail形态的 Pipeline 遗留 REST 风格端点。兼容端点在过渡期内可能继续可用但用户文档应将新 API 描述为主契约废弃端点只在兼容章节中配合迁移指引说明遵循 Compatibility And Deprecation Spec。具体到启用策略遗留 Pipeline 基础路径列表与路径变量详情端点连同POST /v3/console/ai/mcp/import/{validate|execute}默认禁用返回 HTTP410 Gone与API_DEPRECATED。运维可在过渡期通过nacos.core.api.compatibility.enabledtrue重新打开所有显式受限的 v3 兼容端点。注意旧的nacos.ai.resource.import.legacy-mcp-api-enabled属性已不再被读取迁移配置时应删除或忽略它。12. 集成建议与阅读指引结合以上内容面向不同角色的选型建议如下SDK / 自定义客户端开发者只依赖/v3/client/*Open API稳定面配置查询与实例注册/心跳/列表均可用纯 HTTP 完成需要监听配置或订阅服务时应切换至 gRPC 通道自动化与运维工具优先使用/v3/admin/*注意nacos.core.auth.admin.enabled仅控制 Admin 鉴权开关而非兼容开关涉及出站连接的 MCP 导入辅助端点需按nacos.console.ai.mcp.import.*三配置评估安全边界控制台/UI 开发者使用/v3/console/*但不要将仅控制台端点宣传为推荐自动化 APIMCP / Agent 资源治理在管理权达到LIFECYCLE_MANAGED后启用/v3/admin/ai/mcp、/v3/admin/ai/agents生命周期面所有写入都走草稿 → 提交 → 发布 → 上下线的受控流程。深度阅读时可按第 2 节的事实来源逐层深入先看 Constants.java 与 UtilsAndCommons.java 理解路径体系再对照core、config、naming、ai、console各模块controller/v3下的控制器实现最后用 v3-api-surface.md、api-spec.md、authorization-spec.md、response-error-spec.md 四份文档交叉核对契约与实现的一致性。【免费下载链接】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），仅供参考