操作场景
当 Distributed Cache 实例遇到以下场景时，可通过 SQL 限流功能对特定命令进行精准限流，保障核心业务不受影响：
慢命令导致集群异常：因高耗时命令（如
KEYS、HGETALL）导致实例 CPU 飙升甚至集群故障，业务侧整改路径较长，需要快速限流恢复。突发流量冲击：不可预期的业务高峰导致 QPS 激增，需要通过限流保障主流业务的可用性。
异常客户端治理：特定客户端 IP 产生异常请求，需要精准限制该来源的访问。
背景信息
SQL 限流功能基于 Distributed Cache Proxy 层实现，通过在 Proxy 侧配置限流规则，在命令转发前进行匹配和拦截。限流规则支持命令、Key、客户端 IP 三个维度的自由组合，并可配置限流比例和持续时长。
限流策略说明：
单个规则内（如命令规则中配置多个命令关键字），多个关键字之间的关系为逻辑或。
配置多个规则时（如客户端 IP 规则 + 命令规则），多个规则之间的关系为逻辑与。
多规则多关键字场景：限流策略集合为
IP 数量 × 命令数量 × Key 数量 的笛卡尔积组合，各组合之间的关系为逻辑或。实现原理
SQL 限流采用基于会话模式的异步调度架构。
1. 规则创建：用户通过控制台创建限流规则，系统将规则写入数据库并创建限流会话。
2. 规则部署：后台协调器（Coordinator）自动发现新会话，通过分布式锁接管后，由执行器（Executor）将规则全量部署到 Distributed Cache Proxy（Distributed CacheShark）。
3. 规则生效：部署成功后规则立即在 Proxy 层生效，匹配的命令按配置比例被拦截。
4. 统计同步：系统定时从 ES 同步限流统计数据（累计限流次数等）。
5. 规则结束：定时关闭的规则到期后自动失效；手动关闭的规则由用户主动终止。
使用限制
限制项 | 限制说明 |
支持的数据库类型 | 当前仅兼容 Distributed Cache 云数据库。具体支持的 Proxy 版本要求如下： 兼容版本：5.8.25 及以上版本。 例外版本：5.9.0 版本暂不支持。 |
单实例最大规则数 | 64 条（ IP 数量 × 命令数量 × Key 数量 的笛卡尔积总数不超过 64）。 |
限流比例范围 | 1% ~ 100%（100% 表示完全禁止匹配命令的执行）。 |
规则维度要求 | Key 规则不能为通配符 *。 |
规则修改 | 不支持修改已创建的规则，如需调整请先关闭/删除后重新创建。 |
批量删除上限 | 单次最多删除 100 条规则。 |
重复规则校验 | 同一实例下不允许创建相同 命令 + IP + Key 组合的未结束规则。 |
注意事项
限流规则创建后将对所有匹配的命令请求生效（包括业务读写请求），请谨慎配置限流比例，避免误拦截正常业务流量。
限流比例设置为 100% 时，表示完全禁止所有匹配命令的执行，请确认后再操作。
同一实例上的所有限流规则采用全量覆盖方式部署，新增或关闭规则时会重新部署全部生效中的规则。
当实例 CPU 负载极高时，限流规则的部署可能出现延迟。
前提条件
已创建云数据库 Distributed Cache 实例，且实例状态为运行中。
实例架构支持 Proxy 限流能力（系统会在创建规则前自动校验）。
操作步骤
创建限流任务
1. 登录 DBbrain 控制台。
2. 在左侧导航栏，选择诊断优化。
3. 在页面上方选择 Distributed Cache 数据库类型及实例 ID，选择实时会话页签。
4. 在页面下方可选择 SQL 限流页签。
5. 在页面中单击创建任务，配置以下参数。
参数分类 | 参数 | 说明 |
限流策略 | 命令规则 | 输入需要限流的 Distributed Cache 命令（如 GET、HGETALL），按回车添加，支持配置多个。多个命令之间为逻辑或关系。不填写则默认匹配所有命令。 |
| Key 规则 | 输入需要限流的 Key，按回车添加，支持配置多个。不填写则默认匹配所有 Key。 |
| 客户端 IP 规则 | 输入需要限流的客户端 IP 地址，按回车添加，支持配置多个。不填写则默认匹配所有 IP。 |
限流配置 | 限流比例 | 限流比例，范围 1% ~ 100%，默认值为 100%。如果限流比例为 100%，则表示限制所有匹配命令的执行。 |
限流执行方式 | 执行方式 | 选择定时关闭或手动关闭。选择定时关闭时需配置持续时间，选择手动关闭时规则将持续生效直到用户主动关闭。 |
| 持续时间 | 仅在执行方式为定时关闭时显示。限流任务的持续时间，单位为秒，默认值为 300（即 5 分钟）。 最大支持设置30000秒。 |
说明：
命令规则、Key 规则、客户端 IP 规则三项中至少需要填写一项具体值，不能全部留空（即不允许创建无差别的全量限流规则）。
6. 单击确定，等待规则生效。
查看限流任务
在 SQL 限流页签中，可查看所有限流任务的列表。
单击操作列的详情，可在 SQL 限流详情弹窗中查看任务的详细信息。
字段 | 说明 |
开始时间 | 规则实际开始生效的时间。 |
执行时间 | 限流任务的持续时间，单位为秒。 |
结束时间 | 规则结束的时间。 |
已拒绝命令数 | 累计被限流拦截的命令次数。 |
限流任务开启后，若还在所设置的限流时间以内，列表中的状态为运行中，单击操作列的关闭，单击确定，可以提前关闭限流任务，状态列将变为已结束。
说明：
关闭后规则将从 Proxy 层移除，已被限流的命令将恢复正常执行。
限流任务开启后，若自动达到所设定的限流时间，列表中的状态将变为已结束。
删除限流任务。支持对状态为已终止、已完成和执行失败的限流任务进行删除。
单个删除：单击操作列的删除，单击确定。
批量删除：选择一个或多个 SQL 限流任务，在任务列表上方单击删除，单击确定。
SQL 限流配置示例
案例：限流异常 HGETALL 命令保障核心业务
故障背景
某电商平台 Distributed Cache 集群在业务高峰期出现 CPU 利用率飙升至 95%，经 DBbrain 异常诊断发现，根因为某批次脚本高频执行 HGETALL 命令访问大 Key product:detail:1，导致 Proxy 层处理延迟激增，影响核心下单链路。
业务侧短期内无法完成代码整改，需要紧急限流恢复。
限流方案
配置项 | 值 | 说明 |
命令规则 | HGETALL | 仅限流 HGETALL 命令，不影响 GET/SET 等核心操作。 |
Key 规则 | product:detail:1 | 精准匹配问题 Key 值。 |
客户端 IP 规则 | 不填写（匹配所有 IP） | 该命令来自多个业务节点，不限定来源。 |
限流比例 | 80% | 拦截 80% 的匹配请求，保留 20% 用于关键查询。 |
执行方式 | 定时关闭 | — |
持续时间 | 3600 秒 | 先限流 1 小时，观察效果后决定是否续期。 |
操作步骤
1. 登录 DBbrain 控制台，选择诊断优化，选中实例。
2. 进入实时会话 > SQL 限流页签，单击创建任务。
3. 在创建 SQL 限流任务弹窗中配置参数。
限流策略：命令规则输入 HGETALL 按回车，Key 规则输入 product:detail:1 按回车。
限流配置：限流比例设置为 80。
限流执行方式：执行方式选择定时关闭，持续时间设置为 3600。
4. 单击确定。
效果验证
创建限流任务完成后，在任务列表中确认规则状态变为生效中。
单击详情查看已拒绝命令数，确认限流已生效。
后续处理
1. 1 小时后：规则自动到期，状态变为已结束。观察 CPU 是否回升。
2. 如需延长：在规则结束前创建新的限流任务（规则不可修改，需重新创建）。
3. 业务修复后：若业务侧已完成 HGETALL 改为 HMGET 的优化，可提前单击关闭终止限流。
4. 清理历史记录：勾选已结束的任务，单击批量删除。
常见问题
创建限流规则后多久生效？
规则从创建到生效通常在 30 秒内完成。如果超过 1 分钟仍未生效，请检查实例是否处于正常运行状态，或在规则列表中查看任务状态是否为执行失败。
为什么已拒绝命令数显示为 0？
限流统计数据从 ES 异步同步，存在上报延迟。规则刚生效时统计数据可能尚未更新，请稍后刷新查看。查看单条规则详情时，系统会主动从 ES 补拉最新数据。
限流规则可以修改吗？
不支持。已创建的限流规则不可修改，如需调整限流条件或比例，请先关闭当前规则，再创建新的规则。
创建规则时提示“已存在相同组合的未结束策略”？
同一实例下不允许创建相同
命令 + IP + Key 组合的未结束规则。请先关闭已有的同组合规则后重新创建。限流比例 100% 和普通限流有什么区别？
限流比例为 100% 表示完全禁止所有匹配命令的执行，即匹配的请求会被 100% 拦截。其他比例（如 50%）则按概率拦截，即约有 50% 的匹配请求会被放行。
