Kong学习笔记：插件

本文更新于2026-09-23，操作系统为Debian 12.13 (bookworm)，使用Kong Enterprise 3.13.0.1（含OpenResty 1.27.1.2）。

目录

插件存放于/usr/local/share/lua/5.1/kong/plugins目录下。

执行顺序：

插件 优先级
pre-function +inf
zipkin 100000
ip-restriction 3000
bot-detection 2500
cors 2000
session 1900
kubernetes-sidcar-indector 1006
jwt 1005
oauth2 1004
key-auth 1003
ldap-auth 1002
basic-auth 1001
hmac-auth 1000
request-size-limiting 951
acl 950
rate-limiting 901
response-ratelimiting 900
request-transformer 801
response-transformer 800
aws-lambda 750
azure-functions 749
prometheus 13
http-log 12
statsd 11
datadog 10
file-log 9
udp-log 8
tcp-log 7
loggly 6
syslog 4
galileo 3
request-termination 2
correlation-id 1
post-function -1000

鉴权类插件

包括：Basic Authentication、HMAC Authentication、JWT、Key Authentication、OAuth 2.0 Authentication、Session、Upstream Http Basic Authentication等。

当不允许匿名消费者时，鉴权插件始终执行身份验证，其与其它鉴权插件验证结果取“与”的关系。当允许匿名消费者时，仅当此鉴权插件验证失败时才会执行下一个，其与其它鉴权插件验证结果取“或”的关系，如所有鉴权插件都验证失败，则当作匿名消费者接入。

basic-auth

插件会依次检查请求头中Proxy-Authorization和Authorization对应的内容。

可以作用于服务、路由、全局。

配置参数：

  • anonymous：当身份验证失败时是否使用匿名消费者。
  • hide_credentials：将请求代理给上游服务时是否隐藏凭证信息。默认为false。

jwt

根据RFC7519协议中指定的包含HS256算法（对称加密算法）或RS256算法（非对称加密算法）的JWT令牌对请求进行身份校验，还会对RFC7519协议中某些注册的声明（如exp、nbf）进行验证。

可以作用于服务、路由、全局。

配置参数：

  • anonymous：当身份验证失败时是否使用匿名消费者。
  • claims_to_verify：Kong网关验证的声明列表。
  • cookie_names：用于检索JWT信息的Cookie列表。
  • header_names：用于检索JWT信息的请求头列表。
  • maximum_expiration：JWT过期时间。如果指定该参数，还需在claims_to_verify参数中添加exp字段。
  • run_on_preflight：是否在预检请求中执行身份验证。默认为false。
  • secret_is_base64：凭证的密钥是否启用base64编码。当为true时，消费者需要创建一个base64编码的密钥，在对JWT签名时使用原始密钥。默认为false。
  • uri_param_names：用于检索JWT信息的请求参数列表。

key-auth

配置参数：

  • anonymous：当身份验证失败时是否使用匿名消费者。

oauth2

支持OAuth 2.0的4中授权模式：授权码模式、隐式授权模式、密码模式、客户端凭证模式。

可以作用于服务、全局。

配置参数：

  • accept_http_if_already_terminated：如果HTTPS请求已被代理或负载均衡器终止，是否接收HTTP请求。
  • anonymous：当身份验证失败时是否使用匿名消费者。
  • auth_header_name：携带access token的请求头名。默认为Authorization。
  • enable_authorization_code：是否启用授权码模式。
  • enable_client_credentials：是否启用客户端凭证模式。
  • enable_implicit_grant：是否启用隐式授权模式。
  • enable_password_grant：是否启用密码模式。
  • global_credentials：是否与其它插件合用OAuth 2.0配置。默认为false。
  • hash_secret：client_secret是否以哈希形式存储。默认为false。
  • hide_credentials：将请求代理给上游服务时是否隐藏凭证信息。默认为false。
  • mandatory_scope：用户是否强制至少授权一个作用域。默认为false。
  • pkce：pkce模式。可为none、lax、strict。
  • refresh_token_ttl：access token和refresh token的有效时间。0表示永久有效。默认为2周。
  • reuse_refresh_token：刷新access token时是否保留refresh token。默认为false。
  • scopes：用户可以访问的作用域列表。
  • token_expiration：令牌过期时间。0表示禁用过期时间。默认为7200。

安全类插件

包括：ACME、Bot Detection、CORS、IP Restriction等。

ip-restriction

实现IP黑白名单功能。一个插件实例，只能配置黑名单或白名单之一。

可以作用于消费者、服务、路由、全局。

配置参数：

  • allow：IP白名单列表。与deny互斥。
  • deny：IP黑名单列表。与allow互斥。

流量类插件

包括：ACL、Proxy Cache、Rate Limiting、Request Size Limiting、Request Termination、Response Rate Limiting等。

proxy-cache

为反向代理提供缓存功能。可以基于响应码、响应内容类型、请求方法来缓存响应实体。

可以作用于消费者、服务、路由、全局。

配置参数：

  • cache_control：是否遵守RFC7234定义的缓存控制行为。
  • cache_ttl：缓存生存时间，单位为秒。默认为300。
  • content_type：缓存的响应内容类型。必需完全匹配。默认为text/plain和application/json。
  • memory：
    • dictionary_name：保存缓存对象的共享字段名称。
  • request_method：缓存的请求方法。默认为GET和HEAD。
  • response_code：缓存的响应状态码。默认为200、301和404。
  • storage_ttl：缓存在后端存储的生存时间。该值与cache_ttl独立。
  • strategy：缓存的存储策略。默认为memory。
  • vary_headers：组成缓存键的请求头信息。
  • vary_query_params：组成缓存键的请求参数。

rate-limiting

限定接口调用方在给定单位时间内的接口调用数。

可以作用于消费者、服务、路由、全局。

配置参数：

  • day：每天请求限流次数。
  • fault_tolerant：当Kong网关连接外部数据库发生问题时，是否继续代理请求。默认为true。
  • header_name：参与限流统计的请求头。
  • hide_client_headers：是否隐藏响应头信息。
  • hour：每小时请求限流次数。
  • limit_by：限流维度。可为consumer、credential、header、ip、service。默认为consumer。
  • minute：每分钟请求限流次数。
  • month：每月请求限流次数。
  • policy：限流策略。可为cluster、local、redis。
  • redis_database：Redis数据库。默认为0。
  • redis_host：Redis地址。
  • redis_password：Redis密码。
  • redis_port：Redis端口。默认为6379。
  • redis_timeout：Redis超时时间。默认为2000毫秒。
  • second：每秒请求限流次数。
  • year：每年请求限流次数。

request-termination

截断用户请求，使用自定义的状态码和响应信息返回响应。

可以作用于消费者、服务、路由、全局。

配置参数：

  • body：响应体。与message互斥。
  • content_type：响应的Content-Type。默认为application/json; charset=utf-8。
  • message：响应消息。与body互斥。
  • status_code：响应码。默认为503。

response-ratelimiting

根据上游服务返回的响应头限制客户端发送的请求数。

可以作用于消费者、服务、路由、全局。

配置参数：

  • block_on_first_violation：当达到某个限流条件时，是否立即响应请求。
  • fault_tolerant：当Kong网关连接外部数据库发生问题时，是否继续代理请求。默认为true。
  • header_name：递增计数器的响应头名称。值为LIMITNAME=N。
  • hide_client_headers：是否隐藏响应头信息。
  • limit_by：限流维度。可为consumer、credential、ip。
  • limits：限流列表。
    • LIMITNAME：自定义的限流名。
      • day：每天限流次数。
      • hour：每小时限流次数。
      • minute：每分钟限流次数。
      • month：每月限流次数。
      • second：每秒限流次数。
      • year：每年限流次数。
  • policy：限流策略。可为cluster、local、redis。
  • redis_database：Redis数据库。默认为0。
  • redis_host：Redis地址。
  • redis_password：Redis密码。
  • redis_port：Redis端口。默认为6379。
  • redis_timeout：Redis超时时间。默认为2000毫秒。

分析监控类插件

包括：Datadog、Prometheus、Zipkin等。

promethetheus

以Prometheus Exposition格式公开Kong网关和上游服务相关的指标，Prometheus服务器会对这些指标进行抓取。

可以作用于服务、全局。

配置参数：无。

内容转换类插件

包括：Correlation ID、gRPC-gateway、gRPC-Web、Request Transformer、Response Transformer等。

request-transformer

在向上游服务发送请求前，转换客户端发送给Kong网关的请求内容。

可以作用于消费者、服务、路由、全局。

配置参数：

  • add：添加的内容列表。
    • body：添加的请求体表单参数列表。格式为KEY:VALUE。
    • headers：添加的请求头列表。格式为KEY:VALUE。
    • querystring：添加的查询参数列表。格式为KEY:VALUE。
  • append：追加的内容列表。
    • body：追加的请求体表单参数列表。格式为KEY:VALUE。
    • headers：追加的请求头列表。格式为KEY:VALUE。
    • querystring：追加的查询参数列表。格式为KEY:VALUE。
  • http_method：向上游请求的HTTP方法。
  • remove：删除的内容列表。
    • body：删除的请求体表单参数列表。
    • headers：删除的请求头列表。
    • querystring：删除的查询参数列表。
  • rename：重命名的内容列表。
    • body：重命名的请求体表单参数列表。格式为KEY:NEWKEY。
    • headers：重命名的请求头列表。格式为KEY:NEWKEY。
    • querystring：重命名的查询参数列表。格式为KEY:NEWKEY。
  • replace：替换的内容列表。
    • body：替换的请求体表单参数列表。格式为KEY:VALUE。
    • headers：替换的请求头列表。格式为KEY:VALUE。
    • querystring：替换的查询参数列表。格式为KEY:VALUE。
    • uri：向上游请求的URI。

response-transformer

在向客户端返回响应前，转换上游服务发送给Kong网关的响应内容。

可以作用于消费者、服务、路由、全局。

配置参数：

  • add：添加的内容列表。
    • headers：添加的响应头列表。格式为KEY:VALUE。
    • json：添加的响应体JSON参数列表。格式为KEY:VALUE。
    • json_types：添加的响应体参数类型。格式为KEY:TYPE。
  • append：追加的内容列表。
    • headers：追加的响应头列表。格式为KEY:VALUE。
    • json：追加的响应体JSON参数列表。格式为KEY:VALUE。
    • json_types：追加的响应体参数类型。格式为KEY:TYPE。
  • remove：删除的内容列表。
    • headers：删除的响应头列表。
    • json：删除的响应体JSON参数列表。
  • rename：重命名的内容列表。
    • headers：重命名的响应头列表。格式为KEY:NEWKEY。
  • replace：替换的内容列表。
    • headers：替换的响应头列表。格式为KEY:VALUE。
    • json：替换的响应体JSON参数列表。格式为KEY:VALUE。
    • json_types：替换的响应体参数类型。格式为KEY:TYPE。

日志类插件

包括：File Log、Http Log、Sys Log、Tcp Log、Udp Log等。

file-log

将请求和响应写入磁盘上的日志文件。不建议在生产环境使用，其使用阻塞文件I/O，会严重影响性能。

可以作用于消费者、服务、路由、全局。

配置参数：

  • path：日志文件的路径。如果文件不存在，会自动创建。Kong需要有此文件的写入权限。
  • reopen：是否每次请求都关闭并重新打开文件。

http-log

将请求和响应记录到HTTP服务器。

配置参数：

  • endpoint：服务URL。
  • keepalive：连接存活毫秒数。默认为1000。
  • method：请求方法，可为PATCH、POST、PUT。默认为POST。
  • timeout：超时毫秒数。默认为1000。

tcp-log

将请求和响应记录到TCP服务器。

可以作用于消费者、服务、路由、全局。

配置参数：

  • host：接收数据的IP或主机名。
  • keepalive：空闲连接存活时间，单位为毫秒。默认为60000。
  • port：接收数据的端口。
  • timeout：超时时间，单位为毫秒。默认为10000。
posted @ 2026-09-24 00:05  garvenc  阅读(10)  评论(0)    收藏  举报