Kong网关部署与核心配置实践指南

1. 安装 Kong

2. Kong 核心概念

Kong 的核心模型围绕“上游-服务-路由-消费者”四层结构构建，实现请求从网关到后端服务的精准转发与管控。先明确各组件的定义与作用：

• 创建服务后，覆盖全局的路由-创建Route-将path置为空值 = 代理全部Server端点，这与Nginx无异。
• 创建服务后，补全某一个特定的path路径 = 仅针对于某个服务的路径生效，但是请注意，如果未定义的路由，则无法通过8000端口代理,否则就是如下反馈

  1 2 3

  { "message":"An invalid response was received from the upstream server" }

2.1 整体框架如下

说明：8000 为 HTTP 流量代理端口（客户端访问入口），8001 为 HTTP 管理端口（网关配置入口）

2.1 上游（UPSTREAM）

上游是后端服务集群的逻辑分组，包含一组“服务实例”（Kong 中称为 Target），内置负载均衡、健康检查、超时控制等管理策略。

• 核心作用：隔离网关与具体服务实例，网关无需关心单个服务的 IP/端口变化，仅通过上游统一调度请求。
• 类比理解：上游 = “服务集群名称”（如“用户服务集群”），Target = 集群内具体服务器（如 192.168.1.100:8080）。
• 核心价值：通过内置策略解决后端服务的负载均衡、高可用、动态扩展问题，无需侵入业务代码。

2.2 服务（Service）

服务是 Kong 对后端 API/微服务的抽象定义，用于指定后端服务的访问地址（如 http://192.168.87.177:8080），是网关转发请求的“目标地址”。

• 核心作用：关联上游集群与路由规则。一个服务可对应一个上游（集群场景），也可直接指向单个服务实例（简单场景）。

2.3 路由（Route）

路由是请求匹配规则，定义“什么样的请求会转发到对应的服务”，支持通过路径、主机名、HTTP 方法等维度匹配。

• 核心作用：实现“一服务多路由”。例如将 /user/login 和 /user/info 两个路径，均映射到“用户服务”。

2.4 消费者（Consumer）

消费者是使用 API 的客户端实体标识，可代表用户、应用程序、第三方系统等，是精细化 API 治理（认证、限流、授权）的基础。

• 核心作用：
  1. 绑定客户端身份，通过 custom_id 字段关联业务系统用户；
  2. 记录单个客户端的 API 使用情况（调用次数、响应时间），用于计费或监控；
  3. 对特定客户端执行差异化管控（如 VIP 用户更高限流额度）。

2.5 Kong 配置流程与管理端口

2.5.1 核心配置流程

所有 API 接入 Kong 需遵循以下三步（集群场景必走，单实例场景可省略“上游”）：

1. 定义上游（集群场景：管理后端服务实例集合）；
2. 创建服务（关联上游或直接指向后端服务地址）；
3. 为服务添加路由（配置请求匹配规则）。

2.5.2 管理端口说明

Kong 通过 8001/8444 端口暴露管理 API，所有配置操作（创建服务、路由、插件）均通过这些端口完成。各端口功能如下表：

3. 插件的三种启用方式

Kong 插件支持在“服务-路由-消费者”三个层级启用，核心区别在于作用范围与管控粒度，需根据业务场景选择。

3.1 三种启用方式核心差异

3.2 选择建议

1. 需对服务所有接口统一管控（如全局限流、日志采集）→ 服务级插件；
2. 需对单个接口特殊处理（如支付接口签名验证、敏感接口权限控制）→ 路由级插件；
3. 需按客户端身份差异化管控（如 VIP 用户更高限流额度、特定客户端白名单）→ 消费者级插件。

实际场景中可多层结合，例如“服务全局限流 + 路由支付验证 + 消费者 VIP 额度”，实现精细化流量管理。

4. 后端服务准备（ThinkPHP8）

本次实践以 8080 端口运行的 ThinkPHP8 实例为后端服务，用于验证 Kong 代理与插件功能。操作步骤如下：

1. 启动后端服务：确保 ThinkPHP8 服务正常运行在 8080 端口，示例状态如下图：
   
   说明：后端服务需能被 Kong 所在服务器访问（同网段或打通网络）

2. 直连测试：直接访问 http://[后端服务IP]:8080，确认服务正常响应，示例结果如下图：
   
   说明：直连成功后，再通过 Kong 代理访问，避免后端服务本身故障影响测试

5. 核心配置实践（服务-路由-消费者）

5.1 创建消费者（Consumer）

消费者分“普通消费者”和“匿名消费者”：

• 普通消费者：绑定具体客户端身份（如用户、应用）；
• 匿名消费者：用于未携带认证信息的请求（如公开接口临时访问）。

5.1.1 创建普通消费者

关键特性：消费者的认证凭据有效性与插件创建时间无关。即使先创建消费者并绑定凭据，后续为服务/路由添加认证插件后，该凭据仍可正常通过认证。

方式1：图形化界面（Konga）

1. 进入 Konga 控制台 → 左侧菜单 Consumers → 点击 Add Consumer；
2. 填写核心参数：
   • username：Kong 内唯一标识（如 basic-user）；
   • custom_id：业务系统用户唯一标识（如用户 ID、哈希值）；
3. 点击提交，示例配置如下图：
   

方式2：API 端点（curl 命令）

1
2
3
4

curl -i -X POST \
  --url http://[KongIP]:8001/consumers/ \
  --data "username=basic-user" \  # Kong 内唯一的消费者名称
  --data "custom_id=basic-01"     # 关联业务系统用户的唯一标识（如用户ID）

创建成功响应示例：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "success": true,
  "code": 201,
  "message": "消费者创建成功",
  "data": {
    "tags": null,
    "username": "basic-user",
    "id": "6d37ad78-aafd-464b-98bf-849b0f306d6d",  # Kong 消费者唯一 UUID
    "custom_id": "basic-01",                        # 业务系统关联 ID
    "created_at": 1761361971                       # 创建时间戳（Unix 秒）
  }
}

5.2 创建服务（Service）

核心作用：关联后端 ThinkPHP8 服务，告诉 Kong “请求要转发到哪里”。

图形化界面配置（Konga）

1. 进入 Konga 控制台 → 左侧菜单 Services → 点击 Add Service；
2. 填写核心参数（以 ThinkPHP8 为例）：
   • Name：服务名称（Kong 内唯一，如 tp8-service）；
   • Protocol：后端服务协议（如 http）；
   • Host：后端服务 IP（如 192.168.87.177）；
   • Port：后端服务端口（如 8080）；
   • Path：默认请求路径（可选，如 /，即根路径）；
3. 点击提交，示例配置如下图：
   

5.3 创建路由（Route）

核心作用：配置请求匹配规则，告诉 Kong “什么样的请求要转发到 tp8-service”。

图形化界面配置（Konga）

1. 进入 Konga 控制台 → 左侧菜单 Routes → 点击 Add Route；
2. 先关联服务：在「Service」下拉框中选择已创建的 tp8-service；
3. 填写核心匹配规则：
   • Name：路由名称（如 tp8-route）；
   • Paths：匹配路径（如 /tp8，即访问 KongIP:8000/tp8 时触发）；
   • Methods：允许的 HTTP 方法（勾选 GET、POST 等）；
   • Protocols：支持的协议（勾选 http）；
4. 点击提交，示例配置如下图：
   

代理测试

配置完成后，访问 http://[KongIP]:8000/tp8，Kong 会自动转发到后端 192.168.87.177:8080。测试成功示例如下图：

1
2
3

curl -X POST http://[KongIP]:8001/consumers/basic-user/basic-auth \
  --data "username=2022471677@qq.com" \  # Basic Auth 用户名
  --data "password=202019"      # Basic Auth 密码

1
2
3
4

curl -X POST http://127.0.0.1:8001/routes/TP8_Route/plugins \
  --data "name=rate-limiting" \
  --data "config.second=5" \
  --data "config.hour=10000"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

{
    "id": "a1a63cad-e827-4eaf-aadb-b1d5c89bf5c0",
    "consumer": null,
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ],
    "route": {
        "id": "7c5ed32d-0d89-47c5-9435-891fec7077b0"
    },
    "tags": null,
    "enabled": true,
    "name": "rate-limiting",
    "updated_at": 1760067842,
    "created_at": 1760067842,
    "instance_name": null,
    "service": null,
    "config": {
        "month": null,
        "year": null,
        "fault_tolerant": true,
        "hide_client_headers": false,
        "redis_ssl": false,
        "redis_ssl_verify": false,
        "header_name": null,
        "error_message": "API rate limit exceeded",
        "sync_rate": -1,
        "redis": {
            "password": null,
            "ssl": false,
            "ssl_verify": false,
            "server_name": null,
            "username": null,
            "database": 0,
            "port": 6379,
            "host": null,
            "timeout": 2000
        },
        "redis_database": 0,
        "redis_timeout": 2000,
        "redis_host": null,
        "policy": "local",
        "redis_username": null,
        "redis_password": null,
        "limit_by": "consumer",
        "redis_port": 6379,
        "redis_server_name": null,
        "error_code": 429,
        "path": null,
        "second": 5,
        "minute": null,
        "hour": 10000,
        "day": null
    }
}