Kong API 网关部署与实战指南

1. Kong API 网关简介

Kong 是一款开源的、轻量级的 API 网关，专为微服务架构优化设计，具备极高的低延迟性能和出色的可扩展性。它构建于 OpenResty 之上，借助 Nginx 的高性能事件驱动模型和 Lua 的动态脚本能力，为微服务集群提供了统一的流量入口。

Kong 的核心概念与特性如下表所示：

2. 环境部署

Kong 基于 OpenResty 运行，依赖较多底层组件。对于生产环境，强烈推荐使用 Docker 或 Kubernetes 方式部署。本节以 Docker 部署为例，其他安装方式可参考 Kong 官方文档。

2.1 安装 Kong

第一步：创建 Docker 网络

docker network create kong-net

第二步：启动 PostgreSQL 实例

Kong 需要数据库来存储配置数据（路由、服务、插件等），这里使用 PostgreSQL：

docker run -d --name kong-database \
    --network=kong-net \
    -p 5432:5432 \
    -e "POSTGRES_USER=kong" \
    -e "POSTGRES_DB=kong" \
    -e "POSTGRES_PASSWORD=kong" \
    postgres:9.6

第三步：初始化数据库

docker run --rm \
    --network=kong-net \
    -e "KONG_DATABASE=postgres" \
    -e "KONG_PG_HOST=kong-database" \
    -e "KONG_PG_PASSWORD=kong" \
    -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
    kong:latest kong migrations bootstrap

第四步：启动 Kong 网关

docker run -d --name kong \
    --network=kong-net \
    -e "KONG_DATABASE=postgres" \
    -e "KONG_PG_HOST=kong-database" \
    -e "KONG_PG_PASSWORD=kong" \
    -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
    -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
    -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
    -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
    -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
    -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
    -e "KONG_PLUGINS=bundled" \
    -p 8000:8000 \
    -p 8443:8443 \
    -p 127.0.0.1:8001:8001 \
    -p 127.0.0.1:8444:8444 \
    kong:latest

端口说明：

• 8000：HTTP 代理端口，客户端请求入口
• 8443：HTTPS 代理端口
• 8001：Admin API 管理端口（仅监听本地）
• 8444：Admin API 的 HTTPS 端口

第五步：验证安装

curl -i http://localhost:8001/

返回 HTTP 200 状态码则表示 Kong 已成功启动。

2.2 安装 Konga 管理界面

Konga 是一款第三方 Kong Admin API 的图形化管理界面，提供了可视化的网关配置能力，极大降低了运维门槛。

初始化 Konga 数据库

docker pull pantsel/konga:latest
docker run --rm -it --network=kong-net \
    --entrypoint=/usr/local/bin/node \
    pantsel/konga:latest \
    ./bin/konga.js prepare \
    --adapter postgres \
    --uri postgresql://kong:kong@kong-database:5432/konga

启动 Konga 服务

docker run -d --name konga -p 1337:1337 \
    --network=kong-net \
    -e "TOKEN_SECRET=abcdef" \
    -e "DB_ADAPTER=postgres" \
    -e "DB_HOST=kong-database" \
    -e "DB_PORT=5432" \
    -e "DB_USER=kong" \
    -e "DB_PASSWORD=kong" \
    -e "DB_DATABASE=konga" \
    -e "DB_PG_SCHEMA=public" \
    -e "NODE_ENV=production" \
    pantsel/konga:latest

启动后访问 http://<服务器IP>:1337 即可进入 Konga 管理界面。首次登录需创建管理员账号，然后在 Connections 中配置 Kong Admin API 地址（如 http://kong:8001），即可开始通过可视化界面管理 Kong 网关。

使用 MySQL 数据库的部署方式

如果希望使用 MySQL 而非 PostgreSQL，可参考以下配置：

docker run -d -p 1337:1337 \
    --restart=always \
    -e "DB_ADAPTER=mysql" \
    -e "DB_HOST=<MySQL 主机地址>" \
    -e "DB_PORT=3306" \
    -e "DB_USER=konga" \
    -e "DB_PASSWORD=<数据库密码>" \
    -e "DB_DATABASE=konga" \
    -e "NODE_ENV=production" \
    --name konga \
    pantsel/konga

3. 服务管理实战

3.1 暴露服务：Service 与 Route

Kong 通过 Service 和 Route 两个核心对象将上游服务暴露给客户端。

• Service：上游 API 或微服务的抽象实体，通过 URL 属性（或分别指定 protocol、host、port、path）标识上游服务的地址。
• Route：决定客户端请求如何匹配并转发到后端 Service。一个 Service 可以拥有多个 Route。

通过 Konga 添加 Service 与 Route

在 Konga 的 Services 页面，点击 "Add New Service"，填写服务名称、上游 URL 等基本信息即可完成创建。

添加 Service 后，即可为该服务创建 Route。在 Routes 页面指定匹配路径（如 /demo），保存后，访问 http://localhost:8000/demo 的请求就会被转发到对应的后端 Service。

通过 Admin API 添加

创建 Service：

POST /services/
Content-Type: application/json

{
  "name": "e2emapi-service",
  "host": "e2emapi-upstream",
  "port": 80,
  "path": "/e2emapi"
}

创建 Route：

POST /services/e2emapi-service/routes
Content-Type: application/json

{
  "paths": ["/e2emapi"]
}

3.2 服务限流

Rate Limiting（限流）插件用于控制 API 的访问频率，防止服务被过度调用。在 Konga 中，可以直接在 Service 或 Route 的插件管理页面添加 Rate Limiting 插件，配置分钟、小时等维度的请求上限。

限流策略支持三种方式：

• local：基于内存的本地计数器，在每个 Kong 节点独立限流
• redis：使用 Redis 集群进行跨节点的统一计数
• cluster：使用 Kong 数据库作为中央协调点（需要数据库模式）

3.3 身份认证

身份认证是控制 API 访问权限的核心机制。Kong 内置了多种认证插件，常用的包括：

• Key Auth：基于 API Key 的认证
• Basic Auth：HTTP 基本认证
• HMAC Auth：基于签名的 HMAC 认证
• OAuth 2.0：OAuth 2.0 协议认证
• JWT：JSON Web Token 认证
• LDAP：LDAP 高级认证
• OpenID Connect：OpenID 身份认证

认证插件可直接配置到 Service 实体上，从而保护对应的上游服务。

Key Auth 认证配置示例

1. 添加 Key Auth 插件

在目标 Service 上启用 Key Auth 插件，设置 key_names 为 t1（即插件会在请求的 Header 或 Query 中查找名为 t1 的字段）。

2. 创建 Consumer

Consumer 代表 API 的使用者。需创建一个 Consumer（如 demo-access-key-id）并为其配置 Key Auth 凭证：

POST /consumers
Content-Type: application/json

{"username":"demo-access-key-id"}

3. 配置 Credentials

在 Konga 的 Consumers 面板中，为该 Consumer 添加 Key Auth Credentials，系统会自动生成一个 API Key。

4. 发起认证请求

配置完成后，未携带有效 Key 的请求将被拦截。正确的请求方式：

# 通过 Query 参数传递
curl http://localhost:8000/demo?t1=<API_KEY>

# 通过 Header 传递
curl http://localhost:8000/demo -H "t1: <API_KEY>"

HMAC 认证配置

HMAC 认证通过验证 Proxy-Authorization 或 Authorization 头中的签名来鉴权。相较于 Key Auth，HMAC 提供了更高的安全性，因为密钥不会在每次请求中直接传输。

添加 HMAC 插件：

POST /plugins
Content-Type: application/json

{"name":"hmac-auth","config":{"check_nonce":false}}

为 Consumer 添加 HMAC 凭证：

POST /consumers/<consumer-name>/hmac-auth
Content-Type: application/json

{"username":"demo-access-key-id","secret":"demo-access-key-secret"}

HMAC 签名构造方式：

signing_string="date: Thu, 22 Jun 2017 17:15:21 GMT\nGET /requests HTTP/1.1"
digest=HMAC-SHA256(<signing_string>, "secret")
base64_digest=base64(<digest>)

发起带签名的请求：

curl -i -X GET http://localhost:8000/demo \
    -H "Host: hmac.com" \
    -H "Date: Mon, 27 Apr 2020 08:35:21 GMT" \
    -H 'Authorization: hmac username="demo-username", algorithm="hmac-sha256", headers="date request-line", signature="<base64_digest>"'

3.4 负载均衡与健康检查

Upstream 与 Target

Upstream 对象代表一个虚拟主机名，用于将流量分发到多个 Target（后端节点），支持健康检查和熔断机制。

通过 Admin API 创建 Upstream：

POST /upstreams/
Content-Type: application/json

{
  "name": "e2emapi-upstream"
}

创建 Upstream 后，将 Service 的 host 指向该 Upstream，然后为 Upstream 添加 Target：

POST /upstreams/e2emapi-upstream/targets
Content-Type: application/json

{
  "target": "10.0.0.1:80",
  "weight": 100
}

配置完成后，多个 Target 之间的流量将由 Kong 的环形均衡器自动分发。

健康检查

Kong 支持两种健康检查方式：

1. 主动健康检查：定期向目标发送 HTTP/HTTPS 请求，根据响应状态码判断节点健康状况。
2. 被动健康检查（断路器）：分析正在代理的流量，根据目标的响应行为动态评估健康状况。

健康状态的判定逻辑：

• 收到配置为 healthy 的状态码：递增 Successes 计数器，清零其他计数器
• 连接失败：递增 TCP Failures 计数器
• 请求超时：递增 Timeouts 计数器
• 收到配置为 unhealthy 的状态码：递增 HTTP Failures 计数器

当任一失败计数器达到阈值，Target 被标记为不健康；当 Successes 计数器达到阈值，Target 恢复为健康状态。

常用 Admin API 接口

# 查看所有可用插件
GET /plugins/enabled

# 查看某个插件的 Schema
GET /plugins/schema/{plugin name}

# 查看所有接口
GET /endpoints

4. 配置与运维

4.1 Kong 配置文件

Kong 的默认配置文件位于 /etc/kong/kong.conf。可通过以下命令使用自定义配置：

kong start --conf /path/to/kong.conf   # 指定配置文件启动
kong check <path/to/kong.conf>         # 验证配置完整性

Kong 支持通过环境变量覆盖配置文件中的参数。环境变量的命名规则为 KONG_ 加上大写的参数名并使用下划线分隔：

# 在 kong.conf 中配置
log_level = debug

# 等价的环境变量
export KONG_LOG_LEVEL=error

Nginx 注入配置

配置文件中以 nginx_http_、nginx_proxy_、nginx_admin_ 为前缀的配置会被转换为对应的 Nginx 指令：

• nginx_http_：注入到 http 块
• nginx_proxy_：注入到 Kong 代理端口的 server 块
• nginx_admin_：注入到 Admin API 端口的 server 块

例如：

# 环境变量方式
export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"
# 等价于 nginx http 块中的
# output_buffers 4 64k;

nginx_http_include=/path/to/your/my-server.kong.conf  # 引入外部配置

4.2 命令行管理

Kong 提供了一系列命令行工具用于运维管理：

kong check <conf>                 # 检查配置
kong config init <file>           # 生成示例配置文件
kong config db_import <file>      # 将 YAML 配置导入数据库
kong config db_export <file>      # 导出数据库配置到文件
kong config parse <file>          # 检查配置语法（不加载）
kong health                       # 健康检查
kong migrations bootstrap         # 执行数据库迁移
kong start                        # 启动 Kong
kong restart                      # 重启 Kong
kong reload                       # 热重载配置（发送 HUP 信号）
kong stop                         # 停止 Kong（发送 SIGTERM）
kong quit                         # 优雅退出（发送 SIGQUIT）
kong version                      # 查看版本

不使用 kong start 的启动方式：

kong migrations bootstrap
kong prepare -p /usr/local/kong -c kong.conf
nginx -p /usr/local/kong -c /usr/local/kong/nginx.conf

这种方式适用于需要更精细控制 Nginx 启动参数的场景。

5. 混合模式部署

从 Kong 2.0 开始，引入了混合模式（Hybrid Mode），也称为控制面/数据面分离（CP/DP）。在混合模式下，Kong 节点分为两种角色：

• 控制面节点：负责管理配置和暴露 Admin API，连接数据库
• 数据面节点：仅负责代理流量，不连接数据库，从控制面获取最新配置

混合模式的优势：

• 显著降低数据库负载
• 安全性提升，单个数据面节点被入侵不会影响集群中其他节点
• 管理集中化，管理员只需与 CP 节点通信

5.1 生成共享密钥对

kong hybrid gen_cert

该命令会在当前目录下生成 cluster.crt 和 cluster.key 文件，用于 CP 和 DP 节点之间的 mTLS 双向认证。默认证书有效期为 3 年，可通过 --days 参数调整。

5.2 配置控制面节点

KONG_ROLE=control_plane \
KONG_CLUSTER_CERT=cluster.crt \
KONG_CLUSTER_CERT_KEY=cluster.key \
kong start

CP 节点默认监听 0.0.0.0:8005 供数据面节点连接，该端口需对所有 DP 节点可达。CP 节点仍需要数据库支持，可部署多个 CP 节点以实现高可用。

5.3 启动数据面节点

KONG_ROLE=data_plane \
KONG_CLUSTER_CONTROL_PLANE=control-plane.example.com:8005 \
KONG_CLUSTER_CERT=cluster.crt \
KONG_CLUSTER_CERT_KEY=cluster.key \
KONG_LUA_SSL_TRUSTED_CERTIFICATE=cluster.crt \
KONG_DATABASE=off \
kong start

DP 节点通过 lua_ssl_trusted_certificate 让 OpenResty 信任控制面节点的证书。DP 节点数据库设置为 off，从 CP 实时同步配置。

5.4 集群状态监控

在控制面节点上查询集群状态：

http GET :8001/clustering/status

# 返回示例
{
    "a08f5bf2-43b8-4f1c-bdf5-0a0ffb421c21": {
        "config_hash": "64d661f505f7e1de5b4c5e5faa1797dd",
        "hostname": "data-plane-2",
        "ip": "10.107.176.61",
        "last_seen": 1571197860
    }
}

5.5 容错机制

当控制面节点宕机后，数据面节点仍可正常工作。DP 会将最新配置缓存到本地磁盘，并在 CP 恢复前使用缓存配置继续处理请求，同时持续尝试重连。DP 节点重启后也能从本地缓存加载配置，正常代理流量。

5.6 插件兼容性说明

混合模式下使用声明式配置，部分插件存在兼容性差异：

完全兼容的插件：aws-lambda、azure-functions、bot-detection、cors、datadog、file-log、http-log、tcp-log、ip-restriction、prometheus、zipkin、request-transformer、response-transformer、request-termination 等。

部分兼容的插件：如果凭据为静态配置，则 acl、basic-auth、hmac-auth、jwt、key-auth 等认证插件可用，但无法动态管理凭据。限流插件的 local 和 redis 策略可用，cluster 策略不可用。

不兼容的插件：oauth2 插件需要数据库来完成令牌的生成和删除，与 db-less 模式不兼容。

6. 插件开发

Kong 提供了一套完整的插件开发套件（Plugin Development Kit，简称 PDK），开发者可以用 Lua 编写自定义插件，在请求生命周期的特定阶段注入业务逻辑。

6.1 插件文件结构

最基础的插件只需两个文件：

simple-plugin
├── handler.lua
└── schema.lua

• handler.lua：插件的核心逻辑实现，每个函数对应请求/连接生命周期的特定阶段
• schema.lua：定义插件配置的数据结构和校验规则

功能完整的插件可能包含更多模块：

complete-plugin
├── api.lua
├── daos.lua
├── handler.lua
├── migrations
│   ├── init.lua
│   └── 000_base_complete_plugin.lua
└── schema.lua

6.2 请求生命周期与回调函数

Kong 的插件系统允许在请求/响应的特定阶段注入逻辑。HTTP 模块支持以下生命周期钩子：

Stream 模块支持 init_worker()、preread()、log() 三个钩子。

6.3 插件 Handler 实现示例

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"

local CustomHandler = BasePlugin:extend()

CustomHandler.VERSION  = "1.0.0"
CustomHandler.PRIORITY = 10

function CustomHandler:new()
    CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
    CustomHandler.super.access(self)
    -- 在此编写自定义逻辑
    kong.log.inspect(config.key_names)
end

return CustomHandler

对于逻辑复杂的插件，可以将具体实现拆分到独立模块中：

local BasePlugin = require "kong.plugins.base_plugin"
local access = require "kong.plugins.my-custom-plugin.access"
local body_filter = require "kong.plugins.my-custom-plugin.body_filter"

local CustomHandler = BasePlugin:extend()

CustomHandler.VERSION  = "1.0.0"
CustomHandler.PRIORITY = 10

function CustomHandler:access(config)
    CustomHandler.super.access(self)
    access.execute(config)
end

function CustomHandler:body_filter(config)
    CustomHandler.super.body_filter(self)
    body_filter.execute(config)
end

return CustomHandler

6.4 插件执行优先级

插件之间可能存在依赖关系，Kong 通过优先级数值来保证执行顺序。优先级越高，该插件的生命周期阶段执行越早。内置插件默认优先级如下（按从高到低排列）：

自定义插件通过 CustomHandler.PRIORITY 来声明优先级。

6.5 Schema 配置定义

插件配置由 schema.lua 定义，Kong 会自动对用户输入的配置进行校验。一个典型的 Schema 定义如下：

-- schema.lua
local typedefs = require "kong.db.schema.typedefs"

return {
    name = "key-auth",
    fields = {
        { consumer = typedefs.no_consumer },
        { protocols = typedefs.protocols_http },
        {
            config = {
                type = "record",
                fields = {
                    {
                        key_names = {
                            type = "array",
                            required = true,
                            elements = typedefs.header_name,
                            default = { "apikey" },
                        },
                    },
                    {
                        hide_credentials = {
                            type = "boolean",
                            default = false,
                        },
                    },
                },
            },
        },
    },
}

可使用字段验证规则对配置做进一步约束，如 between（数值范围）、len_min（最小长度）、one_of（枚举值）、match（正则匹配）等。

6.6 数据库操作

Kong 通过 DAO（数据访问对象）模式操作数据库。核心实体可通过全局单例 kong.db 访问：

local services  = kong.db.services
local routes    = kong.db.routes
local consumers = kong.db.consumers
local plugins   = kong.db.plugins

-- 插入 Service 和 Plugin 示例
local inserted_service, err = kong.db.services:insert({
    name = "mockbin",
    url  = "http://mockbin.org",
})

local inserted_plugin, err = kong.db.plugins:insert({
    name    = "key-auth",
    service = inserted_service,
})

6.7 插件的安装与加载

方式一：使用 LuaRocks 打包安装

luarocks make                         # 本地构建
luarocks pack <plugin-name> <version>  # 打包为 .rock 文件
luarocks install <rock-filename>       # 安装

方式二：手动安装

将插件代码放到指定目录，然后在 kong.conf 中配置：

lua_package_path = /<path-to-plugin-location>/?.lua;;
plugins = bundled,<plugin-name>

也可以通过环境变量配置：

export KONG_LUA_PACKAGE_PATH="/path/to/plugins/?.lua;;"
export KONG_PLUGINS="bundled,custom-plugin"

配置完成后重启 Kong：

kong restart
# 或热重载
kong prepare && kong reload

启用 debug 日志确认插件已加载：

export KONG_LOG_LEVEL=debug
# 日志中应出现
# [debug] Loading plugin <plugin-name>

7. Kubernetes Ingress Controller

Kong Ingress Controller 将 Kong 网关的能力引入 Kubernetes 集群，由两个核心组件构成：

• Kong：核心代理组件，处理所有传入流量
• Controller：监听 Kubernetes API，将 Ingress 资源同步为 Kong 的配置

7.1 概念映射

Kubernetes 资源与 Kong 对象的映射关系：

Kong Ingress Controller 的一个关键优势是：流量直接从 Kong 到达 Pod，无需经过 kube-proxy，减少了网络跳数。

7.2 自定义资源

Kong Ingress Controller 扩展了 Kubernetes Ingress API，提供了以下自定义资源：

• KongIngress：扩展标准 Ingress，可精细控制 Route、Service、Upstream 的 Kong 属性
• KongPlugin：命名空间级别的插件资源，可关联到 Ingress、Service 或 KongConsumer
• KongClusterPlugin：集群级别的插件资源，用法与 KongPlugin 相同但作用于整个集群
• KongConsumer：直接映射为 Kong 中的 Consumer 对象
• TCPIngress：用于暴露非 HTTP/非 gRPC 的 TCP 服务

7.3 Ingress 配置示例

创建 echo-server 服务并配置 Ingress：

kubectl apply -f https://bit.ly/echo-service

kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  rules:
  - http:
      paths:
      - path: /foo
        pathType: Prefix
        backend:
          service:
            name: echo
            port:
              number: 80
EOF

为 Ingress 添加插件：

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: add-response-header
config:
  add:
    headers:
    - "demo: injected-by-kong"
plugin: response-transformer
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  annotations:
    konghq.com/plugins: add-response-header
spec:
  rules:
  - http:
      paths:
      - path: /foo
        pathType: Prefix
        backend:
          service:
            name: echo
            port:
              number: 80

配置 Consumer 与密钥：

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: harry
username: harry
credentials:
- harry-apikey

使用 Kubernetes Secret 存储密钥凭据：

kubectl create secret generic harry-apikey \
    --from-literal=kongCredType=key-auth \
    --from-literal=key=my-secret-key

7.4 部署自定义插件

在 Kong Ingress Controller 中安装自定义插件，需要将插件代码以 ConfigMap 或 Secret 的形式挂载：

kubectl create configmap kong-plugin-custom-auth \
    --from-file=./custom-auth

然后在 Helm 的 values.yaml 中配置：

plugins:
  configMaps:
  - name: kong-plugin-custom-auth
    pluginName: custom-auth

部署：

helm install kong/kong --values values.yaml

8. 总结

Kong API 网关凭借其高性能、丰富的插件生态和灵活的部署方式，已成为微服务架构中流量治理的核心组件。本文从基础安装入手，逐步深入到服务管理、认证鉴权、负载均衡、混合模式部署和插件开发等高级主题，完整覆盖了 Kong 在实际生产环境中的应用场景。

关键要点回顾：

• 使用 Docker 部署可快速搭建 Kong + Konga 的完整环境
• Service 和 Route 是最核心的抽象，灵活组合可实现复杂的路由策略
• 内置的认证、限流、缓存插件可满足大多数安全治理需求
• 混合模式（CP/DP）适合大规模集群，显著提升安全性和可管理性
• PDK 插件开发套件使得自定义业务逻辑的扩展变得标准化
• Kong Ingress Controller 将 Kong 的能力无缝融入 Kubernetes 生态