<p class="shortdesc">访问限流。限流方法是一段时间内的访问次数限制，即如果设置second为1则表示一秒钟内只能一次访问。</p> <p class="p"><strong class="ph b">限流值说明</strong>：</p> <ul class="ul" id="rate-limiting__ul_bhb_1rx_2sb"> <li class="li">次数限制是通过second/minute/hour/day/month/year，这几个字段设定（不需要全部设定，需要哪个级别的再设置即可。）</li> <li class="li">如果同时设置了多个维度，则大区间的值应该大于小区间的值。即如果设置了second和minute，则minute的值应该大于second的值。表示一秒钟内有次数限制，一分钟内也有次数限制，两个策略是同时满足才行。</li> </ul> <p class="p"><strong class="ph b">示例</strong>：</p> <ul class="ul" id="rate-limiting__ul_yv5_brx_2sb"> <li class="li">如果second=1，minute=2（其他未设定）,结果是一分钟只能访问2次，并且2次的间隔是1秒。</li> <li class="li">如果minute=1，hour=3(其他未设定)，结果是一小时只能访问3次，并且每次访问的间隔是1分钟。</li> <li class="li">如果超过限制则默认返回</li> <li class="li">http_code: 429（可设置）</li> <li class="li">body: {“status”:429,”message”:”API rate limit exceeded”}</li> </ul> <section class="section" id="rate-limiting__section_zch_crx_2sb"><h2 class="doc-tairway">配置参数说明</h2> <div class="p"> <table class="table" id="rate-limiting__table_p2b_2rx_2sb"><caption></caption><colgroup><col><col><col><col><col></colgroup><thead class="thead"> <tr class="row"> <th class="entry align-left" id="rate-limiting__table_p2b_2rx_2sb__entry__1">参数名</th> <th class="entry align-left" id="rate-limiting__table_p2b_2rx_2sb__entry__2">参数类型</th> <th class="entry align-left" id="rate-limiting__table_p2b_2rx_2sb__entry__3">是否必须</th> <th class="entry align-left" id="rate-limiting__table_p2b_2rx_2sb__entry__4">默认值</th> <th class="entry align-left" id="rate-limiting__table_p2b_2rx_2sb__entry__5">参数说明</th> </tr> </thead><tbody class="tbody"> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">second</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">second/minute/hour/day/month/year中必须有一个值。如果设置值的话，必须大于0</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">minute</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">hour</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">day</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">month</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">year</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">limit_by</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">ip</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">可选值：{“consumer”, “credential”, “ip”, “header”}。如果使用consumer/credential则需要配合kong的认证插件jwt/key-auth/oauth生成访问用户如果没有访问用户则默认使用IPheader 需要1.3.2版本或以上Pafa-Cloud-Kong。如果header无值，或者header_key没有设置，则默认使用IP</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">policy</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">Y</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">cluster</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">可选值：{“local”, “cluster”, “redis”, “redis_cluster”， “redis_sentinel”}local:存储在Nginx共享内容，不支持集群。cluster：存储在数据库的rate-limiting表中，支持集群访问。redis: 存储redis到单redis实例redis_cluster: 配置多个redis实例，如果有一个出现连接失败会转向另外的redis实例。（1.3.4或以后版本支持）redis_sentinel: 配置Redis哨兵模式地址。（1.3.4或以后版本支持）</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_cluster</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">table</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">多redis实例节点配置，如果policy选择redis_cluster则此项必须填写。配置的redis实例必须都是可读写的。规则：pafa-cloud-kong会根据limit_by的值hash到一个固定的实例节点，如果实例节点出现异常，则会重新hash到正常的实例节点配置示例：可见下面的配置示例</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_sentinels</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">table</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">多个redis哨兵配置。如果policy选择redis_sentinel则此项必须填写。kong会根据limit_by的值hash到一个可用的哨兵处获取master节点的信息，如果实例节点出现异常，则会重新hash到正常的实例节点。具体配置可见下面的配置示例</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">fault_tolerant</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">true</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">如果为true则在获取访问量错误后继续访问，不会直接返回错误，会继续加访问量数据。如果为false则会返回500错误，不能再继续访问。</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_host</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于单redis实例节点配置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_port</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">6379</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于单redis实例节点配置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_password</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于单redis实例节点配置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_timeout</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">2000</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于单redis实例节点配置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">redis_database</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">0</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于单redis实例节点配置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">hide_client_headers</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">boolean</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">true</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">开启插件后，header中会写入X-RateLimit-Limit-{second/minute/hour/day/month/year}X-RateLimit-Remaining-{second/minute/hour/day/month/year}设置为true后则不显示这2个header</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">http_code</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">429</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">http请求返回状态码，默认是429.</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">response_status_key</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">“status”</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于定制超过限制的返回结果，具体可看下面返回结果示例。以下属性需Pafa-Cloud-Kong 1.3.2版本或以上支持</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">response_status_value</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">429</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">response_msg_key</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">“message”</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">response_msg_value</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">“API rate limit exceeded”</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 "></td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">header_key</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">string</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于limit_by=header时的header key设置</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">limit_policy</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">object</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 "></td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">用于设置特定渠道的特定访问规则，具体可看下面特定访问规则</td> </tr> <tr class="row"> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__1 ">blacklist_time</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__2 ">number</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__3 ">N</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__4 ">0(单位：秒)</td> <td class="entry align-left" headers="rate-limiting__table_p2b_2rx_2sb__entry__5 ">黑名单屏蔽时间。如果请求符合上述限流规则后，并期望延长屏蔽时间可以设置此字段。（1.3.5或以上版本支持）（暂不支持policy=cluster）</td> </tr> </tbody></table> </div> </section> <section class="section" id="rate-limiting__section_crn_2rx_2sb"><h2 class="doc-tairway">配置示例</h2> <p class="p">如下配置是全配置，用户可根据需要设置，不需要的字段可以不设置。</p> <pre class="pre codeblock" id="rate-limiting__codeblock_py2_grx_2sb"><code>{ "limit_by": "ip", "policy": "local", "fault_tolerant": true, "hide_client_headers": true, "response_status_key": "status", "response_status_value": "429", "response_msg_key": "message", "response_msg_value": "API rate limit exceeded", "second": 1, "minute": 0, "hour": 0, "day": 0, "month": 0, "year": 0, "header_key":"", //用于limit_by=header时的header key设置，即从哪个header中读取数据 "blacklist_time":3600, "redis_host": "", "redis_port": 6379, "redis_password": "", "redis_timeout": 2000, "redis_database": 0, "redis_cluster":[ // 如果policy=redis_cluster则此项必须有一个配置 { "redis_host": "127.0.0.1", "redis_port": 6379, "redis_password": "", "redis_timeout": 2000, "redis_database": 0 }, { "redis_host": "127.0.0.2", "redis_port": 6379, "redis_password": "", "redis_timeout": 2000, "redis_database": 0 } ], "redis_sentinels":[ { "redis_host": "127.0.0.1", // 哨兵IP "redis_port": "16000", // 哨兵端口 "redis_password" : "******", // 哨兵密码 "redis_timeout": 2000, // redis连接超时时间 "master_database": 0, // master节点的数据库 "master_password": "******", // master节点的密码 "master_name": "mymaster" // master节点的名称 } ], "limit_policy" : { "127.0.0.1": { //此处的key根据limit_by来设定，如果limit_by=ip，则此处是IP "second": 0, "minute": 1, "hour": 0, "day": 0, "month": 0, "year": 0 } } }</code></pre> </section>