插件化概览

Nacos 的插件化体系用于把可替换、可扩展的能力从核心流程中解耦出来。用户可以按需选择官方默认实现、官方可选插件、社区插件，也可以根据企业内部的安全、数据库、审计、观测和治理要求开发自定义插件。

插件机制主要面向两类人：

• 使用者和运维人员：需要知道某类能力是否可以通过插件启用，插件应该放在哪里，哪些配置需要保持集群一致。
• 开发者和集成方：需要知道插件 SPI 的边界，如何声明实现类，如何避免插件影响 Nacos 主链路稳定性。

插件加载方式

Nacos 插件大多基于 Java SPI 加载。插件 JAR 中需要在 META-INF/services 下声明对应 SPI 接口的实现类。Nacos 启动时通过 NacosServiceLoader 发现实现，再由各插件类型的 PluginProvider 汇总成统一的插件信息。

在部署时，通常有两种方式让 Nacos 加载插件：

1. 将插件 JAR 放入 ${nacos.home}/plugins。
2. 将插件 JAR 和所需依赖加入 Nacos Server 启动 classpath。

生产集群中，所有 Nacos Server 节点应使用相同版本的插件 JAR、依赖 JAR 和插件配置。尤其是鉴权、数据源、可见性、配置变更、环境变量处理这类会影响请求结果或数据读写的插件，更需要先在测试环境完成验证。

插件选择规则

不同插件类型的启用方式并不完全相同。阅读子文档时，需要注意以下差异：

• 单选型插件：同一时间通常只选择一个实现。例如鉴权插件通过 nacos.core.auth.system.type 选择实现，数据源方言插件通过 spring.sql.init.platform 选择数据库类型。
• 多实现插件：可以同时加载多个实现，并由插件内部顺序或订阅关系决定执行方式。例如配置变更插件、Trace 插件可以有多个实现。
• 默认实现和可选实现：Nacos 发行包中会包含部分默认实现；LDAP、OIDC/OAuth、社区数据源、加密等能力可能需要引入独立插件或扩展包。
• 统一插件状态和业务配置不同：Nacos 3.2 起有统一插件管理能力，但具体插件是否真正参与业务流程，仍需要按对应插件文档配置。例如配置变更插件、环境变量插件和流量防护插件都有自己的启用配置。

插件开发原则

开发插件时，建议遵循以下原则：

• 只扩展明确的 SPI 边界：不要依赖 Nacos 内部非公开类作为长期稳定契约。确实需要参考实现时，以目标版本源码为准。
• 插件名称稳定且唯一：插件名称会用于配置选择、日志识别和插件状态管理。名称变更会影响升级和运维。
• 避免阻塞主链路：涉及网络、磁盘、审计系统、外部 KMS、Webhook 的插件应设置超时、失败降级和独立线程池。
• 不在插件中硬编码敏感信息：密钥、token、数据库密码等应来自安全配置、环境变量或企业密钥系统。
• 版本严格匹配：插件 API 可能随 Nacos 版本演进。升级 Nacos 前，请同时验证插件版本、依赖版本和配置兼容性。
• 先验证再上线：上线前至少验证插件加载日志、核心读写路径、异常降级、节点重启、滚动升级和回滚。

插件文档入口

插件	适用场景
鉴权插件	接入默认 RBAC、LDAP、OIDC/OAuth2 或自定义身份认证和权限校验。
可见性插件	控制 AI 资源等对象对当前调用者是否可见，常与鉴权插件配合使用。
多数据源插件	使用 MySQL、PostgreSQL、Oracle、Derby 或社区数据库方言插件。
配置加密插件	对敏感配置内容进行加密存储和读取解密。
配置变更插件	在配置发布、删除、导入等操作前后做校验、审计或 Webhook 通知。
轨迹追踪插件	订阅 Nacos 内部操作事件，用于审计、排障和运维观测。
自定义环境变量插件	在 Nacos 读取配置项时做自定义转换，例如数据库密码解密。
流量防护插件	对连接数、TPS 等访问流量进行限制，保护服务端稳定性。
集群寻址机制	配置 Nacos Server 集群成员发现方式，例如 file 和 address-server。
AI 发布 Pipeline 插件	在 Skill、Prompt、MCP、AgentSpec 等 AI 资源发布前接入审核、扫描或拦截。
AI 资源导入插件	从 MCP registry、Skill 市场或企业内部资源库导入 AI 资源。
AI 存储插件	为 AI 资源版本内容接入自定义存储 provider。

关联建议

如果你只是部署和运维 Nacos，建议优先阅读鉴权、可见性、多数据源、配置加密、流量防护、集群寻址机制和 AI 资源导入。它们直接影响生产环境的安全边界、数据存储、稳定性和资源来源。

如果你需要开发插件，建议先读本页，再阅读目标插件的 SPI、加载方式和故障降级说明。不同插件接入点不同，不建议照搬另一个插件的配置项或生命周期。