尧图网页设计 
Nacos 插件规范全景扩展点分类、SPI 层次、加载生命周期与统一配置管理实战指南【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos 通过一套统一的插件机制与 SPI 扩展将鉴权、资源可见性、数据源方言、加解密、链路追踪、流量控制、环境适配乃至 AI pipeline、AI 存储、AI 资源导入等横切与可替换能力从固定核心中拆出让不同部署环境可以按自身身份系统、数据库、观测体系或扩展场景选择实现。本文以 specs/zh-cn/plugin/README.md 定义的插件规范框架为主线结合核心规范 specs/zh-cn/plugin/plugin-spec.md 与仓库源码系统讲解插件身份模型、类型注册表、执行形态、SPI 层次、加载生命周期、统一状态与配置模型以及管理 API读完即可理解如何判断一个扩展点属于哪类插件、如何加载、如何配置、如何被管理。插件规范的定位与总体框架插件规范定义 Nacos 扩展点如何加载、选择、执行、配置以及如何通过统一插件管理模型对外暴露。它扩展 Nacos 设计规范必须保持 资源模型 语义稳定并在暴露 HTTP 端点时遵守 HTTP API 规则。插件机制是扩展边界不是绕过 Nacos 资源、API 或安全规则的通道。整个插件规范树按功能域划分为五大类这也是插件扩展点全景图通用模型Nacos 插件化规范所有插件共享的运行时契约、寻址扩展规范。数据与配置数据源方言插件规范、默认数据源方言插件实现规范、配置变更插件规范、配置加密插件规范。运行时扩展环境插件规范、Trace 插件规范、Control 插件规范、默认 Control 插件实现规范。AI 扩展AI 发布 Pipeline 插件规范、AI 存储插件规范、AI Vector 插件规范、AI 资源导入插件规范。安全扩展鉴权插件规范、RAM 鉴权插件规范、OIDC 鉴权插件规范、可见性插件规范。其中 寻址扩展规范 是为了和公开插件文档保持连续性而放在插件规范树中记录当前服务端代码通过MemberLookup处理寻址并未将其注册到PluginType注册表它属于扩展相邻机制而非当前统一插件类型。插件身份pluginType / pluginName / pluginId每个插件由以下三个字段唯一标识pluginType扩展类别例如auth或visibilitypluginName该类别下的实现名称例如nacospluginId运行时标识格式为{pluginType}:{pluginName}。pluginId用于管理 API、集群状态同步、插件状态持久化和面向用户的诊断信息。测试用例 PluginAdminApiOpenApiITCase.java 中直接断言了pluginId包含:分隔符、pluginType与pluginName非空印证了该身份模型在 Admin API 响应中的实际结构。插件类型注册表PluginType 枚举当前插件类型注册表由PluginType定义位于 api/src/main/java/com/alibaba/nacos/api/plugin/PluginType.java。除ai-vector外规范表格中的类型均可直接在枚举中找到一一对应类型目的契约auth认证与授权实现。鉴权插件规范visibility资源可见性与查询可见性建议。可见性插件规范datasource-dialect数据库方言与持久化适配。数据源方言插件规范config-change配置变更扩展。配置变更插件规范encryption加解密扩展。配置加密插件规范trace链路追踪与观测扩展。Trace 插件规范environment环境适配扩展。环境插件规范control流量与控制扩展。Control 插件规范ai-pipelineAI 注册中心 pipeline 扩展。AI 发布 Pipeline 插件规范ai-storageAI 注册中心存储扩展。AI 存储插件规范ai-resource-importAI 注册中心外部资源导入扩展。AI 资源导入插件规范各插件类别的领域契约由对应规范定义Nacos 插件化规范 定义所有插件类别共享的运行时契约。关键点在于执行形态和关键能力属于插件类型而不是某个内置实现。从源码看每个枚举常量在构造时就绑定了executionMode、critical和initializationPhase三个元数据例如AUTH(auth, ..., PluginExecutionMode.EXCLUSIVE, true)、AI_STORAGE(ai-storage, ..., PluginExecutionMode.ROUTED, true)、ENVIRONMENT(environment, ..., PluginExecutionMode.CHAIN, false, PluginInitializationPhase.PRE_CONTEXT)。枚举提供的isExclusive()由executionMode EXCLUSIVE推导以保持 API 兼容——这正对应规范中已有exclusive信息继续由executionMode EXCLUSIVE推导的描述。运行位置服务端插件与 Java 客户端扩展Nacos 有两类插件式扩展面运行位置加载模型状态归属示例服务端插件领域 SPI 加PluginProvider在支持时可由服务端插件 API 列出和管理。Nacos 服务端进程对可管理插件还包括服务端插件状态。auth、visibility、datasource-dialect、control、trace。Java 客户端扩展在客户端进程内通过 Java SPI 或 SDK API 加载。客户端 classpath、客户端配置和 SDK 实例生命周期。ServerListProvider、ClientAuthService、IConfigFilter、客户端侧配置加密。客户端扩展不由/v3/admin/core/plugin/*管理也不具备服务端PluginStateCheckerHolder决策除非对应服务端插件同时参与请求处理。但它们仍必须遵守 Nacos 资源身份、鉴权和 payload 语义因为它们会影响 SDK 发出的请求。以客户端寻址为例详见 寻址扩展规范Java Client SDK 在AbstractServerListManager中通过 SPI 加载ServerListProvider实现Config 和 Naming 客户端分别通过ConfigServerListManager与NamingServerListManager使用选中的 providergRPC client 再通过ServerListFactory消费同一份 server list被选中的 provider 是满足match(...)且getOrder()最高的实现。内置 provider 包括配置了serverAddr时使用的PropertiesListProvider固定地址列表以及配置了endpoint时使用的EndpointServerListProvider从 address endpoint 拉取地址、周期刷新并在列表变化时发布ServerListChangeEvent。客户端寻址扩展属于 Java Client SDK 扩展不是服务端插件管理器条目不由服务端 Admin 插件 API 列出或启停。执行形态EXCLUSIVE / ROUTED / CHAIN / BROADCAST插件类别并不都以同一种形态执行每个插件类型都必须明确自身执行形态。四种形态由枚举PluginExecutionMode定义api/src/main/java/com/alibaba/nacos/api/plugin/PluginExecutionMode.java形态含义示例EXCLUSIVE在进程或请求范围内选择一个实现其他已加载实现不参与该次判断。auth、datasource-dialect、controlROUTED可以加载多个实现但领域根据配置、资源元数据或请求上下文选择一个服务。encryption、visibility、ai-storage、ai-resource-importCHAIN多个匹配插件按稳定顺序执行。每个节点可以贡献结果失败是否中断由领域定义。config-change、environment、ai-pipelineBROADCAST多个订阅者观察同一个事件或 trace 点不拥有主决策权。trace、事件型扩展对于链式插件领域 SPI 必须定义如何根据资源或 pointcut 选择候选插件哪个字段控制顺序例如getPreferOrder()或getOrder()执行方式是串行还是并行某个插件失败时是中断链路还是只记录失败结果如何持久化和暴露部分执行结果。核心插件管理器记录插件的加载状态和启用状态本身不定义执行形态由领域管理器负责稳定地应用对应执行形态。对于ai-resource-import每个 managed Builder 实现表示一个外部来源请求的sourceId等于 managedpluginName领域在从 Builder 已接受配置快照创建请求级 Service 之前必须检查插件类型和实现 state。初始化阶段PRE_CONTEXT 与 STANDARD初始化阶段是由PluginType声明的插件类型能力不允许插件实现自行选择阶段含义PRE_CONTEXT在自定义环境值写入 Spring environment 之前完成发现、配置解析和 apply。STANDARDSpring context refresh 后通过常规核心插件管理器完成初始化。environment是内置的PRE_CONTEXT类型其余内置类型均为STANDARD源码中ENVIRONMENT是唯一显式传入PluginInitializationPhase.PRE_CONTEXT的枚举常量。两个阶段共享PluginInitializer编排契约pre-context initializer 必须把已初始化的原始实例及其已接受配置快照交给后续核心管理器后续流程不得再次加载 provider。SPI 层次领域 SPI 与核心插件 SPINacos 插件包含两个相关的 SPI 层次领域 SPI例如AuthPluginService或VisibilityService定义所属领域需要的行为核心插件 SPI即PluginProvider将插件实例暴露给核心插件管理器用于列表查询、状态管理、配置管理和运行时观测。PluginProviderT接口定义在 api/src/main/java/com/alibaba/nacos/api/plugin/PluginProvider.java通过 SPI 机制自动发现插件实现无需在 UnifiedPluginManager 中手工注册每个插件类型。其核心契约是getPluginType()返回管理的插件类型与getAllPlugins()返回插件名到插件实例的 Map并提供一个getOrder()默认方法同类型 provider 按 order 升序处理order 相同时保持 SPI 发现顺序该顺序在 first-wins 注册前生效。官方注释给出的典型实现如下public class AuthPluginProvider implements PluginProviderAuthPluginService { Override public PluginType getPluginType() { return PluginType.AUTH; } Override public MapString, AuthPluginService getAllPlugins() { return AuthPluginManager.getInstance().getAllPlugins(); } }已接入统一配置的领域插件 SPI 统一继承PluginConfigSpecapi/src/main/java/com/alibaba/nacos/api/plugin/PluginConfigSpec.java。该契约的兼容默认实现返回空 definitions、空 current map并提供空 apply 回调因此按旧版领域 SPI 编译的实现和新版零配置实现都会保持configurablefalse。声明至少一个ConfigItemDefinition的插件属于可配置实现必须实现 current-map 和 apply 回调。PluginConfigSpec.isConfigurable()的默认实现正是getConfigDefinitions()非空且非空列表时返回 true。PluginConfigDefinitionSpec是仅暴露 definitions 的父契约供必须在创建实例之前声明配置元数据的 factory 使用参与统一配置生命周期的运行时插件实例仍必须实现完整的PluginConfigSpec只实现 definition contract 的 factory 不接收也不持有 effective config。加载与生命周期确定性、first-wins 与启停判定插件实现通过 Nacos SPI 加载部署时可以从 classpath 或服务端插件目录提供插件插件实现必须能在不修改 Nacos 服务端代码的情况下被加载。pre-context initializer 会在自定义环境处理前发现 policy 允许加载的PRE_CONTEXTprovider只解析STATIC DEFAULT对可配置实现执行 apply并把实例交给领域 managerSpring context refresh 后standard initializer 再发现轻量STANDARDPluginProvider实现。只有领域 policy 当前允许加载的插件类型才会立即调用getAllPluginsactive critical 类型不受可选加载判据影响必须加载对于被延迟的非 critical 类型后续服务配置刷新使加载判据变为 true 时必须先发现实现、恢复持久化实现 state、解析 effective config 并调用applyConfig然后才能让这些实现参与执行。类型一旦加载加载判据再次变为 false 时不卸载实例仍由所属领域入口总开关阻止执行加载判据不能替代实现级 state其默认值为 true见 PluginTypePolicy.java 的isLoadingEnabled默认实现只有拥有类型级模块或能力总开关的领域才应覆盖该判据。插件启动必须具备确定性一个插件类型和插件名称组合只能对应一个运行时插件实例插件发现采用first-wins 注册名称为空或实例为 null 的实现记录 WARN 后忽略后发现实现与已有type:name重复时保留先发现实现记录包含两个实现类的 WARN 并忽略后来实现这类发现冲突本身不阻塞 Nacos 启动provider 从多个 SPI 实现构造返回 Map 时也必须使用相同的 first-wins 规则不得在返回 Core 前静默覆盖先发现实现插件实现不得改变 Nacos 共享资源标识、响应封装或错误约定的含义。支持启停状态判断的插件类别应通过PluginStateCheckerHolder获取状态而不是维护一套独立状态来源。若 adapter 必须在 effective config 被接受后创建领域运行资源可以实现可选的PluginStartupLifecycleCore 只为 enabled 实现调用initialize()调用发生在持久化 state 恢复和applyConfig完成之后、Nacos 报告启动成功之前且该操作必须幂等它与isConfigurable()相互独立——零配置 adapter 仍可能需要初始化可配置 adapter 也可以不实现该生命周期。状态与配置模块开关、插件状态与统一配置模型两个独立层次模块开关 vs 插件状态插件状态分为两个层次已加载实现存在于运行时与已启用实现可以参与请求处理。核心模块开关和插件状态是两个独立层次nacos.core.auth.enabled、nacos.core.auth.admin.enabled和nacos.core.auth.console.enabled等模块开关决定核心请求链路是否调用插件不属于插件实现配置也不得由插件管理 API 修改模块关闭时插件仍可以保持加载、启用和完成配置初始化每个纳入统一管理的插件类型都可以提供一个由领域模块持有的内部PluginTypePolicyapi/src/main/java/com/alibaba/nacos/api/plugin/PluginTypePolicy.java由它定义当前领域是否需要该插件类型、非 critical 类型当前是否允许加载实现、每个已发现实现的初始 enabled 状态、critical 类型 active 时必需的具体实现名称以及诊断信息中的选择配置和激活原因PluginType.isCritical()是该类型可能是服务正确运行所必需的唯一静态声明只有领域 policy 处于 active 状态时 core 才校验该 critical 类型。当前关键类型包括auth、datasource-dialect和ai-storage——active 互斥类型没有选择实现、要求的实现不存在或要求的实现被禁用均属于启动错误Nacos 不得静默选择或重新启用任意 fallback 实现。标准静态选择与启用 key已接入统一启动选择的互斥插件类型通过以下标准静态 key 选择实现RESTART语义修改后需重启nacos.plugin.{pluginType}.type{pluginName}历史选择 key 仅作为 alias类型标准 key历史 alias默认值authnacos.plugin.auth.typenacos.core.auth.system.typenacosdatasource-dialectnacos.plugin.datasource-dialect.typespring.sql.init.platformderbycontrolnacos.plugin.control.typenacos.plugin.control.manager.type空表示 no-limit标准 key 与 alias 同时存在时标准 key 优先读取 alias 时服务端应记录迁移提示日志。由于互斥类型的选择会影响 Spring Bean、数据源等启动资源插件 status API 不得把切换报告为运行时已生效修改选择必须更新上述静态 key 并重启。非互斥插件实现可以通过以下标准静态 key 提供初始启用状态运行时由插件管理 API 和统一 plugin state 管理存在持久化状态时持久化状态优先nacos.plugin.{pluginType}.{pluginName}.enabledtrue|false链式和广播型插件的全部 enabled 实现参与执行路由型插件只允许从 enabled 候选中选择实际实现。nacos.plugin.{pluginType}.enabled这类不包含实现名称的 key 不属于统一实现状态已有 key 若实际承担核心模块或领域能力入口门禁应继续由所属领域读取且不得被持久化子插件状态绕过。统一状态迁移排查表统一状态迁移阶段对现有内置开关的排查结论如下配置归属与迁移行为nacos.core.auth.enabled、nacos.core.auth.admin.enabled、nacos.core.auth.console.enabled核心请求入口开关不进入 plugin state。nacos.extension.ai.enabledAI 模块开关不进入 plugin state。nacos.core.config.plugin.{name}.enabled历史实现开关仅作为nacos.plugin.config-change.{name}.enabled的初始状态兼容 alias。nacos.plugin.visibility.enabled、nacos.plugin.ai-pipeline.enabled已有领域能力入口开关分别决定核心链路是否进入 visibility 或 AI pipeline保留动态读取且不转换为子插件状态。nacos.plugin.visibility.type历史 visibility 选择 key仅用于推导对应实现的初始状态运行时路由从 enabled 实现中按领域输入选择。nacos.plugin.ai-pipeline.type历史 Pipeline 链成员输入仅由 Core 按RESTART推导实现初始状态实现配置和顺序统一使用各节点的PluginConfigSpec。nacos.plugin.datasource.log.enabled数据源行为和日志配置不是实现启停状态。nacos.ai.resource.import.enablednacos.plugin.ai-resource-import.enabled的历史 alias标准 key 存在时优先。AI Resource Import 默认开启只有显式false才关闭。后续不得新增与逐实现 state 含义重复的插件族开关。核心模块或领域能力入口开关可以决定是否进入整项能力但不能选择或启停某个具体实现具体实现是否参与执行只能由逐实现 plugin state 表达。配置定义与来源优先级插件配置项由ConfigItemDefinition描述。key表示插件实现内部的 canonical item key不携带nacos.plugin.{pluginType}.{pluginName}.前缀静态配置推荐使用以下 normalized full keynacos.plugin.{pluginType}.{pluginName}.{itemKey}配置定义可以声明以下元数据字段含义aliases历史静态配置 key用于兼容读取和迁移提示。sensitive是否为敏感值。查询 API 返回前必须脱敏。effectMode生效模式RUNTIME表示可运行时生效RESTART表示需要重启。enabled是插件实现统一状态的保留 item key插件不得在ConfigItemDefinition中将其声明为普通配置项。definition 发现同样采用 first-wins 归一化null definition、空 item key 和保留的enabledkey 记录 WARN 后忽略后来 item key 或 alias 与先前 definition 已占用的输入 key 冲突时保留先发现 definition。PRE_CONTEXT插件声明的RUNTIME生效模式在副本中按RESTART处理。插件配置的 effective value 由统一解析流程计算配置来源优先级为LOCAL_ONLY RUNTIME_PERSISTED STATIC DEFAULT完整优先级只适用于STANDARD插件PRE_CONTEXT插件只解析STATIC DEFAULT不加载也不接受 runtime persisted 或 local-only source。来源含义DEFAULT来自ConfigItemDefinition.defaultValue。STATIC来自application.properties、环境变量、JVM 参数或 Spring 参数等静态配置。RUNTIME_PERSISTED来自集群级运行时 override当前可由plugin-configs.json记录终态内容。LOCAL_ONLY当前节点的本机 override只用于诊断或应急处理不同步到集群。插件详情返回模型可以追加以 canonical item key 为索引的configValueMetasmap每个PluginConfigValueMeta描述对应配置项的当前值来源和是否存在多来源覆盖overridden忽略DEFAULT只有同一 key 同时存在多个非默认来源时才为true。RUNTIME_PERSISTED背后的物理存储属于 core 内部扩展通过PluginConfigStorageProvider声明稳定的存储名称、启动顺序和默认启用状态storage 使用仅重启生效的静态开关nacos.plugin.config.source.{storageName}.enabled控制。内置local-fileprovider 默认开启且选择优先级最低显式开启的内部实现可以替换它。物理存储和集群同步是两个独立扩展边界PluginConfigStorage持有RUNTIME_PERSISTED终态数据PluginStateSynchronizer负责插件状态与运行时持久化配置操作的集群顺序和传播替换其中一个扩展点不得隐式替换另一个。standalone 模式不创建也不调用 synchronizer集群模式在nacos.plugin.state.synchronizer.type不存在、为空或显式设置为raft时使用内置 Raft synchronizer。计划移除的废弃兼容项以下兼容输入在各自迁移窗口内继续接受以便已有部署完成迁移除表格另有更早版本说明外它们均已废弃并计划在 Nacos 4.0.0 移除。新部署、示例、测试和插件实现只能使用标准替代项废弃兼容输入标准替代项迁移说明nacos.core.auth.system.typenacos.plugin.auth.type静态互斥插件选择迁移后需要重启。spring.sql.init.platformnacos.plugin.datasource-dialect.type静态数据库方言选择迁移后需要重启。nacos.plugin.control.manager.typenacos.plugin.control.type静态 Control 实现选择迁移后需要重启。nacos.core.config.plugin.{pluginName}.enablednacos.plugin.config-change.{pluginName}.enabled或统一 plugin state旧 key 只提供实现初始状态。nacos.plugin.visibility.typenacos.plugin.visibility.{pluginName}.enabled或统一 plugin state旧 selector 只提供初始状态不定义运行时路由。nacos.plugin.ai-pipeline.typenacos.plugin.ai-pipeline.{pluginName}.enabled或统一 plugin state使用实现状态替代旧的逗号分隔启动链。nacos.core.auth.plugin.nacos.*、nacos.core.auth.caching.enabled和nacos.core.auth.nacos.anonymous.ai.enablednacos.plugin.auth.nacos.{itemKey}按 definition 暴露的 canonical item key 迁移每个默认鉴权配置项。nacos.core.auth.ldap.*nacos.plugin.auth.ldap.{itemKey}LDAP item 名称使用 canonical kebab-case definition。nacos.core.auth.plugin.oidc.*nacos.plugin.auth.oidc.{itemKey}OIDC item 名称使用 canonical definition当前全部 OIDC 配置仍为RESTART。db.*和 JVM 参数QUERYTIMEOUTnacos.plugin.datasource.db.*数据源参数仍是只在重启后生效的模块配置不进入插件 PUT API。executable、path、useLlm、apiKey等历史 AI Pipeline 相对 item key 和其他 camel-case aliasnacos.plugin.ai-pipeline.{pluginName}.*下的 canonical kebab-case item key精确 alias 清单由 AI Pipeline 插件规范记录。nacos.ai.resource.import.enablednacos.plugin.ai-resource-import.enabled标准模块 key 保持权威默认开启。nacos.plugin.ai.importer.*.enablednacos.plugin.ai-resource-import.{pluginName}.enabled或统一 plugin state把旧内置 source 状态 key 迁移到受管实现状态。nacos.plugin.ai.importer.*item 配置nacos.plugin.ai-resource-import.{pluginName}.{itemKey}把 display、description、limits 和 endpoint 输入迁移到受管 source 身份。nacos.ai.resource.import.allow-user-url受管 source endpoint 配置用户 URL 直接导入兼容和旧 MCP import adapter 计划在 Nacos 3.4.0 移除。ConfigChangeConfigsproperty bridgeConfigChangePluginService上的 definitions 和 callbacks3.x 窗口内没有 definitions 的旧二进制插件继续接收历史 properties。VisibilityService.init(Properties)从PluginConfigSpec继承的 definitions 和 callbacks统一生命周期在 visibility 执行前应用 effective item-key map。CustomEnvironmentPluginManager.join(...)通过PRE_CONTEXTinitializer 发现 Environment SPIEnvironment 实现必须在 Spring environment 定制开始前可被发现。旧的nacos.ai.resource.import.legacy-mcp-api-enabled输入不再识别废弃 MCP Import API 改用 兼容与废弃策略规范 定义的共享nacos.core.api.compatibility.enabled门禁。nacos.core.auth.enabled等核心模块总开关、PluginConfigSpec的空 definitions 默认实现以及旧版零配置插件实现的二进制加载兼容不属于本移除清单。运行时状态约束与配置更新兼容性对于每次运行时操作都会重新选择实现的插件类型领域执行链路必须在调用扩展前检查统一插件状态。当前使用该门禁的插件包括auth、datasource-dialect、encryption、trace、visibility、config-change、ai-pipeline和ai-storage。被禁用的插件仍保持加载并可由管理 API 查询但不得参与领域执行。持久化状态变更必须遵循validate、persist、apply 顺序先校验完整候选终态再写入持久化状态只有持久化成功后才能修改管理器内存状态。持久化失败时内存保持原值并允许重试。localOnly状态变更按定义跳过持久化只应用到当前节点。plugin_state一致性组可能在 Spring context 创建期间恢复快照快照中的statesmap 表示完整的持久化 override 而非增量 patch恢复时必须整体替换本机持久化 map快照中缺失的条目用于移除本机陈旧 override。配置更新 API 保持 additive 兼容已有config和configDefinitions字段继续保留config可以表示当前 effective config新增的configValueMetasmap 按 canonical item key 提供 source 和 overridden 等元信息。PUT /v3/admin/core/plugin/config保持完整 override map 更新语义localOnlytrue表示只更新当前节点 local-only override否则更新集群级 runtime persisted override。effectModeRESTART的字段不应通过运行时更新立即生效新增、修改或移除RESTART配置项都必须拒绝。对于声明为sensitivetrue的配置项提交值只要包含统一的******marker 就按脱敏展示值处理如果当前目标 source 已包含该 key服务端应保留原始值如果目标 source 不包含该 key则忽略这项输入。该判断同时覆盖******、a******z和ab******yz且不得把STATIC等其他 source 的 effective value 复制成 runtime override。管理 API核心插件管理 API 如下均属于 Admin API并要求符合 HTTP 鉴权规范 中的控制台域鉴权同时必须使用标准 v3 响应与错误模型方法路径目的GET/v3/admin/core/plugin/list查询已加载插件可按类型过滤。GET/v3/admin/core/plugin/detail查询单个插件详情返回 effective config 和可选值元数据。PUT/v3/admin/core/plugin/status启用或禁用插件。PUT/v3/admin/core/plugin/config更新插件配置。集成测试 PluginAdminApiOpenApiITCase.java 对这些端点的行为给出了可直接对照的验证list 与 detaillist 响应中每个插件必须携带pluginId含:、pluginType、pluginName、typeCritical、executionMode、exclusive字段按pluginType过滤只返回该类型未知类型过滤返回空列表detail 返回与 list 一致的 identity并追加enabled、configurable、configValueMetas配置元数据对auth类型的nacos实现detail 暴露 5 个configDefinitions包括token.secret.keySTRING、RESTART、sensitive、token.expire.secondsNUMBER、RUNTIME、token.cache.enableBOOLEAN、RUNTIME、caching.enabledBOOLEAN、RUNTIME、anonymous.ai.enabledBOOLEAN、RUNTIME其中敏感项token.secret.key在响应中已脱敏为******而configValueMetas正确标记了token.secret.key的来源为STATIC、anonymous.ai.enabled的来源为DEFAULT边界与错误status 更新必须携带pluginNameconfig 更新必须携带config且拒绝不可配置插件禁用 critical 实现、对互斥类型做运行时切换都会被拒绝且不产生变更符合critical 类型必须保留可用实现互斥选择只能重启生效的约束。控制台配置流程要点控制台插件详情以 detail API 返回的 effective value、definition 和 value metadata 作为唯一权威输入并遵守以下规则RUNTIME字段使用可编辑控件RESTART字段只读并提示通过 Nacos 配置文件修改后重启生效展示 effective source 和 overridden 状态但不得获得或显示未脱敏的敏感值将集群级 runtime persisted 更新与当前节点 local-only 更新作为两个明确、独立的模式按完整 map 更新契约重建目标 source只把 effective metadata 指向目标 source 的现有值作为基线再合并用户编辑和显式移除 override 的操作不能因为提交了表单就把STATIC或DEFAULT的 effective value 复制成运行时 override。由于 effectiveLOCAL_ONLY值可能遮住同一字段已经存在的 runtime persisted 值只要当前节点仍有任意 local-only override控制台就必须阻止提交集群配置可以通过localOnlytrue提交空 map 完整清空当前节点的 local-only source。插件实现设计要求插件实现必须遵守以下规则使用已有 Nacos 资源标识和领域模型不为同一资源发明不兼容的新模型插件提供的 HTTP API 必须保持 v3 HTTP API 响应、错误和鉴权约定仅通过PluginConfigSpec暴露插件自身拥有的配置除调用方明确要求本机操作用于诊断或应急处理外集群级状态变更必须保持同步安全敏感的默认值和部署要求必须在插件实现规范中说明。扩展规范阅读地图按插件规范树的五大分类深入各领域契约时建议按需查阅对应规范文档通用模型plugin-spec.md本文核心依据、addressing-plugin-spec.md数据与配置datasource-dialect-plugin-spec.md、default-datasource-dialect-plugin-spec.md、config-change-plugin-spec.md、config-encryption-plugin-spec.md运行时扩展environment-plugin-spec.md、trace-plugin-spec.md、control-plugin-spec.md、default-control-plugin-spec.mdAI 扩展ai-pipeline-plugin-spec.md、ai-storage-plugin-spec.md、ai-vector-plugin-spec.md、ai-resource-import-plugin-spec.md安全扩展auth-plugin-spec.md、ram-auth-plugin-spec.md、oidc-auth-plugin-spec.md、visibility-plugin-spec.md。与之配套的 SPI 与元数据模型集中在 api/src/main/java/com/alibaba/nacos/api/plugin 包下PluginType、PluginProvider、PluginConfigSpec、PluginTypePolicy、PluginExecutionMode、PluginStartupLifecycle、PluginStateCheckerHolder等管理 API 的行为可对照 PluginAdminApiOpenApiITCase.java 理解。在实际部署中插件选择与启停的静态配置均写入application.properties可参考 distribution/conf/application.properties而运行时配置与状态通过前述管理 API 与集群同步链路维护。【免费下载链接】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 插件规范全景：扩展点分类、SPI 层次、加载生命周期与统一配置管理实战指南
Nacos 插件规范全景扩展点分类、SPI 层次、加载生命周期与统一配置管理实战指南【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos 通过一套统一的插件机制与 SPI 扩展将鉴权、资源可见性、数据源方言、加解密、链路追踪、流量控制、环境适配乃至 AI pipeline、AI 存储、AI 资源导入等横切与可替换能力从固定核心中拆出让不同部署环境可以按自身身份系统、数据库、观测体系或扩展场景选择实现。本文以 specs/zh-cn/plugin/README.md 定义的插件规范框架为主线结合核心规范 specs/zh-cn/plugin/plugin-spec.md 与仓库源码系统讲解插件身份模型、类型注册表、执行形态、SPI 层次、加载生命周期、统一状态与配置模型以及管理 API读完即可理解如何判断一个扩展点属于哪类插件、如何加载、如何配置、如何被管理。插件规范的定位与总体框架插件规范定义 Nacos 扩展点如何加载、选择、执行、配置以及如何通过统一插件管理模型对外暴露。它扩展 Nacos 设计规范必须保持 资源模型 语义稳定并在暴露 HTTP 端点时遵守 HTTP API 规则。插件机制是扩展边界不是绕过 Nacos 资源、API 或安全规则的通道。整个插件规范树按功能域划分为五大类这也是插件扩展点全景图通用模型Nacos 插件化规范所有插件共享的运行时契约、寻址扩展规范。数据与配置数据源方言插件规范、默认数据源方言插件实现规范、配置变更插件规范、配置加密插件规范。运行时扩展环境插件规范、Trace 插件规范、Control 插件规范、默认 Control 插件实现规范。AI 扩展AI 发布 Pipeline 插件规范、AI 存储插件规范、AI Vector 插件规范、AI 资源导入插件规范。安全扩展鉴权插件规范、RAM 鉴权插件规范、OIDC 鉴权插件规范、可见性插件规范。其中 寻址扩展规范 是为了和公开插件文档保持连续性而放在插件规范树中记录当前服务端代码通过MemberLookup处理寻址并未将其注册到PluginType注册表它属于扩展相邻机制而非当前统一插件类型。插件身份pluginType / pluginName / pluginId每个插件由以下三个字段唯一标识pluginType扩展类别例如auth或visibilitypluginName该类别下的实现名称例如nacospluginId运行时标识格式为{pluginType}:{pluginName}。pluginId用于管理 API、集群状态同步、插件状态持久化和面向用户的诊断信息。测试用例 PluginAdminApiOpenApiITCase.java 中直接断言了pluginId包含:分隔符、pluginType与pluginName非空印证了该身份模型在 Admin API 响应中的实际结构。插件类型注册表PluginType 枚举当前插件类型注册表由PluginType定义位于 api/src/main/java/com/alibaba/nacos/api/plugin/PluginType.java。除ai-vector外规范表格中的类型均可直接在枚举中找到一一对应类型目的契约auth认证与授权实现。鉴权插件规范visibility资源可见性与查询可见性建议。可见性插件规范datasource-dialect数据库方言与持久化适配。数据源方言插件规范config-change配置变更扩展。配置变更插件规范encryption加解密扩展。配置加密插件规范trace链路追踪与观测扩展。Trace 插件规范environment环境适配扩展。环境插件规范control流量与控制扩展。Control 插件规范ai-pipelineAI 注册中心 pipeline 扩展。AI 发布 Pipeline 插件规范ai-storageAI 注册中心存储扩展。AI 存储插件规范ai-resource-importAI 注册中心外部资源导入扩展。AI 资源导入插件规范各插件类别的领域契约由对应规范定义Nacos 插件化规范 定义所有插件类别共享的运行时契约。关键点在于执行形态和关键能力属于插件类型而不是某个内置实现。从源码看每个枚举常量在构造时就绑定了executionMode、critical和initializationPhase三个元数据例如AUTH(auth, ..., PluginExecutionMode.EXCLUSIVE, true)、AI_STORAGE(ai-storage, ..., PluginExecutionMode.ROUTED, true)、ENVIRONMENT(environment, ..., PluginExecutionMode.CHAIN, false, PluginInitializationPhase.PRE_CONTEXT)。枚举提供的isExclusive()由executionMode EXCLUSIVE推导以保持 API 兼容——这正对应规范中已有exclusive信息继续由executionMode EXCLUSIVE推导的描述。运行位置服务端插件与 Java 客户端扩展Nacos 有两类插件式扩展面运行位置加载模型状态归属示例服务端插件领域 SPI 加PluginProvider在支持时可由服务端插件 API 列出和管理。Nacos 服务端进程对可管理插件还包括服务端插件状态。auth、visibility、datasource-dialect、control、trace。Java 客户端扩展在客户端进程内通过 Java SPI 或 SDK API 加载。客户端 classpath、客户端配置和 SDK 实例生命周期。ServerListProvider、ClientAuthService、IConfigFilter、客户端侧配置加密。客户端扩展不由/v3/admin/core/plugin/*管理也不具备服务端PluginStateCheckerHolder决策除非对应服务端插件同时参与请求处理。但它们仍必须遵守 Nacos 资源身份、鉴权和 payload 语义因为它们会影响 SDK 发出的请求。以客户端寻址为例详见 寻址扩展规范Java Client SDK 在AbstractServerListManager中通过 SPI 加载ServerListProvider实现Config 和 Naming 客户端分别通过ConfigServerListManager与NamingServerListManager使用选中的 providergRPC client 再通过ServerListFactory消费同一份 server list被选中的 provider 是满足match(...)且getOrder()最高的实现。内置 provider 包括配置了serverAddr时使用的PropertiesListProvider固定地址列表以及配置了endpoint时使用的EndpointServerListProvider从 address endpoint 拉取地址、周期刷新并在列表变化时发布ServerListChangeEvent。客户端寻址扩展属于 Java Client SDK 扩展不是服务端插件管理器条目不由服务端 Admin 插件 API 列出或启停。执行形态EXCLUSIVE / ROUTED / CHAIN / BROADCAST插件类别并不都以同一种形态执行每个插件类型都必须明确自身执行形态。四种形态由枚举PluginExecutionMode定义api/src/main/java/com/alibaba/nacos/api/plugin/PluginExecutionMode.java形态含义示例EXCLUSIVE在进程或请求范围内选择一个实现其他已加载实现不参与该次判断。auth、datasource-dialect、controlROUTED可以加载多个实现但领域根据配置、资源元数据或请求上下文选择一个服务。encryption、visibility、ai-storage、ai-resource-importCHAIN多个匹配插件按稳定顺序执行。每个节点可以贡献结果失败是否中断由领域定义。config-change、environment、ai-pipelineBROADCAST多个订阅者观察同一个事件或 trace 点不拥有主决策权。trace、事件型扩展对于链式插件领域 SPI 必须定义如何根据资源或 pointcut 选择候选插件哪个字段控制顺序例如getPreferOrder()或getOrder()执行方式是串行还是并行某个插件失败时是中断链路还是只记录失败结果如何持久化和暴露部分执行结果。核心插件管理器记录插件的加载状态和启用状态本身不定义执行形态由领域管理器负责稳定地应用对应执行形态。对于ai-resource-import每个 managed Builder 实现表示一个外部来源请求的sourceId等于 managedpluginName领域在从 Builder 已接受配置快照创建请求级 Service 之前必须检查插件类型和实现 state。初始化阶段PRE_CONTEXT 与 STANDARD初始化阶段是由PluginType声明的插件类型能力不允许插件实现自行选择阶段含义PRE_CONTEXT在自定义环境值写入 Spring environment 之前完成发现、配置解析和 apply。STANDARDSpring context refresh 后通过常规核心插件管理器完成初始化。environment是内置的PRE_CONTEXT类型其余内置类型均为STANDARD源码中ENVIRONMENT是唯一显式传入PluginInitializationPhase.PRE_CONTEXT的枚举常量。两个阶段共享PluginInitializer编排契约pre-context initializer 必须把已初始化的原始实例及其已接受配置快照交给后续核心管理器后续流程不得再次加载 provider。SPI 层次领域 SPI 与核心插件 SPINacos 插件包含两个相关的 SPI 层次领域 SPI例如AuthPluginService或VisibilityService定义所属领域需要的行为核心插件 SPI即PluginProvider将插件实例暴露给核心插件管理器用于列表查询、状态管理、配置管理和运行时观测。PluginProviderT接口定义在 api/src/main/java/com/alibaba/nacos/api/plugin/PluginProvider.java通过 SPI 机制自动发现插件实现无需在 UnifiedPluginManager 中手工注册每个插件类型。其核心契约是getPluginType()返回管理的插件类型与getAllPlugins()返回插件名到插件实例的 Map并提供一个getOrder()默认方法同类型 provider 按 order 升序处理order 相同时保持 SPI 发现顺序该顺序在 first-wins 注册前生效。官方注释给出的典型实现如下public class AuthPluginProvider implements PluginProviderAuthPluginService { Override public PluginType getPluginType() { return PluginType.AUTH; } Override public MapString, AuthPluginService getAllPlugins() { return AuthPluginManager.getInstance().getAllPlugins(); } }已接入统一配置的领域插件 SPI 统一继承PluginConfigSpecapi/src/main/java/com/alibaba/nacos/api/plugin/PluginConfigSpec.java。该契约的兼容默认实现返回空 definitions、空 current map并提供空 apply 回调因此按旧版领域 SPI 编译的实现和新版零配置实现都会保持configurablefalse。声明至少一个ConfigItemDefinition的插件属于可配置实现必须实现 current-map 和 apply 回调。PluginConfigSpec.isConfigurable()的默认实现正是getConfigDefinitions()非空且非空列表时返回 true。PluginConfigDefinitionSpec是仅暴露 definitions 的父契约供必须在创建实例之前声明配置元数据的 factory 使用参与统一配置生命周期的运行时插件实例仍必须实现完整的PluginConfigSpec只实现 definition contract 的 factory 不接收也不持有 effective config。加载与生命周期确定性、first-wins 与启停判定插件实现通过 Nacos SPI 加载部署时可以从 classpath 或服务端插件目录提供插件插件实现必须能在不修改 Nacos 服务端代码的情况下被加载。pre-context initializer 会在自定义环境处理前发现 policy 允许加载的PRE_CONTEXTprovider只解析STATIC DEFAULT对可配置实现执行 apply并把实例交给领域 managerSpring context refresh 后standard initializer 再发现轻量STANDARDPluginProvider实现。只有领域 policy 当前允许加载的插件类型才会立即调用getAllPluginsactive critical 类型不受可选加载判据影响必须加载对于被延迟的非 critical 类型后续服务配置刷新使加载判据变为 true 时必须先发现实现、恢复持久化实现 state、解析 effective config 并调用applyConfig然后才能让这些实现参与执行。类型一旦加载加载判据再次变为 false 时不卸载实例仍由所属领域入口总开关阻止执行加载判据不能替代实现级 state其默认值为 true见 PluginTypePolicy.java 的isLoadingEnabled默认实现只有拥有类型级模块或能力总开关的领域才应覆盖该判据。插件启动必须具备确定性一个插件类型和插件名称组合只能对应一个运行时插件实例插件发现采用first-wins 注册名称为空或实例为 null 的实现记录 WARN 后忽略后发现实现与已有type:name重复时保留先发现实现记录包含两个实现类的 WARN 并忽略后来实现这类发现冲突本身不阻塞 Nacos 启动provider 从多个 SPI 实现构造返回 Map 时也必须使用相同的 first-wins 规则不得在返回 Core 前静默覆盖先发现实现插件实现不得改变 Nacos 共享资源标识、响应封装或错误约定的含义。支持启停状态判断的插件类别应通过PluginStateCheckerHolder获取状态而不是维护一套独立状态来源。若 adapter 必须在 effective config 被接受后创建领域运行资源可以实现可选的PluginStartupLifecycleCore 只为 enabled 实现调用initialize()调用发生在持久化 state 恢复和applyConfig完成之后、Nacos 报告启动成功之前且该操作必须幂等它与isConfigurable()相互独立——零配置 adapter 仍可能需要初始化可配置 adapter 也可以不实现该生命周期。状态与配置模块开关、插件状态与统一配置模型两个独立层次模块开关 vs 插件状态插件状态分为两个层次已加载实现存在于运行时与已启用实现可以参与请求处理。核心模块开关和插件状态是两个独立层次nacos.core.auth.enabled、nacos.core.auth.admin.enabled和nacos.core.auth.console.enabled等模块开关决定核心请求链路是否调用插件不属于插件实现配置也不得由插件管理 API 修改模块关闭时插件仍可以保持加载、启用和完成配置初始化每个纳入统一管理的插件类型都可以提供一个由领域模块持有的内部PluginTypePolicyapi/src/main/java/com/alibaba/nacos/api/plugin/PluginTypePolicy.java由它定义当前领域是否需要该插件类型、非 critical 类型当前是否允许加载实现、每个已发现实现的初始 enabled 状态、critical 类型 active 时必需的具体实现名称以及诊断信息中的选择配置和激活原因PluginType.isCritical()是该类型可能是服务正确运行所必需的唯一静态声明只有领域 policy 处于 active 状态时 core 才校验该 critical 类型。当前关键类型包括auth、datasource-dialect和ai-storage——active 互斥类型没有选择实现、要求的实现不存在或要求的实现被禁用均属于启动错误Nacos 不得静默选择或重新启用任意 fallback 实现。标准静态选择与启用 key已接入统一启动选择的互斥插件类型通过以下标准静态 key 选择实现RESTART语义修改后需重启nacos.plugin.{pluginType}.type{pluginName}历史选择 key 仅作为 alias类型标准 key历史 alias默认值authnacos.plugin.auth.typenacos.core.auth.system.typenacosdatasource-dialectnacos.plugin.datasource-dialect.typespring.sql.init.platformderbycontrolnacos.plugin.control.typenacos.plugin.control.manager.type空表示 no-limit标准 key 与 alias 同时存在时标准 key 优先读取 alias 时服务端应记录迁移提示日志。由于互斥类型的选择会影响 Spring Bean、数据源等启动资源插件 status API 不得把切换报告为运行时已生效修改选择必须更新上述静态 key 并重启。非互斥插件实现可以通过以下标准静态 key 提供初始启用状态运行时由插件管理 API 和统一 plugin state 管理存在持久化状态时持久化状态优先nacos.plugin.{pluginType}.{pluginName}.enabledtrue|false链式和广播型插件的全部 enabled 实现参与执行路由型插件只允许从 enabled 候选中选择实际实现。nacos.plugin.{pluginType}.enabled这类不包含实现名称的 key 不属于统一实现状态已有 key 若实际承担核心模块或领域能力入口门禁应继续由所属领域读取且不得被持久化子插件状态绕过。统一状态迁移排查表统一状态迁移阶段对现有内置开关的排查结论如下配置归属与迁移行为nacos.core.auth.enabled、nacos.core.auth.admin.enabled、nacos.core.auth.console.enabled核心请求入口开关不进入 plugin state。nacos.extension.ai.enabledAI 模块开关不进入 plugin state。nacos.core.config.plugin.{name}.enabled历史实现开关仅作为nacos.plugin.config-change.{name}.enabled的初始状态兼容 alias。nacos.plugin.visibility.enabled、nacos.plugin.ai-pipeline.enabled已有领域能力入口开关分别决定核心链路是否进入 visibility 或 AI pipeline保留动态读取且不转换为子插件状态。nacos.plugin.visibility.type历史 visibility 选择 key仅用于推导对应实现的初始状态运行时路由从 enabled 实现中按领域输入选择。nacos.plugin.ai-pipeline.type历史 Pipeline 链成员输入仅由 Core 按RESTART推导实现初始状态实现配置和顺序统一使用各节点的PluginConfigSpec。nacos.plugin.datasource.log.enabled数据源行为和日志配置不是实现启停状态。nacos.ai.resource.import.enablednacos.plugin.ai-resource-import.enabled的历史 alias标准 key 存在时优先。AI Resource Import 默认开启只有显式false才关闭。后续不得新增与逐实现 state 含义重复的插件族开关。核心模块或领域能力入口开关可以决定是否进入整项能力但不能选择或启停某个具体实现具体实现是否参与执行只能由逐实现 plugin state 表达。配置定义与来源优先级插件配置项由ConfigItemDefinition描述。key表示插件实现内部的 canonical item key不携带nacos.plugin.{pluginType}.{pluginName}.前缀静态配置推荐使用以下 normalized full keynacos.plugin.{pluginType}.{pluginName}.{itemKey}配置定义可以声明以下元数据字段含义aliases历史静态配置 key用于兼容读取和迁移提示。sensitive是否为敏感值。查询 API 返回前必须脱敏。effectMode生效模式RUNTIME表示可运行时生效RESTART表示需要重启。enabled是插件实现统一状态的保留 item key插件不得在ConfigItemDefinition中将其声明为普通配置项。definition 发现同样采用 first-wins 归一化null definition、空 item key 和保留的enabledkey 记录 WARN 后忽略后来 item key 或 alias 与先前 definition 已占用的输入 key 冲突时保留先发现 definition。PRE_CONTEXT插件声明的RUNTIME生效模式在副本中按RESTART处理。插件配置的 effective value 由统一解析流程计算配置来源优先级为LOCAL_ONLY RUNTIME_PERSISTED STATIC DEFAULT完整优先级只适用于STANDARD插件PRE_CONTEXT插件只解析STATIC DEFAULT不加载也不接受 runtime persisted 或 local-only source。来源含义DEFAULT来自ConfigItemDefinition.defaultValue。STATIC来自application.properties、环境变量、JVM 参数或 Spring 参数等静态配置。RUNTIME_PERSISTED来自集群级运行时 override当前可由plugin-configs.json记录终态内容。LOCAL_ONLY当前节点的本机 override只用于诊断或应急处理不同步到集群。插件详情返回模型可以追加以 canonical item key 为索引的configValueMetasmap每个PluginConfigValueMeta描述对应配置项的当前值来源和是否存在多来源覆盖overridden忽略DEFAULT只有同一 key 同时存在多个非默认来源时才为true。RUNTIME_PERSISTED背后的物理存储属于 core 内部扩展通过PluginConfigStorageProvider声明稳定的存储名称、启动顺序和默认启用状态storage 使用仅重启生效的静态开关nacos.plugin.config.source.{storageName}.enabled控制。内置local-fileprovider 默认开启且选择优先级最低显式开启的内部实现可以替换它。物理存储和集群同步是两个独立扩展边界PluginConfigStorage持有RUNTIME_PERSISTED终态数据PluginStateSynchronizer负责插件状态与运行时持久化配置操作的集群顺序和传播替换其中一个扩展点不得隐式替换另一个。standalone 模式不创建也不调用 synchronizer集群模式在nacos.plugin.state.synchronizer.type不存在、为空或显式设置为raft时使用内置 Raft synchronizer。计划移除的废弃兼容项以下兼容输入在各自迁移窗口内继续接受以便已有部署完成迁移除表格另有更早版本说明外它们均已废弃并计划在 Nacos 4.0.0 移除。新部署、示例、测试和插件实现只能使用标准替代项废弃兼容输入标准替代项迁移说明nacos.core.auth.system.typenacos.plugin.auth.type静态互斥插件选择迁移后需要重启。spring.sql.init.platformnacos.plugin.datasource-dialect.type静态数据库方言选择迁移后需要重启。nacos.plugin.control.manager.typenacos.plugin.control.type静态 Control 实现选择迁移后需要重启。nacos.core.config.plugin.{pluginName}.enablednacos.plugin.config-change.{pluginName}.enabled或统一 plugin state旧 key 只提供实现初始状态。nacos.plugin.visibility.typenacos.plugin.visibility.{pluginName}.enabled或统一 plugin state旧 selector 只提供初始状态不定义运行时路由。nacos.plugin.ai-pipeline.typenacos.plugin.ai-pipeline.{pluginName}.enabled或统一 plugin state使用实现状态替代旧的逗号分隔启动链。nacos.core.auth.plugin.nacos.*、nacos.core.auth.caching.enabled和nacos.core.auth.nacos.anonymous.ai.enablednacos.plugin.auth.nacos.{itemKey}按 definition 暴露的 canonical item key 迁移每个默认鉴权配置项。nacos.core.auth.ldap.*nacos.plugin.auth.ldap.{itemKey}LDAP item 名称使用 canonical kebab-case definition。nacos.core.auth.plugin.oidc.*nacos.plugin.auth.oidc.{itemKey}OIDC item 名称使用 canonical definition当前全部 OIDC 配置仍为RESTART。db.*和 JVM 参数QUERYTIMEOUTnacos.plugin.datasource.db.*数据源参数仍是只在重启后生效的模块配置不进入插件 PUT API。executable、path、useLlm、apiKey等历史 AI Pipeline 相对 item key 和其他 camel-case aliasnacos.plugin.ai-pipeline.{pluginName}.*下的 canonical kebab-case item key精确 alias 清单由 AI Pipeline 插件规范记录。nacos.ai.resource.import.enablednacos.plugin.ai-resource-import.enabled标准模块 key 保持权威默认开启。nacos.plugin.ai.importer.*.enablednacos.plugin.ai-resource-import.{pluginName}.enabled或统一 plugin state把旧内置 source 状态 key 迁移到受管实现状态。nacos.plugin.ai.importer.*item 配置nacos.plugin.ai-resource-import.{pluginName}.{itemKey}把 display、description、limits 和 endpoint 输入迁移到受管 source 身份。nacos.ai.resource.import.allow-user-url受管 source endpoint 配置用户 URL 直接导入兼容和旧 MCP import adapter 计划在 Nacos 3.4.0 移除。ConfigChangeConfigsproperty bridgeConfigChangePluginService上的 definitions 和 callbacks3.x 窗口内没有 definitions 的旧二进制插件继续接收历史 properties。VisibilityService.init(Properties)从PluginConfigSpec继承的 definitions 和 callbacks统一生命周期在 visibility 执行前应用 effective item-key map。CustomEnvironmentPluginManager.join(...)通过PRE_CONTEXTinitializer 发现 Environment SPIEnvironment 实现必须在 Spring environment 定制开始前可被发现。旧的nacos.ai.resource.import.legacy-mcp-api-enabled输入不再识别废弃 MCP Import API 改用 兼容与废弃策略规范 定义的共享nacos.core.api.compatibility.enabled门禁。nacos.core.auth.enabled等核心模块总开关、PluginConfigSpec的空 definitions 默认实现以及旧版零配置插件实现的二进制加载兼容不属于本移除清单。运行时状态约束与配置更新兼容性对于每次运行时操作都会重新选择实现的插件类型领域执行链路必须在调用扩展前检查统一插件状态。当前使用该门禁的插件包括auth、datasource-dialect、encryption、trace、visibility、config-change、ai-pipeline和ai-storage。被禁用的插件仍保持加载并可由管理 API 查询但不得参与领域执行。持久化状态变更必须遵循validate、persist、apply 顺序先校验完整候选终态再写入持久化状态只有持久化成功后才能修改管理器内存状态。持久化失败时内存保持原值并允许重试。localOnly状态变更按定义跳过持久化只应用到当前节点。plugin_state一致性组可能在 Spring context 创建期间恢复快照快照中的statesmap 表示完整的持久化 override 而非增量 patch恢复时必须整体替换本机持久化 map快照中缺失的条目用于移除本机陈旧 override。配置更新 API 保持 additive 兼容已有config和configDefinitions字段继续保留config可以表示当前 effective config新增的configValueMetasmap 按 canonical item key 提供 source 和 overridden 等元信息。PUT /v3/admin/core/plugin/config保持完整 override map 更新语义localOnlytrue表示只更新当前节点 local-only override否则更新集群级 runtime persisted override。effectModeRESTART的字段不应通过运行时更新立即生效新增、修改或移除RESTART配置项都必须拒绝。对于声明为sensitivetrue的配置项提交值只要包含统一的******marker 就按脱敏展示值处理如果当前目标 source 已包含该 key服务端应保留原始值如果目标 source 不包含该 key则忽略这项输入。该判断同时覆盖******、a******z和ab******yz且不得把STATIC等其他 source 的 effective value 复制成 runtime override。管理 API核心插件管理 API 如下均属于 Admin API并要求符合 HTTP 鉴权规范 中的控制台域鉴权同时必须使用标准 v3 响应与错误模型方法路径目的GET/v3/admin/core/plugin/list查询已加载插件可按类型过滤。GET/v3/admin/core/plugin/detail查询单个插件详情返回 effective config 和可选值元数据。PUT/v3/admin/core/plugin/status启用或禁用插件。PUT/v3/admin/core/plugin/config更新插件配置。集成测试 PluginAdminApiOpenApiITCase.java 对这些端点的行为给出了可直接对照的验证list 与 detaillist 响应中每个插件必须携带pluginId含:、pluginType、pluginName、typeCritical、executionMode、exclusive字段按pluginType过滤只返回该类型未知类型过滤返回空列表detail 返回与 list 一致的 identity并追加enabled、configurable、configValueMetas配置元数据对auth类型的nacos实现detail 暴露 5 个configDefinitions包括token.secret.keySTRING、RESTART、sensitive、token.expire.secondsNUMBER、RUNTIME、token.cache.enableBOOLEAN、RUNTIME、caching.enabledBOOLEAN、RUNTIME、anonymous.ai.enabledBOOLEAN、RUNTIME其中敏感项token.secret.key在响应中已脱敏为******而configValueMetas正确标记了token.secret.key的来源为STATIC、anonymous.ai.enabled的来源为DEFAULT边界与错误status 更新必须携带pluginNameconfig 更新必须携带config且拒绝不可配置插件禁用 critical 实现、对互斥类型做运行时切换都会被拒绝且不产生变更符合critical 类型必须保留可用实现互斥选择只能重启生效的约束。控制台配置流程要点控制台插件详情以 detail API 返回的 effective value、definition 和 value metadata 作为唯一权威输入并遵守以下规则RUNTIME字段使用可编辑控件RESTART字段只读并提示通过 Nacos 配置文件修改后重启生效展示 effective source 和 overridden 状态但不得获得或显示未脱敏的敏感值将集群级 runtime persisted 更新与当前节点 local-only 更新作为两个明确、独立的模式按完整 map 更新契约重建目标 source只把 effective metadata 指向目标 source 的现有值作为基线再合并用户编辑和显式移除 override 的操作不能因为提交了表单就把STATIC或DEFAULT的 effective value 复制成运行时 override。由于 effectiveLOCAL_ONLY值可能遮住同一字段已经存在的 runtime persisted 值只要当前节点仍有任意 local-only override控制台就必须阻止提交集群配置可以通过localOnlytrue提交空 map 完整清空当前节点的 local-only source。插件实现设计要求插件实现必须遵守以下规则使用已有 Nacos 资源标识和领域模型不为同一资源发明不兼容的新模型插件提供的 HTTP API 必须保持 v3 HTTP API 响应、错误和鉴权约定仅通过PluginConfigSpec暴露插件自身拥有的配置除调用方明确要求本机操作用于诊断或应急处理外集群级状态变更必须保持同步安全敏感的默认值和部署要求必须在插件实现规范中说明。扩展规范阅读地图按插件规范树的五大分类深入各领域契约时建议按需查阅对应规范文档通用模型plugin-spec.md本文核心依据、addressing-plugin-spec.md数据与配置datasource-dialect-plugin-spec.md、default-datasource-dialect-plugin-spec.md、config-change-plugin-spec.md、config-encryption-plugin-spec.md运行时扩展environment-plugin-spec.md、trace-plugin-spec.md、control-plugin-spec.md、default-control-plugin-spec.mdAI 扩展ai-pipeline-plugin-spec.md、ai-storage-plugin-spec.md、ai-vector-plugin-spec.md、ai-resource-import-plugin-spec.md安全扩展auth-plugin-spec.md、ram-auth-plugin-spec.md、oidc-auth-plugin-spec.md、visibility-plugin-spec.md。与之配套的 SPI 与元数据模型集中在 api/src/main/java/com/alibaba/nacos/api/plugin 包下PluginType、PluginProvider、PluginConfigSpec、PluginTypePolicy、PluginExecutionMode、PluginStartupLifecycle、PluginStateCheckerHolder等管理 API 的行为可对照 PluginAdminApiOpenApiITCase.java 理解。在实际部署中插件选择与启停的静态配置均写入application.properties可参考 distribution/conf/application.properties而运行时配置与状态通过前述管理 API 与集群同步链路维护。【免费下载链接】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），仅供参考