组策略配置指南

本指南详细介绍 OLC 的分组（Group）和策略（Policy）概念，以及各种配置模式和实战技巧。

核心概念

Group（分组）

分组是 OLC 匹配请求的最小单元。每个分组由多个 Tag 组成，定义了「哪些请求应该应用这个分组对应的策略」。

一个分组可以只有 Tag（不绑定策略），也可以同时绑定 Flow 策略和/或 Admission 策略。

Tag 的三要素

每个 Tag 有四个关键属性：

属性	说明	示例
`tag`	维度名	`URL`、`Method`、`Model`、`IP`
`match`	匹配方式	`equal`（精确）、`regex`（正则）、`default`（通配）
`values`	匹配值列表	`["/api/chat"]`、`["POST"]`、`["gpt-4"]`
`share`	是否共享策略	`true` 共享、`false` 不共享, equal 情况下只能为false, regex 默认为true， default 默认 false

Policy（策略）

分组可以绑定两种策略：

策略类型	字段	说明
流控策略	`flow`	QPS/并发/配额限流
准入策略	`admission`	允许/拒绝/动态准入

分组与策略是一对多的关系：同一个分组可以同时绑定 Flow 和 Admission。

执行顺序与短路

Admission 策略先执行，拒绝请求后后续策略不执行。 Flow 策略后执行，拒绝请求后后续策略不执行。

priority（优先级）

分组支持 priority 字段，值越小优先级越高（先匹配）。但由于规则按顺序匹配，priority 更多用于区分同级别规则的重要程度。默认优先级为 500。当一请求同时命中多个分组时，同类型规则按优先级执行。优先级相同的规则顺序执行，其中一条规则拒绝请求后，后续规则不执行。该请求会被拒绝拒绝。所有规则执行完成后，请求会被允许通过。

normal vs global 分组类型

normal 类型（默认）：标签值之间做笛卡尔积，每个组合生成一个独立的 TagGroup。

{
  "type": "normal",
  "tags": [
    {"tag": "URL", "values": ["/api/chat", "/api/complete"]},
    {"tag": "Model", "values": ["gpt-4", "gpt-3.5"]}
  ]
}

这会生成 4 个 TagGroup：

/api/chat + gpt-4
/api/chat + gpt-3.5
/api/complete + gpt-4
/api/complete + gpt-3.5

global 类型：每个标签值独立生成一个 TagGroup，互不影响。

{
  "type": "global",
  "tags": [
    {"tag": "URL", "values": ["/api/chat", "/api/complete"]}
  ]
}

这会生成 2 个 TagGroup：

/api/chat（名为 myGroup_1）
/api/complete（名为 myGroup_2）

share 控制是否按请求中的实际值创建子组（SubGroup），实现更细粒度的限流。

share 值	行为	适用场景
`true`	所有匹配的请求共享限流配额	共享接口总配额
`false`	按实际值创建子组，独立限流	按用户/Model 拆分配额

{
  "tags": [
    {"tag": "URL", "match": "default", "values": ["*"], "share": true},
    {"tag": "Model", "match": "equal", "values": ["gpt-4", "gpt-3.5"]}
  ]
}

URL 维度 share=false：所有请求共享 URL 匹配
Model 维度 share=false：按实际 Model 值创建子组，gpt-4 和 gpt-3.5 各自独立限流

效果为：

任意URL + gpt-3.5 为一组请求，共享一个规则(例如：每秒限流 100 个请求)
任意URL + gpt-4 为一组请求，共享一个规则(例如：每秒限流 100 个请求)

{
  "tags": [
    {"tag": "URL", "match": "default", "values": ["*"], "share": false},
    {"tag": "Model", "match": "equal", "values": ["gpt-4", "gpt-3.5"]}
  ]
}

URL 维度 share=true：所有请求共享 URL 匹配
Model 维度 share=false：按实际 Model 值创建子组，gpt-4 和 gpt-3.5 各自独立限流

效果为

/url1 + gpt-4 为一组请求，共享一个规则(例如：每秒限流 100 个请求)
/url1 + gpt-4 为一组请求，共享一个规则(例如：每秒限流 100 个请求)
/url2 + gpt-4 为一组请求，共享一个规则(例如：每秒限流 100 个请求)
/url2 + gpt-4 为一组请求，共享一个规则(例如：每秒限流 100 个请求)

常用配置模式

模式 1：单接口 QPS 限流

最简单的用法，对单个接口限制每秒请求数。

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "chatQps",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "flow": {
        "name": "chatQpsFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    }
  ]
}

适用场景：保护单个关键接口。

模式 2：多接口统一限流

对多个接口应用相同的限流策略，使用 default 匹配。

{
  "rules": [
    {
      "group": {
        "name": "apiDefault",
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]}
        ]
      },
      "flow": {
        "name": "defaultFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 500,
        "burstLimit": 500
      }
    }
  ]
}

适用场景：所有接口共享一个总限额，防止整体过载。

模式 3：按维度拆分限流

使用 normal + share=false，按维度拆分独立限流。

{
  "rules": [
    {
      "group": {
        "name": "modelSplit",
        "type": "normal",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
          {"tag": "Model", "match": "default", "values": ["*"], "share": false}
        ]
      },
      "flow": {
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    }
  ]
}

效果：所有 Model 共享 /api/chat 接口的 100 QPS 配额。

如需每个 Model 独立限流：

{
  "group": {
    "name": "modelIndependent",
    "type": "normal",
    "tags": [
      {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
      {"tag": "Model", "match": "equal", "values": ["gpt-4", "gpt-3.5"]}
    ]
  }
}

适用场景：按 Model、IP、用户等维度独立控制配额。

模式 4：黑名单过滤

使用 admission.deny 拒绝特定请求。

{
  "rules": [
    {
      "group": {
        "name": "blacklist",
        "tags": [
          {"tag": "IP", "match": "equal", "values": ["192.168.1.100", "10.0.0.5"]}
        ]
      },
      "admission": {
        "name": "blacklistDeny",
        "enabled": true,
        "type": "deny",
        "blockMsg": "该 IP 已被封禁"
      }
    },
    {
      "group": {
        "name": "normalAccess",
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]}
        ]
      },
      "flow": {
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    }
  ]
}

适用场景：封禁恶意 IP、临时关闭特定用户访问。

模式 5：多级限流

多个规则叠加，形成宽 → 严的限流层级。

{
  "rules": [
    {
      "group": {
        "name": "globalQps",
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]}
        ]
      },
      "flow": {
        "name": "globalFlow",
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 1000,
        "burstLimit": 1000
      }
    },
    {
      "group": {
        "name": "chatQps",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "flow": {
        "name": "chatFlow",
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    }
  ]
}

效果：

/api/chat：受双重限制，先受全局 1000 QPS，再受自身 100 QPS
其他接口：只受全局 1000 QPS 限制

适用场景：全局兜底 + 关键接口额外保护。

模式 6：正则匹配

使用 regex 匹配一类 URL 路径。

{
  "rules": [
    {
      "group": {
        "name": "v1Api",
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/v1/.*"], "share": true}
        ]
      },
      "flow": {
        "name": "v1Flow",
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 200,
        "burstLimit": 200
      }
    },
    {
      "group": {
        "name": "v2Api",
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/v2/.*"], "share": false}
        ]
      },
      "flow": {
        "name": "v2Flow",
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 500,
        "burstLimit": 500
      }
    }
  ]
}

效果：

/api/v1/.*：受share字段影响，v1下所有接口共享 200 QPS 限制
/api/v2/.*：受share字段影响，v2下每个接口独立享受 500 QPS 限制

适用场景：按 API 版本、路径模式分组限流。

实战场景

场景 1：LLM 推理服务

需求：

按 Model 独立限流（gpt-4 更稀缺，限额更低）
SSE 流式接口用并发限流（不是 QPS）
紧急维护时快速关闭

{
  "domain": "llm-service",
  "rules": [
    {
      "group": {
        "name": "maintenance",
        "priority": 1,
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/.*"]}
        ]
      },
      "admission": {
        "name": "maintenanceDeny",
        "enabled": true,
        "type": "deny",
        "blockMsg": "系统维护中，请稍后访问"
      }
    },
    {
      "group": {
        "name": "gpt4Stream",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/stream"]},
          {"tag": "Model", "match": "equal", "values": ["gpt-4"]}
        ]
      },
      "flow": {
        "name": "gpt4StreamFlow",
        "enabled": true,
        "flowControlMode": "concurrent",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 10,
        "burstLimit": 10
      }
    },
    {
      "group": {
        "name": "gpt35Stream",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/stream"]},
          {"tag": "Model", "match": "equal", "values": ["gpt-3.5"]}
        ]
      },
      "flow": {
        "name": "gpt35StreamFlow",
        "enabled": true,
        "flowControlMode": "concurrent",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 50,
        "burstLimit": 50
      }
    },
    {
      "group": {
        "name": "gpt4Chat",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
          {"tag": "Model", "match": "equal", "values": ["gpt-4"]}
        ]
      },
      "flow": {
        "name": "gpt4ChatFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 5,
        "burstLimit": 5
      }
    },
    {
      "group": {
        "name": "gpt35Chat",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
          {"tag": "Model", "match": "equal", "values": ["gpt-3.5"]}
        ]
      },
      "flow": {
        "name": "gpt35ChatFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 20,
        "burstLimit": 20
      }
    }
  ]
}

关键配置：

maintenance 分组 priority=1，最先匹配；启用时快速拒绝所有请求
gpt-4 限额更低（QPS 5，并发 10），反映其稀缺性
/api/stream 用并发限流，适合长连接场景

场景 2：API 网关

需求：

全局兜底：每 IP 最高 100 QPS
高优先级用户不受全局限制
特定接口更严格的限流

{
  "domain": "api-gateway",
  "rules": [
    {
      "group": {
        "name": "highPriority",
        "priority": 5,
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]},
          {"tag": "UserLevel", "match": "equal", "values": ["vip"]}
        ]
      },
      "flow": {
        "name": "vipFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 1000,
        "burstLimit": 1000
      }
    },
    {
      "group": {
        "name": "normalGlobal",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]},
          {"tag": "UserLevel", "match": "equal", "values": ["normal", "guest"]}
        ]
      },
      "flow": {
        "name": "normalGlobalFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    },
    {
      "group": {
        "name": "chatStrict",
        "priority": 5,
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "flow": {
        "name": "chatStrictFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 20,
        "burstLimit": 20
      }
    }
  ]
}

关键配置：

高优先级用户（VIP）享受 1000 QPS，不受普通用户影响
普通/访客用户每 IP 100 QPS
/api/chat 额外限制 20 QPS（更严格的保护）

注意：由于规则按顺序匹配，VIP 用户如果先命中 normalGlobal 规则则无法享受 VIP 限额。建议配合自定义标签提取器，从请求中识别用户等级。

场景 3：流式响应服务

需求：

SSE 流式接口用并发限流（长连接场景）
普通接口用 QPS 限流
紧急时快速关闭特定接口

{
  "domain": "stream-service",
  "rules": [
    {
      "group": {
        "name": "emergencyClose",
        "priority": 1,
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/stream/premium"]}
        ]
      },
      "admission": {
        "name": "emergencyDeny",
        "enabled": true,
        "type": "deny",
        "blockMsg": "该功能暂时关闭"
      }
    },
    {
      "group": {
        "name": "streamConcurrent",
        "priority": 10,
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/stream/.*"]}
        ]
      },
      "flow": {
        "name": "streamConcurrentFlow",
        "enabled": true,
        "flowControlMode": "concurrent",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    },
    {
      "group": {
        "name": "normalQps",
        "priority": 100,
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]}
        ]
      },
      "flow": {
        "name": "normalQpsFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 500,
        "burstLimit": 500
      }
    }
  ]
}

关键配置：

emergencyClose 用 admission.deny 快速关闭特定接口
流式接口用 concurrent 限流，适合长连接场景
普通接口用 qps 限流

最佳实践

规则顺序很重要：更具体的规则放在前面，更宽泛的规则放在后面
善用 priority：用 priority 区分规则重要程度，但主要依赖顺序
维护模式：在 olc.json 中保留一条 admission.deny 规则，紧急时启用
测试配置：修改配置后，用少量请求验证规则是否按预期匹配
避免冲突：同一请求不应同时命中多个分组（通常靠规则顺序解决）
适度拆分：不是越细越好，过细的拆分会增加维护成本

组策略配置指南

核心概念

Group（分组）

Tag 的三要素

Policy（策略）

执行顺序与短路

priority（优先级）

normal vs global 分组类型

share 机制

常用配置模式

模式 1：单接口 QPS 限流

模式 2：多接口统一限流

模式 3：按维度拆分限流

模式 4：黑名单过滤

模式 5：多级限流

模式 6：正则匹配

实战场景

场景 1：LLM 推理服务

场景 2：API 网关

场景 3：流式响应服务

最佳实践