全书目录

第五十二篇:Kong 完全指南 —— 城市总关卡指挥部宇宙

第五十二篇:Kong 完全指南 —— 城市总关卡指挥部宇宙

23 分钟 10,315 字 第 933 / 962 个阅读单元

把 Kong 学明白,最稳的办法不是背命令,而是先建立一个不会乱的类比。

把你的系统想成一座城市:

  • 城市边界上的大门,是 Gateway
  • 每个门口贴的放行规则,是 Route
  • 城里真正办事的机关大楼,是 Service
  • 大楼背后的多条道路和多个窗口,是 Upstream / Target
  • 进城的人、车、机器人、合作方,是 Consumer
  • 通行证、身份证、工作证,是各种认证凭据
  • 门口保安、限速牌、摄像头、安检机、日志系统,是 Plugin
  • 城市总指挥部,是 Control Plane
  • 真正站在一线拦车放行的岗亭,是 Data Plane

Kong 的本质,不是“又一个反向代理”,而是“把城市边界治理做成产品化能力的 API Gateway”。


#一、先把 API Gateway 心智钉死

很多人第一次接触网关,会把它理解成“请求先进来,再转发出去”。这句话没错,但太浅。

API Gateway 真正解决的是四类问题:

  • 入口统一
  • 策略前置
  • 身份识别
  • 流量治理与观测

也就是说,业务服务不想自己重复做这些事:

  • 我是谁
  • 你能不能进
  • 你一分钟能打几次
  • 这次请求该去哪台后端
  • 出错了是谁的问题
  • 这个调用链卡在哪一段

所以 API Gateway 不是“代转发”,而是“城市总关卡系统”。

看一张最核心的图:

text
客户端
  |
  v
+-------------------+
|   Kong Gateway    |
|-------------------|
| 1. 匹配 Route     |
| 2. 执行 Plugin    |
| 3. 识别 Consumer  |
| 4. 转发到 Service |
+-------------------+
          |
          v
     Upstream 服务

再展开一点:

text
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/orders
  • POST /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 做细分

例如:

text
api.example.com
  /users      -> users-service
  /orders     -> orders-service
  /payments   -> payments-service

如果还要区分内外网:

text
internal-api.example.com -> 内部 Route
api.example.com          -> 外部 Route

如果还要区分版本:

text
/api/v1/orders -> orders-v1
/api/v2/orders -> orders-v2

这比一上来就堆复杂 Header 条件更稳。

#Route 的三个常见开关

  • strip_path
  • preserve_host
  • path_handling

最常用的理解是:

  • strip_path=true:外部路径前缀只是门牌号,转发时可以剥掉
  • preserve_host=false:上游看到的 Host 不强行保留客户端 Host
  • path_handling=v0:按当前推荐路径处理逻辑来

#一个最小 Kong 配置示例

下面这个配置表达的是:

  • 暴露 /orders
  • 转到 orders-service
  • key-auth 做认证
  • rate-limiting 做限流
yaml
_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 插件分成几大类:

  • 认证类
  • 安全类
  • 流量控制类
  • 转换类
  • 日志与观测类
  • 协议增强类

最常见的组合通常是:

text
认证 -> 授权 -> 限流 -> 转换 -> 观测 -> 转发

这就是城市门岗流程:

text
先验身份
再看权限
再控流量
再改写格式
再记日志
最后放行

#插件挂载位置怎么选

最实用的经验是:

  • 全局插件:全城统一规则,慎用
  • 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 常见限流策略有:

  • local
  • cluster
  • redis

理解成城市里的三种计数本:

  • local:每个岗亭自己记,快,但多岗亭容易不一致
  • cluster:统一总账本,准,但每次都要查账
  • redis:外接高速共享账本,通常是分布式常用方案

选择建议:

  • 单节点或允许轻微偏差:local
  • 多节点高一致性:优先 redis
  • 已有数据库模式且流量不大:可考虑 cluster

但有一个关键坑:

Hybrid 模式下,Rate Limiting 相关插件不支持 cluster 策略,通常要用 localredis

这点非常重要,因为很多人会天然以为“有控制平面就能集群统一计数”,实际上不是这样。

#一个更像生产的限流片段

yaml
plugins:
  - name: rate-limiting
    service: orders-service
    config:
      minute: 300
      policy: redis

如果你希望对某个大客户单独放大额度:

yaml
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 抖没抖
  • 某个插件是不是在拖慢请求

#一个最小观测配置示例

yaml
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 全局配置里关注:

conf
tracing_instrumentations = all
tracing_sampling_rate = 1.0

生产里通常不会长期 1.0 全采样,但学习阶段这样最直观。


#八、控制平面 / 数据平面:真正的“总指挥部 vs 一线岗亭”

这是 Kong 的高级心智,也是很多人第一次最容易混的地方。

#1. Traditional 模式

text
Kong 节点 <-> PostgreSQL
Kong 节点既管配置,也处理流量

像“每个岗亭都能查总档案库”。

适合:

  • 小中型部署
  • 结构简单
  • 传统自建

#2. DB-less 模式

text
配置文件 --> Kong 节点内存

像“岗亭拿一份完整离线蓝图上岗”。

优点:

  • 少依赖
  • 简洁
  • GitOps 友好

缺点:

  • 每个节点都要加载配置
  • 不适合把它当成中央动态配置中心
  • decK gateway 不能直接管理 DB-less 运行中的网关

#3. Hybrid 模式

text
        +------------------+
        | 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 资源变化
  • IngressHTTPRoute 等资源翻译成 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 示例

yaml
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 入口治理产品化的一整套城市总关卡体系。

它的最强心智不是“会不会配插件”,而是这条主线:

text
Route 决定从哪个门进
Plugin 决定进门前怎么查
Consumer 决定来的人是谁
Service 决定进门后送去哪里
Upstream 决定最终落到哪台后端
CP/DP 决定谁发号施令、谁一线执勤
KIC / Gateway API / Operator 决定在 Kubernetes 里怎样声明式管理这座关卡城市

你一旦把这条线想通,Kong 就不再是“配置很多的网关”,而是一座秩序清晰的 API 城市。

#官方来源链接清单