Kong Gateway 实操实例：代理上游服务并配置限流插件

假设已满足以下前置条件：

Kong Gateway 已部署完成（以开源版为例），默认监听：
- Admin API 端口：8001（用于配置管理）
- 代理流量端口：8000（HTTP 流量）/ 8443（HTTPS 流量）
准备一个上游服务 （如本地启动的简单 HTTP 服务，地址：http://192.168.1.100:3000，提供 /api/hello 接口，返回 {"message":"Hello from upstream"}）
工具：curl（命令行）或 Postman（可视化），用于调用 Kong API 和测试代理效果

一、核心目标

通过 Kong 实现两个核心能力：

流量代理 ：让客户端请求通过 Kong 网关（http://kong-ip:8000）转发到上游服务（http://192.168.1.100:3000）
插件限流 ：为该代理路径配置 rate-limiting 插件，限制单客户端每分钟最多请求 10 次（防止上游服务过载）

二、具体操作步骤

步骤 1：创建 Kong「Service」（关联上游服务）

Kong 中的「Service」是对上游服务的抽象，用于定义"要代理到哪个后端服务"。通过调用 Kong Admin API 创建 Service：

执行命令（curl）：

bash 复制代码

curl -X POST http://kong-ip:8001/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-upstream-service",  # Service 名称（自定义，唯一）
    "url": "http://192.168.1.100:3000"  # 上游服务的实际地址
  }'

预期响应（成功时）：

返回 Service 的详细配置，包含 id（UUID）、name、url 等字段，示例：

json 复制代码

{
  "id": "5f8d2a9e-7d3b-4c1a-8e9f-1234567890ab",
  "name": "my-upstream-service",
  "url": "http://192.168.1.100:3000",
  "protocol": "http",
  "host": "192.168.1.100",
  "port": 3000,
  "created_at": 1718000000
}

验证配置：

查询已创建的 Service，确认是否存在：

bash 复制代码

curl http://kong-ip:8001/services/my-upstream-service

步骤 2：创建 Kong「Route」（定义请求匹配规则）

Kong 中的「Route」是请求入口规则，用于定义"哪些客户端请求会被转发到指定的 Service"（如通过路径、域名、HTTP 方法匹配）。

我们希望：客户端访问 http://kong-ip:8000/my-api/* 时，转发到上游服务的 /* 路径（即 http://192.168.1.100:3000/*）。

执行命令（curl）：

bash 复制代码

curl -X POST http://kong-ip:8001/services/my-upstream-service/routes \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api-route",  # Route 名称（自定义，唯一）
    "paths": ["/my-api"],     # 匹配的客户端请求路径（前缀匹配，/my-api/xxx 均会命中）
    "methods": ["GET", "POST"],  # 允许的 HTTP 方法（可选，默认所有方法）
    "protocols": ["http"]     # 支持的协议（http/https，默认两者）
  }'

预期响应（成功时）：

返回 Route 的配置，包含 id、paths、service（关联的 Service 信息）等字段，示例：

json 复制代码

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "name": "my-api-route",
  "paths": ["/my-api"],
  "methods": ["GET", "POST"],
  "protocols": ["http"],
  "service": {
    "id": "5f8d2a9e-7d3b-4c1a-8e9f-1234567890ab",
    "name": "my-upstream-service"
  },
  "created_at": 1718000100
}

验证配置：

查询已创建的 Route：

bash 复制代码

curl http://kong-ip:8001/routes/my-api-route

步骤 3：测试基础代理功能（无插件）

此时 Kong 已配置好"Route → Service → 上游服务"的转发链路，测试客户端请求是否能通过 Kong 代理到上游服务：

执行测试命令：

bash 复制代码

# 客户端请求 Kong 网关的 /my-api/hello 路径
curl http://kong-ip:8000/my-api/hello

预期结果：

Kong 会将请求转发到上游服务的 http://192.168.1.100:3000/hello，返回上游服务的响应：

json 复制代码

{"message":"Hello from upstream"}

若失败：检查 Kong 与上游服务的网络连通性（如防火墙、上游服务是否正常启动），或 Route/Service 的配置是否正确。

步骤 4：为 Route 配置「rate-limiting」插件（限流）

Kong 自带 rate-limiting 插件，可基于"客户端 IP""用户 ID"等维度限制请求频率。此处配置：基于客户端 IP，每分钟最多允许 10 次请求 ，超过则返回 429 Too Many Requests。

执行命令（curl）：

为 my-api-route 路由绑定插件（也可绑定到 Service 或全局，此处按路由粒度配置）：

bash 复制代码

curl -X POST http://kong-ip:8001/routes/my-api-route/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rate-limiting",  # 插件名称（Kong 自带，固定）
    "config": {
      "minute": 10,           # 每分钟最大请求数
      "policy": "ip",         # 限流维度（ip：基于客户端 IP；还支持 consumer 等）
      "limit_by": "ip",
      "fault_tolerant": true  # 若插件内部出错，是否允许请求继续（建议开启）
    }
  }'

预期响应（成功时）：

返回插件的配置信息，包含 id、name、route（关联的 Route 信息）、config（限流参数）等字段。

验证插件配置：

查询该 Route 已绑定的插件：

bash 复制代码

curl http://kong-ip:8001/routes/my-api-route/plugins

步骤 5：测试限流插件效果

连续发送请求，验证超过 10 次后是否触发限流：

1. 前 10 次请求（正常）：

bash 复制代码

curl -i http://kong-ip:8000/my-api/hello  # 加 -i 显示响应头

响应状态码：200 OK

响应头包含限流信息（便于客户端感知剩余配额）：

复制代码

X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9  # 每次请求后递减

2. 第 11 次请求（触发限流）：

bash 复制代码

curl -i http://kong-ip:8000/my-api/hello

预期响应状态码：429 Too Many Requests
响应体：
json 复制代码
```
{"message":"API rate limit exceeded"}
```

响应头：

复制代码

X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 0
Retry-After: 45  # 建议多少秒后重试（基于当前剩余时间）

三、常见扩展操作

1. 查看所有配置（全局视角）

查看所有 Service：curl http://kong-ip:8001/services
查看所有 Route：curl http://kong-ip:8001/routes
查看所有插件：curl http://kong-ip:8001/plugins

2. 修改配置（如调整限流阈值）

通过插件 ID 修改限流参数（先通过 GET /plugins 获取插件 ID）：

bash 复制代码

curl -X PATCH http://kong-ip:8001/plugins/插件ID \
  -H "Content-Type: application/json" \
  -d '{"config": {"minute": 20}}'  # 改为每分钟 20 次

3. 删除配置（清理资源）

删除 Route：curl -X DELETE http://kong-ip:8001/routes/my-api-route
删除 Service：curl -X DELETE http://kong-ip:8001/services/my-upstream-service
删除插件：curl -X DELETE http://kong-ip:8001/plugins/插件ID

4. 配置 HTTPS 代理

通过 certificates API 上传 SSL 证书（公钥 + 私钥）：

bash 复制代码

curl -X POST http://kong-ip:8001/certificates \
  -F "cert=@{本地公钥文件路径}.pem" \
  -F "key=@{本地私钥文件路径}.key" \
  -F "snis=api.example.com"  # 绑定的域名

修改 Route 的 protocols 为 ["https"]，后续通过 https://kong-ip:8443/my-api/hello 访问。

四、关键概念回顾

组件	作用
Service	抽象上游服务，定义"代理目标"（如后端 API 地址）
Route	定义"请求匹配规则"（如路径、域名），将请求路由到对应的 Service
Plugin	附加功能（如限流、认证、日志），可绑定到 Route/Service/全局，实现功能扩展
Admin API	Kong 的配置入口，用于创建/修改/删除所有资源（生产环境需做好权限控制）