跳到主要内容

上下文与策略匹配器

这些 matcher 使用 mark、环境、时间、概率、速率限制或字符串表达式决定策略分支。

mark​

作用​

匹配上下文中的 mark 集合。

配置示例​

- tag: marked_100
  type: mark
  args:
    - "100"
    - "200"

说明：

  • 参数会被解析为整数 mark。
  • 支持使用逗号或空白分隔多个 mark。
  • 只要上下文 marks 与配置 marks 有交集就算命中。

配置项​

mark 的 args 为 mark 列表。

  • 类型：array；必填：是；默认值：无
  • 作用：定义可命中的上下文标记集合。
  • 支持取值：
    • 无符号整数形式的 mark 值
  • 运行影响：
    • 只要上下文 marks 与配置 marks 存在交集，即返回 true。

quick setup​

- matches: "mark 100 200"

典型用途​

  • 在多个 sequence 间传递分支状态。

env​

作用​

匹配进程环境变量。

配置示例​

- tag: env_profile_prod
  type: env
  args:
    - "PROFILE=prod"
    - "FEATURE_X"

或只校验存在：

args:
  - "FEATURE_X"

配置项​

env 的 args 为环境变量条件列表。

  • 类型：array；必填：是；默认值：无
  • 元素定义：
    • KEY=VALUE：环境变量必须存在且值完全匹配，推荐用于环境变量等值匹配。
    • KEY:VALUE：与 KEY=VALUE 等价，作为规则表达式风格的别名保留。
    • KEY：环境变量存在即命中。
    • KEY: 或 KEY=：显式存在性检查。
  • 数组中的每个字符串都会作为一个完整表达式解析，不会再按逗号或空白拆分；因此 NO_PROXY=localhost,127.0.0.1、GREETING=hello world 这类值应写成单独的带引号数组项。
  • 运行影响：
    • 所有环境变量条件都满足时才返回 true。
    • 环境变量值在插件 init 阶段缓存，运行中不会动态重新读取。

quick setup​

- matches: "env PROFILE=prod FEATURE_X"

行为说明​

  • KEY=VALUE 和 KEY:VALUE 要求值完全匹配。
  • KEY、KEY: 和 KEY= 只检查变量是否存在。
  • ["PROFILE", "prod"] 表示同时检查 PROFILE 和 prod 两个环境变量存在，不表示 PROFILE == prod。
  • quick setup 使用空白分隔多个表达式；如果值本身包含空格，请使用完整 args 数组配置。

典型用途​

  • 同一配置在不同部署环境下启用不同分支。

time​

作用​

按当前墙上时间匹配日内时间段、星期和每月日期。

配置示例​

- tag: work_hours
  type: time
  args:
    timezone: Asia/Shanghai
    periods:
      - start: "09:00"
        end: "18:00"
        weekdays: [mon, tue, wed, thu, fri]
      - start: "22:00"
        end: "02:00"
        weekdays: [sat, sun]
      - monthdays: [1, 15]

配置项​

timezone​

  • 类型：string；必填：否；默认值：系统时区
  • 使用 IANA 时区名称，例如 Asia/Shanghai、UTC。
  • 未配置时会解析系统时区；无法解析时插件初始化失败，不会静默退回 UTC。

periods​

  • 类型：array；必填：是；数量：1..=64
  • 每项可配置 start、end、weekdays 与 monthdays。
  • 多项之间为 OR；同一项内所有已配置条件为 AND。
  • start 与 end 均为 HH:MM，必须同时填写或同时省略；同时省略表示全天，但此时必须配置星期或月日条件。
  • 区间使用 [start, end)；相同起止时间无效。end 早于 start 时表示跨午夜，星期和月日条件归属于开始日。
  • weekdays 支持大小写不敏感的 mon 至 sun，也支持 ISO 周序数字 1..=7（1=周一，7=周日）；monthdays 支持 1..=31。不存在该日期的月份不会命中。

quick setup​

- matches: "time 09:00-18:00"

quick setup 仅支持系统时区下的单个每日窗口；星期、月日和显式时区请使用完整配置。

行为说明​

  • matcher 在执行时读取真实墙上时间；系统校时会立即影响后续判断。
  • 夏令时跳过的本地时间不会出现；重复小时中的两个实际时刻都会按相同钟面规则判断。
  • 独立 Linux 或精简容器中配置 IANA 时区时，应确保系统提供 tzdata。

典型用途​

  • 工作日办公时段走特定上游。
  • 夜间或周末切换缓存、分流或家长控制策略。

random​

作用​

按概率命中。

配置示例​

- tag: rollout_10p
  type: random
  args:
    - "0.1"

配置项​

random 的 args 只接受一个概率值。

  • 类型：array；必填：是；默认值：无
  • 取值范围：0.0 到 1.0
  • 作用：定义本次匹配返回 true 的概率。
  • 运行影响：
    • 0.0 表示始终不命中。
    • 1.0 表示始终命中。

quick setup​

- matches: "random 0.05"

典型用途​

  • 灰度放量。
  • 抽样日志或观测。

rate_limiter​

作用​

基于客户端 IP 的令牌桶限流。

配置示例​

- tag: qps_guard
  type: rate_limiter
  args:
    qps: 20
    burst: 40
    mask4: 32
    mask6: 48

配置项​

qps​

  • 类型：number；必填：否；默认值：20
  • 作用：定义每秒令牌补充速率。
  • 运行影响：
    • 值越大，单位时间内允许通过的请求越多。

burst​

  • 类型：integer；必填：否；默认值：40
  • 作用：定义令牌桶容量上限。
  • 运行影响：
    • 值越大，短时间内允许的突发请求越多。

mask4​

  • 类型：integer；必填：否；默认值：32
  • 作用：定义 IPv4 客户端聚合粒度。
  • 运行影响：
    • 值越小，多个 IPv4 客户端越容易共享同一个限流桶。

mask6​

  • 类型：integer；必填：否；默认值：48
  • 作用：定义 IPv6 客户端聚合粒度。
  • 运行影响：
    • 值越小，多个 IPv6 客户端越容易共享同一个限流桶。

quick setup​

推荐使用完整配置，以便显式控制 qps、burst 和 mask。

行为说明​

  • 命中含义是“允许通过并消费一个令牌”。
  • 返回 false 表示当前限流，不允许通过。

Metrics​

通过全局 GET /api/metrics 导出：

  • ratelimit_allowed_total
  • ratelimit_rejected_total

典型用途​

  • 源地址维度的入口保护。