页面规则动作

# 限制请求速率：Limit Request Rate

# 参数说明

limit_key 可选值：

• client-addr：客户端地址
• uri：请求的 URI
• uri-arg：请求参数
• req-cookie：请求中的 Cookie
• req-header：请求头
• first-x-forwarded-addr：请求头中 X-Forwarded-For 的第一个地址
• last-x-forwarded-addr：请求头中 X-Forwarded-For 的最后一个地址

uri-arg、req-cookie 和 req-header 需要配合 key_arg 使用，以指定具体的参数、Cookie 或请求头名称。

reject_action 可选值：

• enable_hcaptcha：启用 hCaptcha 验证码验证
• enable_edge_captcha：启用 Edge Captcha 验证码验证
• error_page：返回指定 error_page_status_code 对应的错误页面
• close_connection：直接关闭 TCP 连接
• redirect_validate：执行重定向验证
• js_challenge：执行 JS 挑战

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    limit-req-rate:
      limit_key: uri
      rate_shape: 10
      rate_shape_unit: r/s
      rate_reject: 20
      rate_reject_unit: r/s
      reject_action: error_page
      error_page_status_code: 429

示例展示了基于 URI 进行请求限速。当请求速率达到 10 r/s 时，开始流量控制，即请求可能会被延迟处理；当请求速率达到 20 r/s 时，对超速的请求执行拒绝策略，返回状态码 429 的错误页面。

# 断路器：Circuit Breaker

# 参数说明

断路器策略选项：

• slow-ratio：慢请求比率，当慢请求与正常请求的比率达到阈值时，断路器跳闸。
• failure-ratio：失败请求比率，当失败请求与正常请求的比率达到阈值时，断路器跳闸。
• failure-count：失败请求数，当失败请求量达到阈值时，断路器跳闸。

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-circuit-breaker:
      strategy: failure-count
      window_time: 10
      open_time: 15
      hopen_time: 30
      open_action: exit
      failure_time: 3000
      failure_status:
      - 500
      - 502
      - 503
      failure_count: 3
      min_reqs_in_window: 5
      resp_status: 500

此示例中采用了“失败请求数量”策略的断路器。当 URI 为 /hello 时，启用断路器。10 秒的时间窗口内若超过 5 次请求并且 500、502 或 503 的失败请求达到 3 次，断路器将跳闸 15 秒。在跳闸期间，所有请求将执行 exit 动作并返回状态码 500。跳闸状态持续 15 秒后，转入半开状态 30 秒，此期间若首个请求成功，则恢复打开状态；否则重回跳闸状态。

# 阻断请求：Block Request

# 参数说明

在 observe_interval 观察周期内，如果被限速的请求量达到 block_threshold 阻断阈值，则对由 limit_key 标识的请求实施持续 block_time 秒的阻断，直接响应 503。 后续会支持更多阻断动作。

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    block-req:
      limit_key: uri
      rate_shape: 10
      rate_shape_unit: r/s
      rate_reject: 20
      rate_reject_unit: r/s
      block_threshold: 10
      observe_interval: 60
      block_time: 3600

在该示例中，根据 URI 对请求进行分类。当请求速率达到 10 r/s 时，开始流量控制；当请求速率达到 20 r/s 时，拒绝超速的请求。如果在 60 秒的观察周期内拒绝的请求超过了 10 个阻断阈值，那么后续的此类请求将直接返回状态码 503，并持续阻断 3600 秒。

# OAuth JWT 验证：OAuth2 JWT Validate

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    oauth2-jwt-validate:
      discovery: https://accounts.openresty.com/.well-known/introspect-configuration
      token_signing_alg:
      - HS256
      - HS512
      - RS256
      - ES256
      - ES512
      - RS512
      - none
      accept_unsupported_alg: false

在此示例中，当请求 URI 为 /hello 时，启用 OAuth2 JWT 验证。秘钥通过 URL 发现，配置中选中了所有支持的 token 签名算法，并拒绝不支持的算法。

# 启用 Basic 认证：Enable Basic Authentication

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-basic-authentication:
      group_name: hello

在此示例中，当请求 URI 为 /hello 时，启用 Basic 认证，只有属于 hello 用户组的成员才能访问对应的资源。

# 启用 WebSocket：Enable WebSocket

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-websocket: {}

# 设置 URI：Set URI

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    set-uri:
      uri: /world

示例中，当请求 URI 为 /hello 时，URI 将被修改为 /world。

# 添加 URI 前缀：Add URI Prefix

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /world

  actions:
    add-uri-prefix:
      value: /hello

示例中，当请求 URI 为 /world 时，URI 将被修改为 /hello/world。

# 删除 URI 前缀：Remove URI Prefix

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-uri-prefix:
      value: /hello

示例中，当请求 URI 为 /hello/world 时，将会删除 URI 中的 /hello 前缀，URI 最终变为 /world。

# 设置请求头：Set Request Header

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-req-header:
      header: Host
      value: openresty.com

示例中，当请求 URI 为 /hello/world 时，将会修改 Host 请求头为 openresty.com，若不存在 Host 请求头，则会添加一个。

# 添加请求头：Add Request Header

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    add-req-header:
      header: Foo
      value: Bar

示例中，当请求 URI 为 /hello/world 时，无论 Foo 请求头是否已存在，都会添加 Foo: Bar 请求头。

# 删除请求头：Remove Request Header

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-req-header:
      name: Foo

在此示例中，当请求的 URI 为 /hello/world 时，系统将会移除请求头中的 Foo。若此时请求被代理至上游服务器，上游服务器将不会收到此请求头。

# 设置代理 URI：Set Proxy URI

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    set-proxy-uri:
      uri: /hello/world

此示例展示，当请求的 URI 为 /hello 时，将会在代理请求中将 URI 更改为 /hello/world，而原始请求中的 URI 保持不变。

# 设置代理请求头：Set Proxy Header

# 参数说明

请求头的值可通过 value 直接设置为固定值，或者通过 el_var 和 el_var_arg 设置为动态值。下文将会提供两种情况的示例。

el_var 支持的变量包括：

• client-addr：客户端地址
• client-port：客户端端口
• host：请求的主机名
• scheme：HTTP 请求的协议，可为 http 或 https
• first-x-forwarded-addr：X-Forwarded-For 请求头的第一个地址
• last-x-forwarded-addr：X-Forwarded-For 请求头的最后一个地址
• system-hostname：OpenResty Edge 节点的系统主机名
• req-header：指定请求头，请求头名称通过 el_var_arg 指定
• ssl-client-s-dn：SSL 客户端证书的持有者信息
• ssl-client-i-dn：SSL 客户端证书的签发机构（CA）信息
• ssl-client-serial：SSL 客户端证书的序列号
• ssl-client-verify-result：SSL 客户端证书的验证结果

# 示例

示例 1：

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: Host
      value: openresty.com

此示例中，当请求的 URI 为 /hello/world 时，将会设置代理请求的 Host 请求头为 openresty.com。若无 Host 请求头，则会添加。

示例 2：

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: X-Forwarded-For
      el_var: client-addr

在此示例中，当请求的 URI 为 /hello/world 时，将会将代理请求的 X-Forwarded-For 请求头设置为实际的客户端地址。

示例 3：

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: Host
      el_var: req-header
      el_var_arg: Host

在此示例中，当请求的 URI 为 /hello/world 时，将会把原始请求头中的 Host 请求头设置到代理请求中。

# 设置响应头：Set Response Header

# 参数说明

响应头的值可通过 value 直接设置为固定值，或者通过 el_var 和 el_var_arg 设置为动态值。如下所示，提供两种情况的示例。

el_var 支持的变量包括：

• system-hostname：OpenResty Edge 节点的系统主机名
• req-header：指定请求头，请求头名称通过 el_var_arg 指定

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-resp-header:
      name: Foo
      value: Bar

在此示例中，当请求的 URI 为 /hello/world 时，将会设置响应头 Foo: Bar。若无 Foo 响应头，则会添加之。

# 添加响应头：Add Response Header

# 参数说明

响应头的值可通过 value 直接设置为固定值，或者通过 el_var 和 el_var_arg 设置为动态值。如下所示，提供两种情况的示例。

el_var 支持的变量包括：

• system-hostname：OpenResty Edge 节点的系统主机名
• req-header：指定请求头，请求头名称通过 el_var_arg 指定

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    add-resp-header:
      name: Foo
      value: Bar

在此示例中，无论响应中是否已存在 Foo 响应头，当请求的 URI 为 /hello/world 时，都会添加一个 Foo: Bar 的响应头。

# 删除响应头：Remove Response Header

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-resp-header:
      name: Access-Control-Allow-Origin

在此示例中，当请求的 URI 为 /hello/world 时，如果响应头中包含 Access-Control-Allow-Origin，则会将其删除。

# 输出响应体：Output Response Body

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    print:
      msg: |
        Hello World!

在此示例中，当请求的 URI 为 /hello/world 时，将会输出 Hello World! 作为响应体。

# 退出当前请求：Exit Current Request

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /bad/request

  actions:
    exit:
      code: 403

在此示例中，当请求的 URI 为 /bad/request 时，将会以 403 状态码响应请求。