wehub-resource-sync
161 lines
6.2 KiB
Markdown
161 lines
6.2 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.
|
|
-->
|
|
|
|
# Control 插件规范
|
|
|
|
## 范围
|
|
|
|
Control 插件为 Nacos 服务端节点提供运行时流量和连接控制。它覆盖连接准入、TPS 检查、规则
|
|
解析、规则存储和可选指标采集。
|
|
|
|
这是配置选择的单服务插件。配置的 control manager type 会选择一个 `ControlManagerBuilder`。
|
|
如果未配置类型，或选中的插件无法加载，Nacos 使用无上限的默认 manager。通用生命周期和
|
|
状态规则由 [Nacos 插件化规范](plugin-spec.md) 定义，内置实现由
|
|
[默认 Control 插件实现规范](default-control-plugin-spec.md) 定义。
|
|
|
|
Control 是 Nacos 的反脆弱机制。它在某个控制点访问量超过规则时，对连接或请求进行监控或
|
|
拒绝，用于保护当前服务端节点。Control 插件不得改变资源语义；它只判断当前连接或请求能否
|
|
继续执行。
|
|
|
|
HTTP 和 gRPC TPS control 钩子通过
|
|
[请求过滤与运行时上下文规范](../design/foundation-request-context-spec.md)定义的共享请求过滤模型接入。
|
|
|
|
## 概念
|
|
|
|
| 概念 | 含义 |
|
|
|------|------|
|
|
| Control point | 可被度量和限制的命名运行时资源。 |
|
|
| Connection control | 针对长连接或长轮询连接的准入控制。 |
|
|
| TPS control | 针对命名 API 操作点的请求频率准入控制。 |
|
|
| Rule storage | 持久化本地或外部分发规则文本的存储。 |
|
|
| Rule parser | 将规则文本解析成运行时规则对象的解析器。 |
|
|
| Barrier | 某个 TPS point 的运行时计数与决策组件。 |
|
|
|
|
连接控制和 TPS 控制彼此独立。部署可以同时提供两个 manager，也可以只提供其中一个，
|
|
缺失的维度按无上限处理。
|
|
|
|
## SPI
|
|
|
|
Control 插件实现 `ControlManagerBuilder`。
|
|
|
|
| 方法 | 要求 |
|
|
|------|------|
|
|
| `getName()` | 稳定插件名称。 |
|
|
| `buildConnectionControlManager()` | 构造连接控制 manager。 |
|
|
| `buildTpsControlManager()` | 构造 TPS 控制 manager。 |
|
|
|
|
外部规则存储插件实现 `ExternalRuleStorageBuilder`，并通过 control 配置独立选择。
|
|
|
|
该插件以 `control` 类型暴露给核心插件管理器。
|
|
|
|
## Manager
|
|
|
|
`ConnectionControlManager` 拥有连接规则，并为连接准入返回 `ConnectionCheckResponse`。
|
|
它可以加载 `ConnectionMetricsCollector` 实现来上报连接指标。
|
|
|
|
连接 manager 必须满足：
|
|
|
|
| 方法 | 要求 |
|
|
|------|------|
|
|
| `applyConnectionLimitRule(rule)` | 应用最新连接规则。 |
|
|
| `check(request)` | 返回连接准入的通过或拒绝结果。 |
|
|
| `buildConnectionControlRuleParser()` | 可以覆盖规则文本解析器。 |
|
|
|
|
`TpsControlManager` 拥有 TPS point、TPS 规则和 barrier，并为 TPS 准入返回
|
|
`TpsCheckResponse`。
|
|
|
|
TPS manager 必须满足：
|
|
|
|
| 方法 | 要求 |
|
|
|------|------|
|
|
| `registerTpsPoint(pointName)` | 在启动或路由扫描时注册控制点。 |
|
|
| `applyTpsRule(pointName, rule)` | 应用或移除某个 point 的规则。 |
|
|
| `check(request)` | 返回 TPS 请求的通过或拒绝结果。 |
|
|
| `buildTpsControlRuleParser()` | 可以覆盖规则文本解析器。 |
|
|
| `buildTpsBarrierCreator()` | 可以覆盖时间窗口和计数行为。 |
|
|
|
|
## 规则模型
|
|
|
|
`ConnectionControlRule` 包含：
|
|
|
|
| 字段 | 含义 |
|
|
|------|------|
|
|
| `countLimit` | 最大总连接数。小于 0 表示不限制。 |
|
|
| `monitorIpList` | 需要详细记录连接行为的 IP 列表。 |
|
|
|
|
`TpsControlRule` 包含：
|
|
|
|
| 字段 | 含义 |
|
|
|------|------|
|
|
| `pointName` | 控制点名称。 |
|
|
| `pointRule` | 控制点规则详情。 |
|
|
|
|
`RuleDetail` 包含：
|
|
|
|
| 字段 | 含义 |
|
|
|------|------|
|
|
| `ruleName` | 规则标识。自定义插件可以让一个 point 拥有多个规则名。 |
|
|
| `maxCount` | 周期内最大允许次数。小于 0 表示不限制。 |
|
|
| `period` | 计数周期，内置默认值为秒。 |
|
|
| `monitorType` | `monitor` 表示只观测，`intercept` 表示拒绝。 |
|
|
|
|
## 规则存储
|
|
|
|
规则可以来自本地磁盘存储，也可以来自外部规则存储插件。本地规则始终是安全基线。只有当
|
|
选中的 control 插件明确要求时，外部规则存储失败才应导致 fail closed。
|
|
|
|
规则重载通过 control 规则变更事件发布，并由当前活跃 manager 应用。本地事件分发遵循
|
|
[事件分发与 NotifyCenter 规范](../design/foundation-event-dispatch-spec.md)。
|
|
Control 指标和拒绝观测遵循
|
|
[可观测钩子规范](../design/foundation-observability-hooks-spec.md)。
|
|
|
|
外部规则存储通过以下配置选择：
|
|
|
|
```properties
|
|
nacos.plugin.control.rule.external.storage=${controlPluginName}
|
|
```
|
|
|
|
本地规则存储基准目录通过以下配置选择：
|
|
|
|
```properties
|
|
nacos.plugin.control.rule.local.basedir=${expectedDir}
|
|
```
|
|
|
|
自定义 control 插件可以通过覆盖规则解析器支持非 JSON 规则文本。自定义 TPS 插件可以通过
|
|
覆盖 barrier creator 支持滑动窗口等其他计数算法。
|
|
|
|
## 选择与状态
|
|
|
|
选中的 manager 实现由以下配置指定：
|
|
|
|
```properties
|
|
nacos.plugin.control.manager.type=${controlPluginName}
|
|
```
|
|
|
|
当通过核心插件管理器集成时，选中的 control 插件还必须遵守 `control:{pluginName}` 的
|
|
统一插件状态。
|
|
|
|
Point name 属于公开 control 契约。新增 `@TpsControl` point 时，必须使用稳定名称，
|
|
记录被保护的操作，并在 HTTP 与 gRPC 端点表达同一个语义操作时复用该名称。
|
|
|
|
## 降级
|
|
|
|
Control 插件会影响请求准入。如果插件构造失败，除非部署明确配置 fail-fast 策略，否则 Nacos
|
|
必须回退到无上限 manager，并记录失败日志。
|
|
|
|
运行时插件异常不得破坏请求状态。对于只观测规则，失败应记录并跳过。对于拦截规则，失败后
|
|
通过、拒绝或 fail fast 由被选中的插件决定，并必须在实现规范中记录。
|