📚 课程目录第2章 Kong网关基础回顾

2. Kong 网关基础：核心组件、插件体系与声明式配置

Kong Gateway 是一个基于 OpenResty (Nginx + Lua) 构建的高性能 API 网关。在生产环境中，它通常以集群模式部署，承担着流量入口、认证鉴权、流量控制、协议转换等核心职责。理解其三大核心组件、插件扩展机制以及声明式配置工具 decK，是后续实现配置同步与回滚护栏的基石。

2.1 三大核心组件：Admin API、Proxy 与 DB

Kong 的运行时架构由三个逻辑组件构成，它们各司其职，共同支撑网关的流量处理与配置管理。

组件	端口（默认）	核心职责	生产注意事项
Admin API	8001 (HTTP) / 8444 (HTTPS)	提供 RESTful 接口管理所有网关实体（Service、Route、Upstream、Consumer、Plugin 等）。	必须绑定内网或启用 RBAC 认证，禁止暴露到公网。
Proxy	8000 (HTTP) / 8443 (HTTPS)	接收客户端请求，根据 Route 规则匹配 Service，并执行插件链后转发到上游。	对外暴露的流量入口，通常配置 TLS 和负载均衡。
DB (Database)	5432 (PostgreSQL) / 9042 (Cassandra)	持久化存储所有运行时配置（声明式配置的最终状态）。	推荐使用 PostgreSQL 并开启主从复制，确保高可用。

架构要点： Admin API 是“写”入口，Proxy 是“读”入口，DB 是状态存储。所有对网关配置的变更（包括 decK 同步）最终都会通过 Admin API 写入 DB，然后由 Kong 节点从 DB 中拉取最新配置到本地缓存。

2.2 插件体系：扩展网关能力的核心机制

Kong 的插件系统是其生态的核心。插件以“链”的形式附加在 Route 或 Service 上，在请求的生命周期中按顺序执行。每个插件可以作用于不同的阶段（如 access、header_filter、body_filter、log）。

2.2.1 插件分类与典型场景

分类	典型插件	应用场景
认证	Key-Auth, JWT, OAuth2, Basic-Auth, HMAC	API 鉴权、单点登录集成
安全	IP Restriction, Bot Detection, CORS	IP 白名单、爬虫拦截、跨域配置
流量控制	Rate Limiting, Request Size Limiting	API 限流、请求体大小限制
可观测性	Prometheus, Zipkin, File Log, Syslog	指标采集、链路追踪、日志审计
转换	Request Transformer, Response Transformer	请求/响应头或 Body 的改写
协议	gRPC Gateway, WebSocket Upgrade	协议转换、WebSocket 代理

  配置同步关键点： 插件的配置（如限流阈值、JWT 密钥）是声明式配置中最容易出错的部分。在回滚场景中，必须确保插件配置的完整性和版本一致性，否则可能导致认证失败或限流失效。

2.3 声明式配置与 decK

Kong 原生支持通过 Admin API 进行 CRUD 操作，但在多环境（开发、测试、生产）管理和版本控制场景下，声明式配置是更优的选择。decK（Kong 官方 CLI 工具）正是为此而生。

2.3.1 decK 的核心能力

dump：从运行中的 Kong 实例导出完整配置为 YAML/JSON 文件。
sync：将本地声明式配置文件与 Kong 实例状态进行“差异同步”，只变更不一致的部分。
diff：预览本地文件与线上配置的差异，类似 git diff。
ping：测试 decK 与 Admin API 的连接性。
validate：在同步前校验声明式文件的语法和逻辑正确性。

2.3.2 声明式配置文件结构示例

一个标准的 decK 配置文件（kong.yaml）包含以下顶层字段：

_format_version: "3.0"
_transform: true

services:
  - host: user-service.internal
    name: user-service
    port: 8080
    protocol: http
    routes:
      - name: user-api
        paths:
          - /api/v1/users
        methods:
          - GET
          - POST
        strip_path: false
    plugins:
      - name: key-auth
        enabled: true
      - name: rate-limiting
        config:
          minute: 100
          policy: local

consumers:
  - username: client-app
    keyauth_credentials:
      - key: my-secret-key-123

upstreams:
  - name: user-service.v1
    targets:
      - target: 10.0.1.10:8080
        weight: 100
      - target: 10.0.1.11:8080
        weight: 50

常见陷阱： 使用 decK sync 时，如果本地文件缺失某个实体（如某个 Consumer），默认行为是删除该实体。在生产环境中，务必先使用 decK diff 预览变更，或使用 --select-entity 参数限定同步范围，避免误删。

2.4 本章小结

组件分工明确：Admin API 负责配置写入，Proxy 负责流量处理，DB 负责状态持久化。
插件是扩展点：认证、限流、日志等能力通过插件链实现，配置同步时必须保证插件参数的精确性。
decK 是配置同步的基石：通过 diff + sync 实现声明式管理，结合 Git 版本控制即可构建基础的配置回滚能力。