一、操作场景
·慢命令导致集群异常：因高耗时命令（如 KEYS、HGETALL）导致实例 CPU 飙升甚至集群故障，业务侧整改路径较长，需要快速限流恢复。
·突发流量冲击：不可预期的业务高峰导致 QPS 激增，需要通过限流保障主流业务的可用性。
·异常客户端治理：特定客户端 IP 产生异常请求，需要精准限制该来源的访问。
二、背景信息
SQL 限流功能基于 Distributed Cache Proxy 层实现，直连模式实例不包含 Proxy 节点，因此该功能仅适用于代理模式实例。通过在 Proxy 侧配置限流规则，在命令转发前进行匹配和拦截。限流规则支持命令、Key、客户端 IP 三个维度的自由组合，并可配置限流比例和持续时长。
限流策略说明：
·单个规则内（如命令规则中配置多个命令关键字），多个关键字之间的关系为逻辑或。
·配置多个规则时（如客户端 IP 规则 + 命令规则），多个规则之间的关系为逻辑与。
·多规则多关键字场景：限流策略集合为 IP 数量 × 命令数量 × Key 数量 的笛卡尔积组合，各组合之间的关系为逻辑或。
三、实现原理
SQL 限流采用基于会话模式的异步调度架构。
1. 规则创建：用户通过控制台创建限流规则，系统将规则写入数据库并创建限流会话。
2. 规则部署：后台协调器（Coordinator）自动发现新会话，通过分布式锁接管后，由执行器（Executor）将规则全量部署到 Distributed Cache Proxy（Distributed CacheShark）。
3. 规则生效：部署成功后规则立即在 Proxy 层生效，匹配的命令按配置比例被拦截。
4. 统计同步：系统定时从 ES 同步限流统计数据（累计限流次数等）。
5. 规则结束：定时关闭的规则到期后自动失效；手动关闭的规则由用户主动终止。
四、使用限制
| 限制项 | 限制说明 |
| 支持的数据库类型 | 当前仅支持代理模式（Proxy 模式）实例，直连模式实例不支持 SQL 限流功能。具体支持的 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 限流任务，在任务列表上方单击删除，单击确定。
十二、故障背景
某电商平台 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. 清理历史记录：勾选已结束的任务，单击批量删除。
十八、Q1：创建限流规则后多久生效？
规则从创建到生效通常在 30 秒内完成。如果超过 1 分钟仍未生效，请检查实例是否处于正常运行状态，或在规则列表中查看任务状态是否为执行失败。
十九、Q2：为什么已拒绝命令数显示为 0？
限流统计数据从 ES 异步同步，存在上报延迟。规则刚生效时统计数据可能尚未更新，请稍后刷新查看。查看单条规则详情时，系统会主动从 ES 补拉最新数据。
20、Q3：限流规则可以修改吗？
不支持。已创建的限流规则不可修改，如需调整限流条件或比例，请先关闭当前规则，再创建新的规则。
21、Q4：创建规则时提示“已存在相同组合的未结束策略”？
同一实例下不允许创建相同 命令 + IP + Key 组合的未结束规则。请先关闭已有的同组合规则后重新创建。
22、Q5：限流比例 100% 和普通限流有什么区别？
限流比例为 100% 表示完全禁止所有匹配命令的执行，即匹配的请求会被 100% 拦截。其他比例（如 50%）则按概率拦截，即约有 50% 的匹配请求会被放行。