頁面規則動作

# 限制請求速率：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 狀態碼響應請求。