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

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

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

一、核心目标

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

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

二、具体操作步骤

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

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

执行命令（curl）：

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 等字段，示例：

{
"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，确认是否存在：

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）：

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 信息）等字段，示例：

{
"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：

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

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

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

执行测试命令：

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

预期结果：

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

{"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 或全局，此处按路由粒度配置）：

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 已绑定的插件：

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

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

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

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

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

• 响应状态码：200 OK
• 响应头包含限流信息（便于客户端感知剩余配额）：

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

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

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

• 预期响应状态码：429 Too Many Requests
• 响应体：

  {"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）：

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 代理

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

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

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

四、关键概念回顾

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