OLC 配置参考

本文档是 OLC 所有配置项的完整参考。

Properties 配置项

配置文件：overload-config.properties，路径通过环境变量 OLC_CONFIG_PATH 指定。

SDK 配置

键名	类型	默认值	说明
olc.sdk.domain	str	""	域名，需与 JSON 规则中的 domain 一致
olc.sdk.switch	bool	True	全局开关，设为 off 或 false 关闭 OLC
olc.sdk.dynamic.switch	bool	False	动态开关
olc.sdk.config.stub	str	"jsonfile"	配置源类型，对应 OlcConfigPluginManager 中注册的插件名
olc.sdk.policy.update.period	int	6	规则刷新间隔（秒）

采集器配置

键名	类型	默认值	说明
olc.sdk.collector.active	str	""	激活的采集器名称，多个用分号分隔，如 "vllm"
olc.sdk.collector.capacity	int	10	采集器存储容量（最大保留的采集记录数）
olc.sdk.collector.sample	int	10	采集器采样数（计算平均值时使用的样本数）
olc.sdk.collector.interval	int	1	采集间隔（秒）

Redis 配置

键名	类型	默认值	说明
olc.redis.mode	str	"alone"	Redis 模式：alone（单机）/ cluster（集群）/ sentinel（哨兵）
olc.redis.nodeList	str	""	节点列表，集群模式用逗号分隔
olc.redis.passwd	str	None	密码，支持 ENC(...) 加密格式
olc.redis.timeout	int	2000	连接超时（毫秒）
olc.redis.maxConnections	int	64	最大连接数
olc.redis.serviceName	str	""	Sentinel 模式的服务名
olc.redis.retry.times	int	3	重试次数
olc.redis.retry.interval	int	1000	重试间隔（毫秒）
olc.redis.socketTimeout	int	2000	Socket 超时（毫秒）

Prometheus 配置

键名	类型	默认值	说明
olc.extension.prometheus.url	str	"http://localhost:9090"	Prometheus 服务地址

配置文件示例

# SDK 基础配置
olc.sdk.domain=my-service
olc.sdk.switch=on
olc.sdk.config.stub=jsonfile
olc.sdk.policy.update.period=6

# 采集器配置
olc.sdk.collector.active=vllm
olc.sdk.collector.capacity=10
olc.sdk.collector.sample=10
olc.sdk.collector.interval=1

# Redis 配置（集群模式）
olc.redis.mode=cluster
olc.redis.nodeList=redis1:6379,redis2:6379,redis3:6379
olc.redis.passwd=ENC(encrypted_password)
olc.redis.timeout=2000
olc.redis.maxConnections=64

---

JSON 规则配置

配置文件：olc.json，路径为 {OLC_CONFIG_PATH}/olc.json。

顶层结构

{
  "domain": "my-service",
  "rules": [...]
}

字段	类型	必填	说明
domain	str	是	域名，需与 Properties 中的 olc.sdk.domain 一致
rules	array	是	规则列表

Group 配置

{
  "group": {
    "priority": 4,
    "enabled": true,
    "name": "apiGroup",
    "type": "normal",
    "tags": [...]
  }
}

字段	类型	默认值	说明
name	str	-	分组名称（全局唯一）
priority	int	500	优先级
enabled	bool	true	是否启用
type	str	"normal"	分组类型：normal（笛卡尔积）/ global（独立生成）
tags	array	-	标签列表（最多 5 个）

Tag 配置

{
  "tag": "URL",
  "match": "equal",
  "values": ["/api/chat"],
  "share": true
}

字段	类型	默认值	说明
tag	str	-	维度名，需在 Dimension 中注册
match	str	"equal"	匹配方式：equal（精确）/ regex（正则）/ default（通配 *）
values	array	-	匹配值列表 当 match 为default时只能为*
share	bool	根据 match 自动推断	是否共享（equal 默认 True，其他默认 False）

share 说明：

• share=True：该维度的标签不创建子组，所有匹配的请求共享限流配额
• share=False：根据请求中的实际值创建子组，实现细粒度限流

例如：

{
  "tag": "URL",
  "match": "default",
  "values": ["*"],
  "share": true
}

当 share=True 时，所有请求的 URL 都会被归入同一个分组，无论 URL 本身是否变化。 当 share=False 时，根据请求中的实际值创建子组，实现细粒度限流。

Flow 配置

{
  "flow": {
    "name": "flow1",
    "enabled": true,
    "flowControlMode": "qps",
    "policyType": "NODE",
    "timeUnit": "second",
    "timeInterval": 1,
    "rateLimit": 100,
    "burstLimit": 120,
    "maxWaitTimeMs": 0,
    "blockMsg": "请求过于频繁",
    "calculateAlg": null,
    "assignAlg": null
  }
}

字段	类型	默认值	说明
name	str	{groupName}_flow	策略名称（全局唯一）
enabled	bool	true	是否启用
flowControlMode	str	"qps"	流控模式：qps / quota / response_quota / concurrent
policyType	str	""	策略类型：NODE（单机）/ CLUSTER（集群）
timeUnit	str	-	时间单位：second / minute / hour / day
timeInterval	int	1	时间间隔
rateLimit	int	0	限流阈值
burstLimit	int	0	突发上限
maxWaitTimeMs	int	0	最大等待时间（毫秒）
blockMsg	str	""	拦截消息
calculateAlg	object	null	计算算法配置
assignAlg	object	null	分配算法配置（集群模式）

calculateAlg 结构：

{
  "algName": "PID",
  "algParam": {
    "Kp": 0.5,
    "Ki": 0,
    "kd": 0.5,
    "minResource": 0.5,
    "maxResource": 0.8,
    "currentUsage": "localresource.memory"
  }
}

字段	类型	说明
algName	str	算法名称，需在 OlcAlgManager 中注册
algParam	object	算法参数，key 为参数名，value 为参数值

Admission 配置

{
  "admission": {
    "name": "admission1",
    "enabled": true,
    "type": "allow",
    "blockMsg": "",
    "calculateAlg": null
  }
}

字段	类型	默认值	说明
name	str	{groupName}_admission	策略名称（全局唯一）
enabled	bool	true	是否启用
type	str	""	准入类型：allow / deny / dynamic
blockMsg	str	""	拦截消息
calculateAlg	object	null	动态准入算法配置

完整配置示例

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "priority": 4,
        "enabled": true,
        "name": "chatApiGroup",
        "type": "normal",
        "tags": [
          {
            "tag": "URL",
            "match": "equal",
            "values": ["/api/chat"]
          },
          {
            "tag": "Method",
            "match": "equal",
            "values": ["POST"]
          }
        ]
      },
      "flow": {
        "name": "chatFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "policyType": "NODE",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 120
      }
    },
    {
      "group": {
        "priority": 3,
        "enabled": true,
        "name": "modelApiGroup",
        "type": "normal",
        "tags": [
          {
            "tag": "URL",
            "match": "equal",
            "values": ["/api/chat"],
            "share": true
          },
          {
            "tag": "Model",
            "match": "equal",
            "values": ["gpt-4", "gpt-3.5"],
            "share": false
          }
        ]
      },
      "flow": {
        "name": "modelFlow",
        "enabled": true,
        "flowControlMode": "concurrent",
        "policyType": "NODE",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 50,
        "burstLimit": 50,
        "calculateAlg": {
          "algName": "PID",
          "algParams": {
            "Kp": 0.5,
            "Ki": 0,
            "kd": 0.5,
            "minResource": 0.5,
            "maxResource": 0.8,
            "currentUsage": "vllm.gpu_usage"
          }
        }
      },
      "admission": {
        "name": "modelAdmission",
        "enabled": true,
        "type": "allow"
      }
    }
  ]
}

---

环境变量

变量名	说明	示例
OLC_CONFIG_PATH	配置文件目录路径	/app/config

设置方式：

# 命令行
export OLC_CONFIG_PATH=/app/config

# Python 代码
import os
os.environ["OLC_CONFIG_PATH"] = "/app/config"

---

适配器配置

OlcAdapterConfig (FastAPI)

from olc.adapters.fastapi import OlcAdapterConfig

config = OlcAdapterConfig(
    tag_extractor=extract_tags,       # 标签提取函数
    block_msg="请求过于频繁",          # 默认拦截消息
    block_response_builder=custom_response,  # 自定义拦截响应
    token_number=1,                    # 令牌消耗数
)

字段	类型	默认值	说明
tag_extractor	Callable[[Request], Dict[str, str]] 或 Callable[[Request], Awaitable[Dict[str, str]]]	None	自定义标签提取函数，为 None 时使用默认提取（URL + Method）
block_msg	str	"Request blocked by rate limiter"	默认拦截消息
block_response_builder	Callable[[Request, str], Response] 或 Callable[[Request, str], Awaitable[Response]]	None	自定义拦截响应构建函数，为 None 时返回 429 JSON
token_number	int	1	每次请求消耗的令牌数

默认标签提取

未提供 tag_extractor 时，适配器自动提取：

tags = {
    "URL": request.url.path,
    "Method": request.method,
}

自定义标签提取示例

from olc.bean.dimension import URL, Method, Model

def extract_tags_from_headers(request: Request) -> dict:
    return {
        f"{URL}": request.url.path,
        f"{Method}": request.method,
        f"{Model}": request.headers.get("X-Model", "default"),
    }

自定义拦截响应示例

from fastapi import Request
from fastapi.responses import JSONResponse

def custom_block_response(request: Request, block_msg: str) -> JSONResponse:
    return JSONResponse(
        status_code=429,
        content={
            "error": "Rate limit exceeded",
            "message": block_msg,
            "path": str(request.url.path),
            "retry_after": 1,
        },
        headers={"Retry-After": "1"},
    )