准入控制指南

准入控制（Admission Control）是对请求的全量放行或拒绝，与限流不同：限流是按配额控制速率，准入控制是二元判定（允许/拒绝）。

架构说明

准入模块由三部分组成：

组件	文件	说明
准入控制器	`olc/admission/admission_controller.py`	负责实际判定逻辑
准入工厂	`olc/admission/admission_factory.py`	创建和管理控制器实例
准入算法	`olc/alg/admission/`	动态模式下的判定算法

控制器类型

控制器	类型值	行为
AllowController	`allow`	始终放行
DenyController	`deny`	始终拒绝
DynamicController	`dynamic`	根据算法动态决定

准入算法

动态模式下可使用的准入算法：

算法名称	说明	参数
CONCURRENTTHREAD	基于并发线程数判断	`threadThreshold`: 线程数阈值

准入控制模式

模式	type 值	行为	适用场景
允许	`allow`	始终放行	默认放行，配合限流使用
拒绝	`deny`	始终拒绝	黑名单、维护模式
动态	`dynamic`	根据算法动态决定	基于资源状态动态开关

Allow 模式

允许模式始终放行请求，通常与限流策略组合使用。

配置示例

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "allowGroup",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "admission": {
        "name": "allowAdmission",
        "enabled": true,
        "type": "allow"
      }
    }
  ]
}

适用场景

配合限流策略使用，明确标记某些接口允许访问
作为默认策略，后续可通过配置切换为 deny

Deny 模式

拒绝模式始终拒绝匹配的请求，适用于黑名单和维护模式。

配置示例

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "denyGroup",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/admin"]}
        ]
      },
      "admission": {
        "name": "denyAdmission",
        "enabled": true,
        "type": "deny",
        "blockMsg": "该接口暂不可用"
      }
    }
  ]
}

适用场景

黑名单：拒绝特定 IP、用户或接口的访问
维护模式：临时关闭某个接口
灰度控制：拒绝特定版本的请求

Dynamic 模式

动态模式根据算法结果动态决定是否放行，适用于基于资源状态的动态开关。

配置示例

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "dynamicGroup",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "admission": {
        "name": "dynamicAdmission",
        "enabled": true,
        "type": "dynamic",
        "calculateAlg": {
          "algName": "CONCURRENTTHREAD",
          "algParam": {
            "threadThreshold": 100
          }
        }
      }
    }
  ]
}

动态参数

calculateAlg.algParam 中的参数值可以配置为动态获取，格式为 #{}：

{
  "algParam": {
    "threadThreshold": "#{dynamic.thread.count}"
  }
}

动态参数的值来源于资源采集器获取的真实运行时指标。

适用场景

系统过载时自动拒绝请求
基于资源使用率动态开关

与限流策略组合使用

同一规则中可以同时配置 admission 和 flow，准入判定在限流判定之前执行。

示例：黑名单 + QPS 限流

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "blacklistGroup",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]},
          {"tag": "IP", "match": "equal", "values": ["192.168.1.100"]}
        ]
      },
      "admission": {
        "name": "blacklistAdmission",
        "enabled": true,
        "type": "deny",
        "blockMsg": "您的 IP 已被封禁"
      }
    },
    {
      "group": {
        "name": "apiGroup",
        "tags": [
          {"tag": "URL", "match": "equal", "values": ["/api/chat"]}
        ]
      },
      "flow": {
        "name": "apiFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 100,
        "burstLimit": 100
      }
    }
  ]
}

执行顺序：

请求进入 → 先匹配 blacklistGroup，若 IP 在黑名单中则直接拒绝
若未命中黑名单 → 匹配 apiGroup，执行 QPS 限流判定

示例：维护模式 + 其他接口限流

{
  "domain": "my-service",
  "rules": [
    {
      "group": {
        "name": "maintenanceGroup",
        "tags": [
          {"tag": "URL", "match": "regex", "values": ["/api/admin/.*"]}
        ]
      },
      "admission": {
        "name": "maintenanceAdmission",
        "enabled": true,
        "type": "deny",
        "blockMsg": "系统维护中，请稍后访问"
      }
    },
    {
      "group": {
        "name": "normalGroup",
        "tags": [
          {"tag": "URL", "match": "default", "values": ["*"]}
        ]
      },
      "flow": {
        "name": "normalFlow",
        "enabled": true,
        "flowControlMode": "qps",
        "timeUnit": "second",
        "timeInterval": 1,
        "rateLimit": 200,
        "burstLimit": 200
      }
    }
  ]
}

更多限流配置详情请参阅限流策略使用指南。