把 Kong 学明白,最稳的办法不是背命令,而是先建立一个不会乱的类比。
把你的系统想成一座城市:
- 城市边界上的大门,是
Gateway - 每个门口贴的放行规则,是
Route - 城里真正办事的机关大楼,是
Service - 大楼背后的多条道路和多个窗口,是
Upstream / Target - 进城的人、车、机器人、合作方,是
Consumer - 通行证、身份证、工作证,是各种认证凭据
- 门口保安、限速牌、摄像头、安检机、日志系统,是
Plugin - 城市总指挥部,是
Control Plane - 真正站在一线拦车放行的岗亭,是
Data Plane
Kong 的本质,不是“又一个反向代理”,而是“把城市边界治理做成产品化能力的 API Gateway”。
#一、先把 API Gateway 心智钉死
很多人第一次接触网关,会把它理解成“请求先进来,再转发出去”。这句话没错,但太浅。
API Gateway 真正解决的是四类问题:
- 入口统一
- 策略前置
- 身份识别
- 流量治理与观测
也就是说,业务服务不想自己重复做这些事:
- 我是谁
- 你能不能进
- 你一分钟能打几次
- 这次请求该去哪台后端
- 出错了是谁的问题
- 这个调用链卡在哪一段
所以 API Gateway 不是“代转发”,而是“城市总关卡系统”。
看一张最核心的图:
客户端
|
v
+-------------------+
| Kong Gateway |
|-------------------|
| 1. 匹配 Route |
| 2. 执行 Plugin |
| 3. 识别 Consumer |
| 4. 转发到 Service |
+-------------------+
|
v
Upstream 服务再展开一点:
Request
|
v
[Route 匹配]
|
+--> [认证插件]
|
+--> [限流插件]
|
+--> [改写/变换插件]
|
+--> [日志/指标/追踪插件]
|
v
[Service]
|
v
[Upstream / Targets]你要记住一句话:
Kong 先决定“这是谁、该不该进、按什么规则进”,再决定“送去哪里”。
#二、Kong 到底在管什么
Kong 的核心实体不多,但每个都很关键。
#1. Service:城市里的办事大厅
Service 表示后端上游能力。它通常对应一个真实 API、微服务或外部系统。
比如:
- 订单服务
- 支付服务
- 用户服务
- 第三方短信网关
注意,Kong 里的 Service 不等于 Kubernetes 里的 Service。
它是网关视角下的“上游服务定义”。
#2. Route:门口放行规则
Route 决定什么请求能匹配到哪个 Service。
它可以按这些条件匹配:
- Host
- Path
- Method
- Header
- SNI
- Port
- 协议
Kong 当前有两套路由心智:
- 传统 JSON 路由
- Expressions Router 表达式路由
如果你把 Route 当成“门岗规则卡”,就不会乱。
例如:
api.example.com/ordersPOST /payments- 带特定 Header 的内部请求
- TLS SNI 为某域名的连接
Kong 会对所有 Route 做优先级排序,然后选择最高优先级的匹配项。
这意味着:
路由不是“谁先写谁生效”,而是“谁更具体、谁优先级更高谁生效”。
#3. Consumer:谁在消费你的 API
Consumer 是调用方身份。
它不一定是人,更常见是:
- 前端应用
- 手机 App
- 另一个服务
- 合作伙伴系统
- 批处理任务
有了 Consumer,Kong 才能做这些事:
- 区分不同调用方
- 绑定不同凭据
- 按调用方限流
- 做 ACL 或分组授权
- 打出调用方维度的审计日志
#4. Plugin:城市规章制度
Plugin 是 Kong 最强的扩展点。
它可以挂在不同层级:
- 全局
- Service
- Route
- Consumer
- Consumer Group
这就像城市政策可以:
- 全市生效
- 某栋楼生效
- 某个门岗生效
- 针对某类来访者生效
这也是 Kong 和“纯反向代理配置”差异最大的地方。
#三、路由怎么想,才不会配着配着就失控
路由是 Kong 的骨架。
一个稳定的路由设计,通常遵循这三个原则:
- 先按域名切边界
- 再按路径切业务
- 最后用 Header/Method 做细分
例如:
api.example.com
/users -> users-service
/orders -> orders-service
/payments -> payments-service如果还要区分内外网:
internal-api.example.com -> 内部 Route
api.example.com -> 外部 Route如果还要区分版本:
/api/v1/orders -> orders-v1
/api/v2/orders -> orders-v2这比一上来就堆复杂 Header 条件更稳。
#Route 的三个常见开关
strip_pathpreserve_hostpath_handling
最常用的理解是:
strip_path=true:外部路径前缀只是门牌号,转发时可以剥掉preserve_host=false:上游看到的 Host 不强行保留客户端 Hostpath_handling=v0:按当前推荐路径处理逻辑来
#一个最小 Kong 配置示例
下面这个配置表达的是:
- 暴露
/orders - 转到
orders-service - 用
key-auth做认证 - 用
rate-limiting做限流
_format_version: "3.0"
services:
- name: orders-service
url: http://orders.default.svc.cluster.local:8080
routes:
- name: orders-route
paths:
- /orders
strip_path: true
plugins:
- name: key-auth
config:
key_names:
- apikey
- name: rate-limiting
config:
minute: 60
policy: redis
consumers:
- username: mobile-app
keyauth_credentials:
- consumer: mobile-app
key: top-secret-key这个例子非常典型:
Service决定去哪Route决定什么请求能进Plugin决定怎么管Consumer决定你是谁
#四、插件不是“装饰品”,而是 Kong 的主战场
很多系统里,“路由”只是入口,“插件”才是治理本体。
你可以把 Kong 插件分成几大类:
- 认证类
- 安全类
- 流量控制类
- 转换类
- 日志与观测类
- 协议增强类
最常见的组合通常是:
认证 -> 授权 -> 限流 -> 转换 -> 观测 -> 转发这就是城市门岗流程:
先验身份
再看权限
再控流量
再改写格式
再记日志
最后放行#插件挂载位置怎么选
最实用的经验是:
- 全局插件:全城统一规则,慎用
- Service 级插件:一类业务统一规则
- Route 级插件:某个入口差异化规则
- Consumer 级插件:对特定调用方单独管控
- Consumer Group:对一组调用方统一治理
经验法则:
- 同一个后端服务有“内外两个入口”,优先挂在 Route
- 同一个服务所有入口都必须认证,优先挂在 Service
- 某个大客户有独立配额,挂在 Consumer 或 Consumer Group
#插件执行顺序
Kong 内置插件有静态优先级。
高级场景还能做动态插件排序,但这是进阶能力,且和版本、授权、Consumer/Consumer Group 作用域都有约束。
实战上不要一开始就改顺序。
先按默认链路做清晰设计,只有出现明确依赖关系时,再处理顺序。
#五、认证:Kong 不只是“挡住没登录的人”
认证不是单一功能,而是一整套身份入口策略。
你可以把 Kong 的认证想成“门口能接受哪些证件”。
常见证件类型:
- API Key
- Basic Auth
- JWT
- mTLS
- OpenID Connect
- OAuth2 相关能力
#1. API Key:最像门禁卡
适合:
- 服务到服务
- 内部系统
- 简单合作方接入
- 快速接管旧系统
优点:
- 简单
- 易落地
- 易迁移
缺点:
- 粒度有限
- 泄漏风险高于短时令牌
- 适合机器,不适合复杂用户登录体系
#2. JWT:自带声明的身份证
适合:
- 已有统一身份平台
- 前后端分离
- 微服务间令牌透传
优点:
- 无状态验证快
- 适合分布式
- 可承载 claims
缺点:
- 撤销复杂
- 生命周期设计要谨慎
#3. mTLS:带证书的专用通道
适合:
- 高安全 B2B
- 内部东西向通信
- 零信任高要求场景
优点:
- 强身份
- 双向校验
- 防中间人能力强
缺点:
- 证书运维复杂
- 不适合所有调用方生态
#4. OIDC:把登录交给身份提供商
适合:
- 企业统一登录
- SSO
- 用户级身份联邦
- 与 Keycloak、Okta、Auth0 等对接
这类心智不是“自己发卡”,而是“信任外部发证中心”。
要注意一点:
Kong 的 OpenID Connect 插件是 Enterprise 能力。
所以你做选型时要先分清:
- 我要机器调用认证,还是用户登录认证
- 我要自管简单凭据,还是接企业 IdP
- 我是 OSS 诉求,还是可接受 Enterprise/Konnect 方案
#多认证插件并存怎么理解
Kong 支持一个 Service 或 Route 上配置多个认证插件。
你可以把它想成“这个门既认工卡,也认临时二维码”。
但这不是“随便叠”。
多认证链路必须把“谁先认、认完是否短路、匿名访问怎么处理”想清楚。
#六、限流:不是只有“每分钟 100 次”这么简单
限流是 API Gateway 最容易被低估的能力。
它真正回答的是:
- 按谁限
- 限什么
- 在哪里记账
- 跨节点怎么算一致
#1. 按谁限
常见维度:
- 按 IP
- 按 Consumer
- 按 Credential
- 按 Service / Route
- 按业务分组
#2. 限什么
常见指标:
- 每秒请求数
- 每分钟请求数
- 并发
- 响应体量
- GraphQL 查询成本
- AI Token 成本
#3. 记账策略怎么选
Kong 常见限流策略有:
localclusterredis
理解成城市里的三种计数本:
local:每个岗亭自己记,快,但多岗亭容易不一致cluster:统一总账本,准,但每次都要查账redis:外接高速共享账本,通常是分布式常用方案
选择建议:
- 单节点或允许轻微偏差:
local - 多节点高一致性:优先
redis - 已有数据库模式且流量不大:可考虑
cluster
但有一个关键坑:
Hybrid 模式下,Rate Limiting 相关插件不支持 cluster 策略,通常要用 local 或 redis。
这点非常重要,因为很多人会天然以为“有控制平面就能集群统一计数”,实际上不是这样。
#一个更像生产的限流片段
plugins:
- name: rate-limiting
service: orders-service
config:
minute: 300
policy: redis如果你希望对某个大客户单独放大额度:
plugins:
- name: rate-limiting
consumer: mobile-app
service: orders-service
config:
minute: 3000
policy: redis#七、观测:没有观测,网关就是黑盒门房
Kong 在生产里是否好用,观测能力决定一半。
你至少要看三层:
- Metrics
- Logs
- Traces
#1. Metrics:城市仪表盘
Prometheus 插件会暴露指标。
要注意,Kong 的 Prometheus 指标是节点级的。
这意味着:
- 你的 Prometheus 必须发现并抓取所有 Kong 节点
- 不是只抓一个地址就代表全局状态
这和很多新手想象的“抓一个网关入口就行”不同。
#2. Logs:进出城台账
你至少应该记录:
- 请求路径
- 状态码
- 上游耗时
- 调用方身份
- 请求 ID
- 错误原因
否则线上出事时,你只能看到“502 了”,但不知道:
- 是路由没匹配
- 是认证失败
- 是上游超时
- 还是插件自己报错
#3. Traces:穿城调用链
Kong 支持 OpenTelemetry 能力。
它不仅能打顶层请求 span,还能在一些配置下跟踪:
- router 执行
- DNS 查询
- balancer 重试
- OpenResty HTTP client 请求
- plugin 阶段
这意味着什么?
意味着网关不再只是“入口耗时 120ms”。
你可以进一步知道:
- 路由匹配慢不慢
- 上游重试发生没发生
- DNS 抖没抖
- 某个插件是不是在拖慢请求
#一个最小观测配置示例
plugins:
- name: prometheus
- name: opentelemetry
config:
traces_endpoint: http://otel-collector.monitoring:4318/v1/traces
logs_endpoint: http://otel-collector.monitoring:4318/v1/logs
resource_attributes:
service.name: kong-gateway同时你会在 Kong 全局配置里关注:
tracing_instrumentations = all
tracing_sampling_rate = 1.0生产里通常不会长期 1.0 全采样,但学习阶段这样最直观。
#八、控制平面 / 数据平面:真正的“总指挥部 vs 一线岗亭”
这是 Kong 的高级心智,也是很多人第一次最容易混的地方。
#1. Traditional 模式
Kong 节点 <-> PostgreSQL
Kong 节点既管配置,也处理流量像“每个岗亭都能查总档案库”。
适合:
- 小中型部署
- 结构简单
- 传统自建
#2. DB-less 模式
配置文件 --> Kong 节点内存像“岗亭拿一份完整离线蓝图上岗”。
优点:
- 少依赖
- 简洁
- GitOps 友好
缺点:
- 每个节点都要加载配置
- 不适合把它当成中央动态配置中心
decK gateway不能直接管理 DB-less 运行中的网关
#3. Hybrid 模式
+------------------+
| Control Plane |
| Admin API / DB |
+------------------+
|
配置同步 |
v
+-------------------+ +-------------------+
| Data Plane | | Data Plane |
| 只处理业务流量 | | 只处理业务流量 |
+-------------------+ +-------------------+这时:
- CP 管配置和管理接口
- DP 真正处理客户端流量
- 数据库只在 CP 一侧
- DP 保持和 CP 的配置同步连接
最重要的一句:
控制平面不是业务流量转发路径上的那一跳。
很多人误以为请求会先到 CP 再到 DP,这是错的。
真实业务请求是直接打到 DP。
#4. Konnect
Konnect 可以理解成“云上的控制平面”。
你自管或托管数据平面,Kong 托管控制面能力。
这适合:
- 多环境
- 多团队
- 需要 SaaS 管理面
- 不想自己养控制平面
#九、Kubernetes 语境下,Kong 应该怎么理解
Kubernetes 里,Kong 不是孤立存在的,至少有三个角色要分清:
- Kong Gateway
- Kong Ingress Controller
- Kong Operator
#1. KIC:翻译官,不是门岗本人
Kong Ingress Controller 的职责是:
- 监听 Kubernetes 资源变化
- 把
Ingress、HTTPRoute等资源翻译成 Kong 配置 - 推给 Kong Gateway
关键点:
KIC 自己不直接代理业务流量。
真正转发请求的是 Kong Gateway。
可以把它想成:
- KIC 是“看施工蓝图并下发指令的调度员”
- Kong Gateway 才是“站在门口执勤的岗亭”
#2. Gateway API 比 Ingress 更像现代城市规划图
Kubernetes Gateway API 的心智比 Ingress 更清晰:
GatewayClass:哪类网关Gateway:具体网关实例HTTPRoute/GRPCRoute/TCPRoute/UDPRoute:流量规则
它的优势是:
- 角色导向
- 协议感知
- 更可扩展
- 不再强依赖一堆注解拼装高级功能
Kong 官方也明确建议新用户优先采用 Gateway API 资源,例如 HTTPRoute。
#3. KIC 与 Operator 的区别
只用 KIC 时,一个容易踩的坑是:
Kong 对 Gateway API 的实现并不会自动替你把 Gateway 对应的 Deployment / Service / listeners 都创建好。
也就是说:
- 你写了
Gateway - 不代表端口、Service、Kong 监听配置就自动全齐了
而 Kong Operator 提供的是更 Kubernetes-native 的管理方式,能更完整地把 Kong 作为 K8s 资源来部署和治理。
简化理解:
KIC:把 K8s 路由资源翻译成 Kong 配置Operator:把 Kong 本身也纳入 K8s 声明式管理
#一个最小 Gateway API 示例
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: kong
annotations:
konghq.com/gatewayclass-unmanaged: "true"
spec:
controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: kong
spec:
gatewayClassName: kong
listeners:
- name: http
port: 80
protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: orders
spec:
parentRefs:
- name: kong
rules:
- matches:
- path:
type: PathPrefix
value: /orders
backendRefs:
- name: orders-svc
port: 8080这段配置表达的是:
- 用 Kong 这类网关
- 开一个 HTTP 监听口
/orders这条路由交给orders-svc:8080
#十、Kong 和 Nginx / OpenResty / Traefik / Envoy 到底怎么区分
这是选型时最容易混的部分。
#1. Kong vs Nginx
Nginx 的强项是:
- 反向代理
- 负载均衡
- 静态内容
- HTTP/TCP/UDP 代理能力
它像“高性能交通设施本体”。
Kong 的重点是:
- 面向 API 的路由模型
- Consumer 身份模型
- 插件治理
- 控制平面/数据平面管理
- 声明式配置与 APIOps
所以二者不是完全同级竞争。
工程上可以这么理解:
Nginx:你在修路和建收费站Kong:收费站系统已经成套做好,附带证件系统、限流系统、监控系统、管理后台
#2. Kong vs OpenResty
OpenResty 不是 Nginx fork,而是以 Nginx 为组件的更高层应用与网关平台。
Kong 本身就是建立在 OpenResty 之上的。
这意味着:
- OpenResty 更像“可编程网关平台”
- Kong 更像“已经做好的 API Gateway 产品”
如果你选 OpenResty,常常意味着:
- 你自己定义模型
- 你自己写大量 Lua 逻辑
- 你自己维护治理体系
如果你选 Kong,意味着:
- 你接受一套成熟的网关实体模型
- 用插件和配置扩展
- 少造大量基础轮子
一句话:
OpenResty 更像造城底座,Kong 更像已经建好的城市关卡系统。
#3. Kong vs Traefik
Traefik 的典型心智是:
- Router
- Middleware
- Service
这和 Kong 的:
- Route
- Plugin
- Service
非常接近。
Traefik 在这些场景很顺手:
- Docker / K8s 动态发现
- 简洁边缘代理
- 中小规模入口治理
- 运维入口配置简洁优先
Kong 更强的地方在于它的 API Gateway 产品心智更完整:
- Consumer
- 凭据与认证体系
- 插件治理深度
- CP/DP 分离
- 更强的 API 管理生态延展
工程上可以这样选:
- 主要诉求是自动发现 + 简洁中间件链,Traefik 很轻快
- 主要诉求是 API 治理、身份、配额、审计、平台化,Kong 更像正解
#4. Kong vs Envoy
Envoy 的心智更底层,常见模型是:
- Listener
- Filter Chain
- Route
- Cluster
它是极强的通用数据平面,尤其常见于:
- Service Mesh
- Sidecar
- 高性能 L4/L7 代理
- 复杂过滤链和协议处理
Kong 和 Envoy 的最大区别不是“谁性能高”这种空泛问题,而是抽象层级不同。
可以这么记:
Envoy:高性能可编程数据平面引擎Kong Gateway:面向 API 治理的成品网关Kong Mesh:则是基于 Kuma 和 Envoy 的服务网格体系
所以如果你在做:
- 服务网格
- sidecar 架构
- L4/L7 深度过滤编排
Envoy 心智更核心。
如果你在做:
- 统一 API 入口
- 认证
- 配额
- 开发者消费治理
- 边缘网关产品化
Kong 更直接。
#十一、最常见的误区
#误区 1:Kong 就是带插件的 Nginx
不对。
Kong 确实建立在 Nginx/OpenResty 上,但它真正提供的是 API Gateway 的领域模型和治理系统,不只是“能转发 + 能加 Lua”。
#误区 2:KIC 在代理流量
不对。
KIC 负责把 Kubernetes 资源翻译成 Kong 配置。真正代理流量的是 Kong Gateway。
#误区 3:有了 Control Plane,请求都要先过 CP
不对。
CP 主要管配置和管理接口,DP 才处理业务请求。
#误区 4:限流就是写个 minute: 100
不对。
你还必须决定:
- 按谁限
- 用什么存储策略
- 多节点一致性怎么保证
- Hybrid/Konnect 里策略是否兼容
#误区 5:插件当然越多越好
不对。
每多一层插件,就多一层时延、故障面、排障复杂度。
插件应该是“明确承担治理职责”,不是“想到什么就挂什么”。
#误区 6:Kong 的 Service 就等于 K8s Service
不对。
二者名称相同,但语义层不同。一个是网关实体,一个是 Kubernetes 服务抽象。
#误区 7:DB-less 也能像数据库模式一样随便用 decK 同步
不对。
DB-less 的核心是整份声明式配置装入内存,运行中的管理方式和 DB-backed / hybrid 不同。
#十二、Kong 适用什么,不适用什么
#适用场景
- 你要做统一 API 入口
- 你需要认证、限流、审计、观测前置化
- 你要把 API 治理做成平台能力
- 你需要清晰的 CP/DP 架构
- 你运行在 Kubernetes,且希望网关配置 Kubernetes-native
- 你不想把认证、配额、日志全堆进每个服务里重复造轮子
#不太适合的场景
- 你只是想做一个极简反向代理
- 你几乎不需要 Consumer、认证、插件治理
- 你想自己完全掌控底层代理编程模型,且有足够 OpenResty/Envoy 研发能力
- 你没有明确 API 治理需求,只是临时转发两三个服务
判断标准很简单:
如果你要的是“把入口流量接进去”,很多工具都能做。
如果你要的是“把入口流量治理成平台能力”,Kong 才开始真正发挥价值。
#十三、实战上的一套稳定落地建议
- 先定路由边界:域名、路径、版本
- 再定身份模型:Consumer、凭据、认证方式
- 再定限流维度:IP、Consumer、Service、Route
- 再定观测三件套:metrics、logs、traces
- 再定部署模式:traditional、DB-less、hybrid、Konnect
- 在 Kubernetes 中优先用 Gateway API 心智,而不是把所有高级能力都塞进 Ingress 注解
- 只在确实需要时才引入复杂插件编排和动态顺序
- 生产里优先保证“路由清晰、策略单一职责、可观测完整”,而不是追求插件花样
#十四、总结
如果只用一句话总结 Kong:
Kong 是把 API 入口治理产品化的一整套城市总关卡体系。
它的最强心智不是“会不会配插件”,而是这条主线:
Route 决定从哪个门进
Plugin 决定进门前怎么查
Consumer 决定来的人是谁
Service 决定进门后送去哪里
Upstream 决定最终落到哪台后端
CP/DP 决定谁发号施令、谁一线执勤
KIC / Gateway API / Operator 决定在 Kubernetes 里怎样声明式管理这座关卡城市你一旦把这条线想通,Kong 就不再是“配置很多的网关”,而是一座秩序清晰的 API 城市。
#官方来源链接清单
- Kong Gateway 总览:https://developer.konghq.com/gateway/
- Kong Route 实体与路由心智:https://developer.konghq.com/gateway/entities/route/
- Kong Plugin 实体与优先级:https://developer.konghq.com/gateway/entities/plugin/
- Kong Authentication 参考:https://developer.konghq.com/gateway/authentication/
- Kong Key Auth 插件:https://developer.konghq.com/plugins/key-auth/
- Kong OpenID Connect 插件:https://developer.konghq.com/plugins/openid-connect/
- Kong Rate Limiting 插件:https://developer.konghq.com/plugins/rate-limiting/
- Kong 限流策略说明:https://developer.konghq.com/gateway/rate-limiting/strategies/
- Kong Prometheus 插件:https://developer.konghq.com/plugins/prometheus/
- Kong Tracing 参考:https://developer.konghq.com/gateway/tracing/
- Kong OpenTelemetry 插件:https://developer.konghq.com/plugins/opentelemetry/
- Kong Hybrid Mode:https://developer.konghq.com/gateway/hybrid-mode/
- Kong DB-less Mode:https://developer.konghq.com/gateway/db-less-mode/
- decK 文档:https://developer.konghq.com/deck/
- Kong Ingress Controller 总览:https://developer.konghq.com/kubernetes-ingress-controller/
- Kong Ingress Controller Gateway API:https://developer.konghq.com/kubernetes-ingress-controller/gateway-api/
- Kong Operator 总览:https://developer.konghq.com/operator/
- Kong Operator Gateway API:https://developer.konghq.com/operator/dataplanes/gateway-api/
- Kubernetes Gateway API 官方概念文档:https://kubernetes.io/docs/concepts/services-networking/gateway/
- NGINX 负载均衡文档:https://nginx.org/en/docs/http/load_balancing.html
- OpenResty 官方介绍:https://openresty.org/en/
- Traefik Router 文档:https://doc.traefik.io/traefik/reference/routing-configuration/http/routing/router/
- Traefik Middleware 文档:https://doc.traefik.io/traefik/master/reference/routing-configuration/http/middlewares/overview/
- Envoy Listeners 架构文档:https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/listeners/listeners
- Envoy HTTP Filters 架构文档:https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/http/http_filters.html