页面规则 - 动作

# 限制请求速率

# 参数说明

limit_key 或 limit_keys 的 name 参数的可选值：

• 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 挑战

# 示例

示例 1：

- 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 的错误页面。

示例 2：

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

  - limit-req-rate:
      limit_keys:
      - name: client-addr
      - name: req-header
        arg: ABC
      - name: uri
      rate_shape: 10
      rate_shape_unit: r/s
      rate_reject: 20
      rate_reject_unit: r/s
      error_page_status_code: 403
      reject_action: page_template
      page_template_name: page403

此示例与示例 1 不同在于：指定了多个限速 key，并且拒绝动作是 page_template，响应状态码是 403。

# 断路器

# 参数说明

断路器策略选项：

• 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 秒，此期间若首个请求成功，则恢复打开状态；否则重回跳闸状态。

# 阻断请求

# 参数说明

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

# 示例

示例 1：

- 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 秒。

示例 2：

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

  - block-req:
      limit_keys:
      - name: 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
      clearance_time: 60
      status_code: 404
      reject_action: page_template
      page_template_name: page404

在这个示例与“示例 1”唯一的不同在于，设置了拒绝动作为 page_template，页面模板的名称为 page404，响应状态码为 404。

# OAuth JWT 验证

# 参数说明

# 示例

- 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 Authentication

# 参数说明

# 示例

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello
  actions:
    enable-basic-authentication:
      group_name: hello

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

示例 2：

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello
  actions:
  - enable-basic-authentication:
      group_name: hello
      group_type: global

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

# 启用 WebSocket

# 示例

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

  actions:
    enable-websocket: {}

# 设置 URI

# 参数说明

# 示例

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

  actions:
    set-uri:
      uri: /world

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

# 添加 URI 前缀

# 参数说明

# 示例

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

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

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

# 删除 URI 前缀

# 参数说明

# 示例

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

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

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

# 设置请求头

# 参数说明

# 示例

- 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 请求头，则会添加一个。

# 添加请求头

# 参数说明

# 示例

- 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 请求头。

# 删除请求头

# 参数说明

# 示例

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

  actions:
    rm-req-header:
      name: Foo

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

# 设置代理 URI

# 参数说明

# 示例

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

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

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

# 设置代理请求头

# 参数说明

请求头的值可通过 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 请求头设置到代理请求中。

# 设置响应头

# 参数说明

响应头的值可通过 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 响应头，则会添加之。

# 添加响应头

# 参数说明

响应头的值可通过 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 的响应头。

# 删除响应头

# 参数说明

# 示例

- 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，则会将其删除。

# 输出响应体

# 参数说明

# 示例

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

  actions:
    print:
      msg: |
        Hello World!

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

# 退出当前请求

# 参数说明

# 示例

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

  actions:
    exit:
      code: 403

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

# 设置变量

# 参数说明

# 示例

- enable_rule: true
  order: 11
  actions:
  - set-var:
      value: hello
      var_name: uuid
      var_type: app
  - set-var:
      value: world
      var_name: uuid
      var_type: global

在此示例中，设置了应用用户变量 uuid 的值为 hello以及全局用户变量 uuid的值为 world。

# 使用 Edgelang 语言

# 参数说明

# 示例

- enable_rule: true
  order: 12
  actions:
  - user-code:
      el: |-
        true =>
            say($or_user_variable_test),
            say($or_global_user_variable_uuid);

在此示例中，将应用用户变量 uuid 和全局用户变量 uuid作为请求的响应进行输出。

# 自定义错误页面

# 参数说明

# 示例

- enable_rule: true
  actions:
  - set-error-page:
      status:
      - 404
      content_type: text/html; charset=utf8
      file_path: dir1/setup.sh
  - set-error-page:
      status:
      - 403
      content_type: text/html; charset=utf8
      page_template_name: page403

在此用例中包含两个动作，一个是设置 404 状态码的错误页为一个路径为 dir1/setup.sh 静态文件。另一个是设置 403 状态码的错误也为名为 page403 的页面模板。

# 自定义动作

# 参数说明

# 示例

- enable_rule: true
  actions:
  - global_action:
      global_action_name: global-action-1
  - global_action:
      global_action_name: global-action-2

在此用例中包含两个动作，一个是名为 global-action-1 的全局自定义动作，另一个是名为 global-action-2 的全局自定义动作。

# 镜像请求

# 参数说明

# 示例

- enable_rule: true
  actions:
  - mirror-request:
      retries: 1
      upstream_type: global
      conn_timeout: 60
      type: raw
      retry_condition:
      - error
      - timeout
      - invalid_header
      - http_500
      - http_502
      - http_504
      module_name: ''
      algorithm: hash
      send_timeout: 60
      read_timeout: 60
      upstream_name: global_upstream_name1

在这个示例中，将原始请求镜像到名为 global_upstream_name1 的全局上游。