wehub-resource-sync
266 lines
14 KiB
Markdown
266 lines
14 KiB
Markdown
<!--
|
||
Copyright 1999-2026 Alibaba Group Holding Ltd.
|
||
|
||
Licensed under the Apache License, Version 2.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
You may obtain a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS,
|
||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|
||
-->
|
||
|
||
# Nacos 插件化规范
|
||
|
||
## 目的
|
||
|
||
Nacos 使用插件机制和 SPI 扩展，将横切基础能力和可替换的领域能力从固定核心中拆出。
|
||
插件可以提供鉴权、资源可见性、数据源方言、加解密、链路追踪、流量控制、环境适配、
|
||
AI pipeline、AI 存储、AI 资源导入或 Java 客户端侧请求适配等能力。
|
||
|
||
插件机制的目标，是在保持 Nacos 核心模型稳定的同时，让不同部署环境可以选择符合自身
|
||
身份系统、数据库、观测体系或扩展场景的实现。
|
||
|
||
## 插件身份
|
||
|
||
每个插件由以下字段唯一标识：
|
||
|
||
- `pluginType`：扩展类别，例如 `auth` 或 `visibility`。
|
||
- `pluginName`：该类别下的实现名称，例如 `nacos`。
|
||
- `pluginId`：运行时标识，格式为 `{pluginType}:{pluginName}`。
|
||
|
||
`pluginId` 用于管理 API、集群状态同步、插件状态持久化和面向用户的诊断信息。
|
||
|
||
## 插件类型
|
||
|
||
当前插件类型注册表由 `PluginType` 定义。
|
||
|
||
| 类型 | 目的 | 契约 |
|
||
|------|------|------|
|
||
| `auth` | 认证与授权实现。 | [鉴权插件规范](../auth/auth-plugin-spec.md) |
|
||
| `visibility` | 资源可见性与查询可见性建议。 | [可见性插件规范](../auth/visibility-plugin-spec.md) |
|
||
| `datasource-dialect` | 数据库方言与持久化适配。 | [数据源方言插件规范](datasource-dialect-plugin-spec.md) |
|
||
| `config-change` | 配置变更扩展。 | [配置变更插件规范](config-change-plugin-spec.md) |
|
||
| `encryption` | 加解密扩展。 | [配置加密插件规范](config-encryption-plugin-spec.md) |
|
||
| `trace` | 链路追踪与观测扩展。 | [Trace 插件规范](trace-plugin-spec.md) |
|
||
| `environment` | 环境适配扩展。 | [环境插件规范](environment-plugin-spec.md) |
|
||
| `control` | 流量与控制扩展。 | [Control 插件规范](control-plugin-spec.md) |
|
||
| `ai-pipeline` | AI 注册中心 pipeline 扩展。 | [AI 发布 Pipeline 插件规范](ai-pipeline-plugin-spec.md) |
|
||
| `ai-storage` | AI 注册中心存储扩展。 | [AI 存储插件规范](ai-storage-plugin-spec.md) |
|
||
| `ai-resource-import` | AI 注册中心外部资源导入扩展。 | [AI 资源导入插件规范](ai-resource-import-plugin-spec.md) |
|
||
|
||
各插件类别的领域契约由对应规范定义。本文档定义所有插件类别共享的运行时契约。
|
||
|
||
[寻址扩展](addressing-plugin-spec.md)为了和公开插件文档保持连续性，也放在插件
|
||
规范中记录；但当前服务端代码通过 `MemberLookup` 处理寻址，并未将其注册到
|
||
`PluginType`。
|
||
|
||
## 运行位置
|
||
|
||
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 发出的请求。
|
||
|
||
## 执行形态
|
||
|
||
插件类别并不都以同一种形态执行。每个插件类型都必须明确自身执行形态。
|
||
|
||
| 形态 | 含义 | 示例 |
|
||
|------|------|------|
|
||
| 互斥选择 | 在进程或请求范围内选择一个实现，其他已加载实现不参与该次判断。 | `auth`、`datasource-dialect` |
|
||
| 配置选择的单服务 | 可以加载多个实现，但领域根据配置或请求上下文选择一个服务。 | `visibility`、`ai-resource-import` |
|
||
| 有序链式执行 | 多个匹配插件按稳定顺序执行。每个节点可以贡献结果，失败是否中断由领域定义。 | `ai-pipeline`、`config-change` |
|
||
| 订阅或广播 | 多个订阅者观察同一个事件或 trace 点，不拥有主决策权。 | `trace`、事件型扩展 |
|
||
|
||
对于链式插件，领域 SPI 必须定义：
|
||
|
||
- 如何根据资源或 pointcut 选择候选插件。
|
||
- 哪个字段控制顺序，例如 `getPreferOrder()` 或 `getOrder()`。
|
||
- 执行方式是串行还是并行。
|
||
- 某个插件失败时，是中断链路还是只记录失败结果。
|
||
- 如何持久化和暴露部分执行结果。
|
||
|
||
核心插件管理器记录插件的加载状态和启用状态，本身不定义执行形态。领域管理器负责稳定地
|
||
应用对应执行形态。
|
||
|
||
## SPI 层次
|
||
|
||
Nacos 插件包含两个相关的 SPI 层次：
|
||
|
||
1. 领域 SPI，例如 `AuthPluginService` 或 `VisibilityService`，定义所属领域需要的行为。
|
||
2. 核心插件 SPI，即 `PluginProvider`，将插件实例暴露给核心插件管理器，用于列表查询、
|
||
状态管理、配置管理和运行时观测。
|
||
|
||
需要动态配置的插件应实现 `PluginConfigSpec`。支持启停状态判断的插件类别，应通过
|
||
`PluginStateCheckerHolder` 获取状态，而不是维护一套独立状态来源。
|
||
|
||
## 加载与生命周期
|
||
|
||
插件实现通过 Nacos SPI 加载。部署时可以从 classpath 或服务端插件目录提供插件。
|
||
插件实现必须能在不修改 Nacos 服务端代码的情况下被加载。
|
||
|
||
核心 `PluginManager` 会在服务端应用就绪后发现 `PluginProvider` 实现。领域管理器也可以
|
||
通过 SPI 加载自身领域服务，但是否可参与请求处理，仍必须遵守核心插件管理器维护的启停
|
||
状态。
|
||
|
||
插件启动必须具备确定性：
|
||
|
||
- 一个插件类型和插件名称组合只能对应一个运行时插件实例。
|
||
- 同一插件类型下重复的插件名称不适合稳定运行。
|
||
- 插件实现不得改变 Nacos 共享资源标识、响应封装或错误约定的含义。
|
||
|
||
## 状态与配置
|
||
|
||
插件状态分为两个层次：
|
||
|
||
- 已加载：实现存在于运行时。
|
||
- 已启用：实现可以参与请求处理。
|
||
|
||
大多数插件类型在加载后默认启用。互斥插件类型会选择一个默认实现：
|
||
|
||
| 类型 | 默认选择规则 |
|
||
|------|--------------|
|
||
| `auth` | 由 `nacos.core.auth.system.type` 指定，默认 `nacos`。 |
|
||
| `datasource-dialect` | 由 SQL platform 配置指定，默认 `derby`。 |
|
||
|
||
当服务端依赖某些插件维持基本运行能力时，这些插件不能被禁用。当前关键插件集合包括内置
|
||
数据源方言，以及服务端需要的默认 AI 存储插件。
|
||
|
||
实现 `PluginConfigSpec` 的插件应暴露配置定义、当前配置和配置应用行为。除非请求明确
|
||
声明为仅本机生效，否则集群级状态或配置变更必须通过插件状态操作链路进行同步。
|
||
|
||
### 配置定义
|
||
|
||
插件配置项由 `ConfigItemDefinition` 描述。`key` 表示插件实现内部的 canonical item
|
||
key，不携带 `nacos.plugin.{pluginType}.{pluginName}.` 前缀。静态配置推荐使用以下
|
||
normalized full key：
|
||
|
||
```text
|
||
nacos.plugin.{pluginType}.{pluginName}.{itemKey}
|
||
```
|
||
|
||
配置定义可以声明以下元数据：
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `aliases` | 历史静态配置 key，用于兼容读取和迁移提示。 |
|
||
| `sensitive` | 是否为敏感值。查询 API 返回前必须脱敏。 |
|
||
| `effectMode` | 生效模式，`RUNTIME` 表示可运行时生效，`RESTART` 表示需要重启。 |
|
||
|
||
`aliases` 用于静态配置兼容读取，也可以作为迁移兼容的 API 输入。完成归一化后，alias
|
||
不应写入运行时持久化文件或 local-only 内存表。如果输入同时包含同一配置项的多个
|
||
alias，则按定义中的声明顺序取第一个生效，并由服务端记录其余 alias 被忽略的日志。
|
||
|
||
### 配置来源与值元数据
|
||
|
||
插件配置的 effective value 由统一解析流程计算。配置来源优先级为：
|
||
|
||
```text
|
||
LOCAL_ONLY > RUNTIME_PERSISTED > STATIC > DEFAULT
|
||
```
|
||
|
||
| 来源 | 含义 |
|
||
|------|------|
|
||
| `DEFAULT` | 来自 `ConfigItemDefinition.defaultValue`。 |
|
||
| `STATIC` | 来自 `application.properties`、环境变量、JVM 参数或 Spring 参数等静态配置。 |
|
||
| `RUNTIME_PERSISTED` | 来自集群级运行时 override，当前可由 `plugin-configs.json` 记录终态内容。 |
|
||
| `LOCAL_ONLY` | 当前节点的本机 override，只用于诊断或应急处理，不同步到集群。 |
|
||
|
||
插件详情返回模型可以追加以 canonical item key 为索引的 `configValueMetas` map。每个
|
||
`PluginConfigValueMeta` 用于描述对应配置项的当前值来源和是否存在多来源覆盖。
|
||
`overridden` 忽略 `DEFAULT`，只有同一 key 同时存在多个非默认来源时才应为 `true`。
|
||
|
||
运行时持久化配置和 local-only 配置只保存 `pluginId + itemKey` 对应的值，不保存
|
||
normalized full key、alias key、source 或版本信息。
|
||
|
||
每个内部 source resolver 都必须通过 `getConfig(PluginInfo)` 返回使用 canonical
|
||
item key 的完整 map。读取能力与写入能力相互独立：`DEFAULT` 从 definition 读取默认值，
|
||
`STATIC` 根据标准 key 和 alias 从环境读取，两个运行时 source 读取各自内部 map。
|
||
`isUpdatable` 只在替换 source map 时检查。每次更新完整替换该 source 的 map；传入空
|
||
map 表示清空该插件在该 source 下的全部 override，不额外提供 remove 或 restore 操作。
|
||
|
||
### 配置更新兼容性
|
||
|
||
插件详情 API 应保持 additive 兼容：已有 `config` 和 `configDefinitions` 字段继续
|
||
保留，其中 `config` 可以表示当前 effective config，新增的 `configValueMetas` map 按
|
||
canonical item key 提供 source 和 overridden 等元信息。
|
||
|
||
`PUT /v3/admin/core/plugin/config` 和对应 Console API 保持现有完整 override map
|
||
更新语义。`localOnly=true` 表示只更新当前节点 local-only override；否则更新集群级
|
||
runtime persisted override。key 归一化和 `effectMode` 校验由服务端内部完成，不作为
|
||
新的 API 参数暴露。`effectMode=RESTART` 的字段不应通过运行时更新立即生效。
|
||
服务端应比较目标 source 更新前后的完整 map，因此新增、修改或移除 `RESTART` 配置项
|
||
都必须拒绝。提交的完整 map 中省略某个 key，只有在该配置项支持运行时生效时才表示
|
||
移除对应 override。
|
||
canonical item key、normalized full key 和兼容 alias key 应在校验及存储前统一归一化为
|
||
item key。请求包含未定义 key，或者 alias 歧义命中多个配置项时，应返回参数校验错误。
|
||
|
||
对于声明为 `sensitive=true` 的配置项，提交值只要包含统一的 `******` marker，就按
|
||
脱敏展示值处理。如果当前目标 source 已经包含该 key，服务端应保留该 source 中的原始
|
||
值；如果目标 source 不包含该 key，则忽略这项输入，继续保持该 source 不存在此 key。
|
||
该判断同时覆盖 `******`、`a******z` 和 `ab******yz`，且不得把 `STATIC` 等其他
|
||
source 的 effective value 复制成 runtime override。服务端应记录 WARN 日志，但只记录
|
||
`pluginId`、item key 和目标 source，不得打印配置值。
|
||
|
||
### 初始化与运行时应用
|
||
|
||
启动和运行时更新复用同一套 source resolver 与 effective config 计算逻辑：
|
||
|
||
1. 启动时先将 `plugin-configs.json` 中的全部内容装载到 runtime persisted source，
|
||
再开始应用插件配置。
|
||
2. 随后对每个已加载的可配置插件执行 resolve 和 apply，即使该插件没有持久化
|
||
override 也要处理。启动属于初始化阶段，可以同时应用 `RUNTIME` 和 `RESTART`
|
||
字段。
|
||
3. 运行时请求完整替换一个 `RUNTIME_PERSISTED` 或 `LOCAL_ONLY` source map，随后
|
||
重新解析全部来源；每次接受的请求都调用插件实现，包括使用相同完整 map 发起的
|
||
手动重试。
|
||
|
||
同一插件的更新应串行执行。runtime persisted 更新先持久化归一化后的完整 source
|
||
map，再替换 resolver source、解析并校验 effective config，最后应用到插件。持久化
|
||
失败时不得修改 resolver source 或插件，也不执行回滚。source 更新成功但 apply 失败
|
||
时，已接受的 source map 保持持久化和可解析状态，服务端不自动发起回滚或补偿更新；
|
||
API 应明确返回“配置已更新但 apply 失败”的服务端错误，日志记录 plugin ID 和 source
|
||
且不记录配置值。再次提交相同完整 map 可以手动重试 apply。`LOCAL_ONLY` 更新执行相同
|
||
的 replace、resolve、apply 流程，但不持久化、不同步；apply 失败后新的本机 source map
|
||
同样保留。
|
||
|
||
## 管理 API
|
||
|
||
核心插件管理 API 如下：
|
||
|
||
| 方法 | 路径 | 目的 |
|
||
|------|------|------|
|
||
| `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` | 更新插件配置。 |
|
||
|
||
这些端点属于 Admin API，并要求符合 [HTTP 鉴权规范](../http-api/authorization-spec.md)
|
||
中的控制台域鉴权。插件管理 API 必须使用标准 v3
|
||
[响应与错误模型](../http-api/response-error-spec.md)。
|
||
|
||
## 设计要求
|
||
|
||
插件实现必须遵守以下规则：
|
||
|
||
- 使用已有 Nacos [资源标识](../design/resource-model-spec.md)和领域模型，不为同一
|
||
资源发明不兼容的新模型。
|
||
- 插件提供的 HTTP API 必须保持 v3 [HTTP API](../http-api/api-spec.md) 响应、错误和
|
||
鉴权约定。
|
||
- 仅通过 `PluginConfigSpec` 暴露插件自身拥有的配置。
|
||
- 除调用方明确要求本机操作用于诊断或应急处理外，集群级状态变更必须保持同步。
|
||
- 安全敏感的默认值和部署要求必须在插件实现规范中说明。
|
||
|
||
插件机制是扩展边界，不是绕过 Nacos 资源、API 或安全规则的通道。
|