Centre de documentation

Tous les produits

Centre de documentation

API Gateway:Limitation de débit par clé de cluster

Dernière mise à jour :Sep 19, 2026

Le plug-in cluster-key-rate-limit active la limitation de débit basée sur Redis au niveau du cluster, assurant une cohérence du throttling entre plusieurs instances de Higress Gateway. Les clés peuvent être extraites des paramètres d'URL, des en-têtes de requête HTTP, des adresses IP client, des noms de consommateur ou des clés de cookie.

Attributs d'exécution

Étape d'exécution du plug-in : default stage. Priorité d'exécution du plug-in : 20.

Paramètres

Champ

Type

Obligatoire

Valeur par défaut

Commentaire

rule_name

string

Oui

-

Nom de la règle de limitation. Le nom de la règle, le type de limitation, le nom de la clé et la valeur réelle de la clé sont concaténés pour former la clé Redis.

rule_items

array of object

Oui

-

Éléments de la règle de limitation, évalués dans l'ordre. Dès qu'une correspondance est trouvée, les éléments suivants sont ignorés.

show_limit_quota_header

bool

Non

false

Indique s'il faut inclure les en-têtes X-RateLimit-Limit (nombre total de requêtes limitées) et X-RateLimit-Remaining (nombre de requêtes autorisées restantes) dans la réponse.

rejected_code

int

Non

429

Code d'état HTTP renvoyé lorsque les requêtes sont limitées.

rejected_msg

string

Non

Too many requests

Corps de la réponse renvoyé lorsque les requêtes sont limitées.

redis

object

Oui

-

Paramètres de connexion Redis.

Le tableau suivant décrit les champs contenus dans rule_items.

Champ

Type

Obligatoire

Valeur par défaut

Description

limit_by_header

string

Non. Configurez un seul des champs limit_by_*.

-

Nom de l'en-tête de requête HTTP utilisé comme clé de limitation.

limit_by_param

string

Non. Configurez un seul des champs limit_by_*.

-

Nom du paramètre d'URL utilisé comme clé de limitation.

limit_by_consumer

string

Non. Configurez un seul des champs limit_by_*.

-

Nom du consommateur utilisé comme clé de limitation. Aucune valeur réelle n'est requise.

limit_by_cookie

string

Non. Configurez un seul des champs limit_by_*.

-

Nom de la clé de cookie utilisé comme clé de limitation.

limit_by_per_header

string

Non. Configurez un seul des champs limit_by_*.

-

Nom de l'en-tête de requête HTTP pour une limitation par valeur. Chaque valeur d'en-tête distincte fait l'objet d'une limitation de débit indépendante. Les expressions régulières et les astérisques (*) sont pris en charge dans limit_keys.

limit_by_per_param

string

Non. Configurez un seul des champs limit_by_*.

-

Nom du paramètre d'URL pour une limitation par valeur. Chaque valeur de paramètre distincte fait l'objet d'une limitation de débit indépendante. Les expressions régulières et les astérisques (*) sont pris en charge dans limit_keys.

limit_by_per_consumer

string

Non. Configurez un seul des champs limit_by_*.

-

Nom du consommateur pour une limitation par consommateur. Chaque consommateur fait l'objet d'une limitation de débit indépendante. Aucune valeur réelle n'est requise. Les expressions régulières et les astérisques (*) sont pris en charge dans limit_keys.

limit_by_per_cookie

string

Non. Configurez un seul des champs limit_by_*.

-

Nom de la clé de cookie pour une limitation par valeur. Chaque valeur de cookie distincte fait l'objet d'une limitation de débit indépendante. Les expressions régulières et les astérisques (*) sont pris en charge dans limit_keys.

limit_by_per_ip

string

Non. Configurez un seul des champs limit_by_*.

-

Source de l'adresse IP pour une limitation par adresse IP. Définissez cette option sur from-header-<Header name> (par exemple, from-header-x-forwarded-for) pour extraire les adresses IP d'un en-tête de requête, ou sur from-remote-addr pour utiliser l'adresse IP du socket pair. Chaque adresse IP fait l'objet d'une limitation de débit indépendante.

limit_keys

array of object

Oui.

-

Seuils de limitation de débit appliqués lorsqu'une valeur de clé correspond.

Le tableau suivant décrit les champs contenus dans limit_keys.

Champ

Type

Obligatoire

Valeur par défaut

Description

key

string

Oui.

-

Valeur de la clé à faire correspondre. Pour limit_by_per_header, limit_by_per_param, limit_by_per_consumer et limit_by_per_cookie, les expressions régulières (préfixées par regexp:) et les astérisques (*) sont pris en charge. Un astérisque correspond à toutes les valeurs. Exemple : regexp: ^d.* correspond à toutes les chaînes commençant par d. Pour limit_by_per_ip, les adresses IP et les blocs CIDR sont pris en charge.

query_per_second

int

Non. Configurez l'un des champs suivants : query_per_second, query_per_minute, query_per_hour ou query_per_day.

-

Nombre de requêtes autorisées par seconde.

query_per_minute

int

Non. Configurez l'un des champs suivants : query_per_second, query_per_minute, query_per_hour ou query_per_day.

-

Nombre de requêtes autorisées par minute.

query_per_hour

int

Non. Configurez l'un des champs suivants : query_per_second, query_per_minute, query_per_hour ou query_per_day.

-

Nombre de requêtes autorisées par heure.

query_per_day

int

Non. Configurez l'un des champs suivants : query_per_second, query_per_minute, query_per_hour ou query_per_day.

-

Nombre de requêtes autorisées par jour.

Le tableau suivant décrit les champs contenus dans redis.

Champ

Type

Obligatoire

Valeur par défaut

Description

service_name

string

Oui

-

Nom du service Redis sous forme de nom de domaine complet (FQDN), tel que my-redis.dns ou redis.my-ns.svc.cluster.local.

service_port

int

Non

Si le type de service est un service statique, la valeur par défaut est 80. Pour les autres services, la valeur par défaut est 6379.

Numéro de port de l'instance Tair (compatible avec OSS Redis).

username

string

Non

-

Nom d'utilisateur Redis.

password

string

Non

-

Mot de passe Redis.

timeout

int

Non

1000

Délai de connexion pour l'instance Tair (compatible avec OSS Redis), en millisecondes.

Exemples de configuration

Identifier les requêtes en fonction du paramètre apikey et appliquer différentes opérations de limitation

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:
  # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each request, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identifier les requêtes en fonction de l'en-tête de requête x-ca-key et appliquer différentes opérations de limitation

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:
  # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each request, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Obtenir les adresses IP des pairs en fonction de l'en-tête de requête x-forwarded-for et appliquer différentes opérations de limitation

rule_name: default_rule
rule_items:
- limit_by_per_ip: from-header-x-forwarded-for
  limit_keys:
  # The exact IP address.
  - key: 1.1.1.1
    query_per_day: 10
  # The CIDR block. For each IP address in the CIDR block, 100 QPD is allowed.
  - key: 1.1.1.0/24
    query_per_day: 100
  # By default, 1,000 QPD is allowed for each IP address.
  - key: 0.0.0.0/0
    query_per_day: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identifier les requêtes en fonction des consommateurs et appliquer différentes opérations de limitation

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:
  # A regular expression is used to match all strings that start with a. For each consumer that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each consumer that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each consumer, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identifier les requêtes en fonction des paires clé-valeur dans les cookies et appliquer différentes opérations de limitation

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:
      # A regular expression is used to match all strings that start with a. For each request that matches a specific cookie value, 10 QDS is allowed.
      - key: "regexp:^a.*"
        query_per_second: 10
      # A regular expression is used to match all strings that start with b. For each request that matches a specific cookie value, 100 QD is allowed.
      - key: "regexp:^b.*"
        query_per_minute: 100
      # All requests are matched. For each request, 1,000 QDH is allowed.
      - 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