cluster-key-rate-limit外掛程式 - API Gateway

cluster-key-rate-limit 外掛程式基於 Redis 實現叢集限流，適用於需要跨多個 Higress Gateway 執行個體實現全域一致速率限制的情境。限流所使用的 Key 可以來源於 URL 參數、HTTP 要求頭、用戶端 IP 位址、消費者名稱或 Cookie 中的 Key。

運行屬性

外掛程式執行階段：預設階段 外掛程式執行優先順序：20

配置說明

配置項	類型	必填	預設值	說明
rule_name	string	是	-	限流規則名稱，根據限流規則名稱 + 限流類型 + 限流 key 名稱 + 限流 key 對應的實際值來拼裝 redis key
rule_items	array of object	是	-	限流規則項，按照 rule_items 下的排列順序，匹配第一個 rule_item 後命中限流規則，後續規則將被忽略
show_limit_quota_header	bool	否	false	回應標頭中是否顯示 `X-RateLimit-Limit`（限制的總請求數）和 `X-RateLimit-Remaining`（剩餘還可以發送的請求數）
rejected_code	int	否	429	請求被限流時，返回的 HTTP 狀態代碼
rejected_msg	string	否	Too many requests	請求被限流時，返回的響應體
redis	object	是	-	redis 相關配置

rule_items 中每一項的配置欄位說明。

配置項	類型	必填	預設值	說明
limit_by_header	string	否，`limit_by_*` 中選填一項	-	配置擷取限流索引值的來源 HTTP 要求頭名稱
limit_by_param	string	否，`limit_by_*` 中選填一項	-	配置擷取限流索引值的來源 URL 參數名稱
limit_by_consumer	string	否，`limit_by_*` 中選填一項	-	根據 consumer 名稱進行限流，無需添加實際值
limit_by_cookie	string	否，`limit_by_*` 中選填一項	-	配置擷取限流索引值的來源 Cookie中 key 名稱
limit_by_per_header	string	否，`limit_by_*` 中選填一項	-	按規則匹配特定 HTTP 要求頭，並對每個要求標頭分別計算限流，配置擷取限流索引值的來源 HTTP 要求頭名稱，配置 `limit_keys` 時支援Regex或 `*`
limit_by_per_param	string	否，`limit_by_*` 中選填一項	-	按規則匹配特定 URL 參數，並對每個參數分別計算限流，配置擷取限流索引值的來源 URL 參數名稱，配置 `limit_keys` 時支援Regex或 `*`
limit_by_per_consumer	string	否，`limit_by_*` 中選填一項	-	按規則匹配特定 consumer，並對每個 consumer 分別計算限流，根據 consumer 名稱進行限流，無需添加實際值，配置 `limit_keys` 時支援Regex或 `*`
limit_by_per_cookie	string	否，`limit_by_*` 中選填一項	-	按規則匹配特定 Cookie，並對每個 Cookie 分別計算限流，配置擷取限流索引值的來源 Cookie中 key 名稱，配置 `limit_keys` 時支援Regex或 `*`
limit_by_per_ip	string	否，`limit_by_*` 中選填一項	-	按規則匹配特定 IP，並對每個 IP 分別計算限流，配置擷取限流索引值的來源 IP 參數名稱，從要求標頭擷取，以 `from-header-對應的header名`，樣本：`from-header-x-forwarded-for`，直接擷取對端 socket ip，配置為 `from-remote-addr`
limit_keys	array of object	是	-	配置匹配索引值後的限流次數

limit_keys 中每一項的配置欄位說明。

配置項	類型	必填	預設值	說明
key	string	是	-	匹配的索引值，`limit_by_per_header`,`limit_by_per_param`,`limit_by_per_consumer`,`limit_by_per_cookie` 類型支援配置Regex（以regexp：開頭後面跟Regex）或者（代表所有），Regex樣本：`regexp:^d.`（以d開頭的所有字串）；`limit_by_per_ip`支援配置 IP 位址或 IP 段
query_per_second	int	否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中選填一項	-	允許每秒請求次數
query_per_minute	int	否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中選填一項	-	允許每分鐘請求次數
query_per_hour	int	否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中選填一項	-	允許每小時請求次數
query_per_day	int	否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中選填一項	-	允許每天請求次數

redis 中每一項的配置欄位說明。

配置項	類型	必填	預設值	說明
service_name	string	必填	-	redis 服務名稱，帶服務類型的完整 FQDN 名稱，例如 my-redis.dns、redis.my-ns.svc.cluster.local
service_port	int	否	服務類型為固定地址（static service）預設值為80，其他為6379	輸入Redis服務的服務連接埠
username	string	否	-	redis 使用者名稱
password	string	否	-	redis 密碼
timeout	int	否	1000	redis 連線逾時時間，單位毫秒

配置樣本

識別請求參數 apikey，進行區別限流

rule_name: default_rule
rule_items:
- limit_by_param: apikey
  limit_keys:
  - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
    query_per_minute: 10
  - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
    query_per_hour: 100
- limit_by_per_param: apikey
  limit_keys:
  # Regex，匹配以 a 開頭的所有字串，每個 apikey 對應的請求 10qds
  - key: "regexp:^a.*"
    query_per_second: 10
  # Regex，匹配以 b 開頭的所有字串，每個 apikey 對應的請求 100qd
  - key: "regexp:^b.*"
    query_per_minute: 100
  # 兜底用，匹配所有請求，每個 apikey 對應的請求 1000qdh
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

識別要求標頭 x-ca-key，進行區別限流

rule_name: default_rule
rule_items:
- limit_by_header: x-ca-key
  limit_keys:
  - key: 102234
    query_per_minute: 10
  - key: 308239
    query_per_hour: 10
- limit_by_per_header: x-ca-key
  limit_keys:
  # Regex，匹配以 a 開頭的所有字串，每個 apikey 對應的請求 10qds
  - key: "regexp:^a.*"
    query_per_second: 10
  # Regex，匹配以b開頭的所有字串，每個 apikey 對應的請求 100qd
  - key: "regexp:^b.*"
    query_per_minute: 100
  # 兜底用，匹配所有請求，每個 apikey 對應的請求 1000qdh
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

根據要求標頭 x-forwarded-for 擷取對端 IP，進行區別限流

rule_name: default_rule
rule_items:
- limit_by_per_ip: from-header-x-forwarded-for
  limit_keys:
  # 精確 IP
  - key: 1.1.1.1
    query_per_day: 10
  # IP 段，符合這個 IP 段的 IP，每個 IP 100qpd
  - key: 1.1.1.0/24
    query_per_day: 100
  # 兜底用，即預設每個 IP 1000 qpd
  - key: 0.0.0.0/0
    query_per_day: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

識別 consumer，進行區別限流

rule_name: default_rule
rule_items:
- limit_by_consumer: ''
  limit_keys:
  - key: consumer1
    query_per_second: 10
  - key: consumer2
    query_per_hour: 100
- limit_by_per_consumer: ''
  limit_keys:
  # Regex，匹配以 a 開頭的所有字串，每個 consumer 對應的請求 10qds
  - key: "regexp:^a.*"
    query_per_second: 10
  # Regex，匹配以 b 開頭的所有字串，每個 consumer 對應的請求 100qd
  - key: "regexp:^b.*"
    query_per_minute: 100
  # 兜底用，匹配所有請求，每個 consumer 對應的請求 1000qdh
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

識別 Cookie 中的索引值對，進行區別限流

rule_name: default_rule
rule_items:
  - limit_by_cookie: key1
    limit_keys:
      - key: value1
        query_per_minute: 10
      - key: value2
        query_per_hour: 100
  - limit_by_per_cookie: key1
    limit_keys:
      # Regex，匹配以 a 開頭的所有字串，每個 cookie 中的 value 對應的請求 10qds
      - key: "regexp:^a.*"
        query_per_second: 10
      # Regex，匹配以 b 開頭的所有字串，每個 cookie 中的 value 對應的請求 100qd
      - key: "regexp:^b.*"
        query_per_minute: 100
      # 兜底用，匹配所有請求，每個 cookie 中的 value 對應的請求 1000qdh
      - key: "*"
        query_per_hour: 1000
rejected_code: 200
rejected_msg: '{"code":-1,"msg":"Too many requests"}'
redis:
  service_name: redis.static
show_limit_quota_header: true

常見問題

cluster-key-rate-limit外掛程式配置後限流不生效？

檢查 redis.service_name 欄位，應填寫帶服務類型的完整 FQDN 名稱（如 redis.dns、redis.my-ns.svc.cluster.local），而非直接填寫 Redis 串連地址。需先將 Redis 通過 DNS 網域名稱方式添加到網關服務中，再填入服務名稱。