頁面規則 - 動作

# 限制請求速率

# 引數說明

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 的全域性上游。