Kong学习笔记：Admin API

本文更新于2026-10-07，操作系统为Debian 12.13 (bookworm)，使用Kong Enterprise 3.13.0.1（含OpenResty 1.27.1.2）。

目录

• Admin API
  • API-key
    • 为Consumer创建API-key
  • Basic-auth
    • 为Consumer创建Basic-auth凭证
  • Cache
    • 删除所有Cache
    • 通过Key删除Cache
    • 通过Key获取Cache
  • Consumer
    • 创建Consumer
    • 删除Consumer
    • 获取Consumer
  • Information
    • 获取Kong实例的信息
    • 列出所有API端点
  • JWT
    • 为Consumer创建JWT凭证
  • Plugin
    • 列出Consumer的所有Plugin
    • 为Consumer绑定Plugin
    • 删除Consumer的Plugin
    • 获取Consumer的Plugin
    • 修改Consumer的Plugin
    • 创建或修改Consumer的Plugin
    • 列出所有Plugin
    • 创建Plugin
    • 删除Plugin
    • 获取Plugin
    • 修改Plugin
    • 创建或修改Plugin
    • 列出Route的所有Plugin
    • 为Route绑定Plugin
    • 删除Route的Plugin
    • 获取Route的Plugin
    • 修改Route的Plugin
    • 创建或修改Route的Plugin
    • 列出Service的所有Plugin
    • 为Service绑定Plugin
    • 删除Service的Plugin
    • 获取Service的Plugin
    • 修改Service的Plugin
    • 创建或修改Service的Plugin
  • Route
    • 列出所有Route
    • 删除Route
    • 获取Route
    • 修改Route
    • 创建或修改Route
    • 列出Service的所有Route
    • 为Service创建Route
    • 删除Service的Route
    • 获取Service的Route
    • 修改Service的Route
    • 创建或修改Service的Route
  • Schema
    • 校验实体模式
  • Service
    • 列出所有Service
    • 创建Service
    • 删除Service
    • 获取Service
    • 修改Service
    • 创建或修改Service
  • Target
    • 列出Upstream的所有Target
    • 为Upstream绑定Target
    • 从Upstream删除Target
  • Upstream
    • 列出所有Upstream
    • 创建Upstream
    • 删除Upstream
    • 获取Upstream
    • 修改Upstream
    • 创建或修改Upstream
  • 其它
    • 查看监控数据
• 示例
  • 反向代理
  • Basic-auth鉴权
  • JWT鉴权
  • 限流
  • Kong API回路（Loopback）
• 常见错误

官方文档：https://developer.konghq.com/api/gateway/admin-ee/3.14/

Admin API

请求体可使用以下格式：

• application/json。如：

  curl -X POST http://localhost:8001/services/SERVICE/routes \
  --header 'Content-Type: application/json' \
  --data \
  '{
  	"name": "ROUTE",
  	"paths": ["/PATH", "/TEMP"]
  }'
  

• application/x-www-form/urlencoded。使用“.”连接嵌套的对象。数组需要在属性后添加方括号，括号内的数字可以填充，但一旦填充，必需从1开始，之后的索引也需保持连续。如：

  curl -X POST http://localhost:8001/services/SERVICE/routes \
  --data 'name=ROUTE' \
  --data 'paths[]=/PATH' \
  --data 'paths[]=/TEMP'
  

• multipart/form-data。使用“.”连接嵌套的对象。数组必需添加索引。如：

  curl -X POST http://localhost:8001/services/SERVICE/routes \
  -F 'name=ROUTE' \
  -F 'paths[1]=/PATH' \
  -F 'paths[2]=/TEMP'
  

API-key

为Consumer创建API-key

curl -X POST http://localhost:8001/consumers/CONSUMER/key-auth

响应字段有：

• key：API密钥。作为客户端请求URL的查询字符串参数发送请求。

Basic-auth

为Consumer创建Basic-auth凭证

curl -X POST http://localhost:8001/consumers/CONSUMER/basic-auth \
--header 'Content-Type: application/json' \
--data \
'{
	"username": "USERNAME",
	"password": "PASSWORD"
}'

Cache

删除所有Cache

curl -X DELETE http://localhost:8001/cache

通过Key删除Cache

curl -X DELETE http://localhost:8001/cache/KEY

通过Key获取Cache

curl http://localhost:8001/cache/KEY

Consumer

创建Consumer

curl -X POST http://localhost:8001/consumers \
--header 'Content-Type: application/json' \
--data \
'{
	"username": "CONSUMER",
	"custom_id": "CUSTOMID"
}'

删除Consumer

curl -X DELETE http://localhost:8001/consumers/CONSUMER

获取Consumer

curl http://localhost:8001/consumers/CONSUMER

Information

获取Kong实例的信息

curl http://localhost:8001/

列出所有API端点

curl http://localhost:8001/endpoints

JWT

为Consumer创建JWT凭证

curl -X POST http://localhost:8001/consumers/CONSUMER/jwt

响应字段有：

• key
• secret

Plugin

列出Consumer的所有Plugin

curl http://localhost:8001/consumers/CONSUMER/plugins

为Consumer绑定Plugin

curl -X POST http://localhost:8001/consumers/CONSUMER/plugins \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "PLUGIN",
	"config": {
		"KEY": "VALUE"
	}
}'

删除Consumer的Plugin

curl -X DELETE http://localhost:8001/consumers/CONSUMER/plugins/PLUGINID

获取Consumer的Plugin

curl http://localhost:8001/consumers/CONSUMER/plugins/PLUGINID

修改Consumer的Plugin

curl -X PATCH http://localhost:8001/consumers/CONSUMER/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

创建或修改Consumer的Plugin

curl -X PUT http://localhost:8001/consumers/CONSUMER/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

列出所有Plugin

curl http://localhost:8001/plugins

创建Plugin

curl -X POST http://localhost:8001/plugins \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "PLUGIN",
	"config": {
		"KEY": "VALUE"
	}
}'

删除Plugin

curl -X DELETE http://localhost:8001/plugins/PLUGINID

获取Plugin

curl http://localhost:8001/plugins/PLUGINID

修改Plugin

curl -X PATCH http://localhost:8001/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

创建或修改Plugin

curl -X PUT http://localhost:8001/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

列出Route的所有Plugin

curl http://localhost:8001/routes/ROUTE/plugins

为Route绑定Plugin

curl -X POST http://localhost:8001/routes/ROUTE/plugins \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "PLUGIN",
	"config": {
		"KEY": "VALUE"
	}
}'

删除Route的Plugin

curl -X DELETE http://localhost:8001/routes/ROUTE/plugins/PLUGINID

获取Route的Plugin

curl http://localhost:8001/routes/ROUTE/plugins/PLUGINID

修改Route的Plugin

curl -X PATCH http://localhost:8001/routes/ROUTE/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

创建或修改Route的Plugin

curl -X PUT http://localhost:8001/routes/ROUTE/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

列出Service的所有Plugin

curl http://localhost:8001/services/SERVICE/plugins

为Service绑定Plugin

curl -X POST http://localhost:8001/services/SERVICE/plugins \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "PLUGIN",
	"config": {
		"KEY": "VALUE"
	}
}'

删除Service的Plugin

curl -X DELETE http://localhost:8001/services/SERVICE/plugins/PLUGINID

获取Service的Plugin

curl http://localhost:8001/services/SERVICE/plugins/PLUGINID

修改Service的Plugin

curl -X PATCH http://localhost:8001/services/SERVICE/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

创建或修改Service的Plugin

curl -X PUT http://localhost:8001/services/SERVICE/plugins/PLUGINID \
--header 'Content-Type: application/json' \
--data \
'{
	"enabled": false,
	"config": {
		"KEY": "VALUE"
	}
}'

Route

列出所有Route

curl http://localhost:8001/routes

删除Route

curl -X DELETE http://localhost:8001/routes/ROUTE

获取Route

curl http://localhost:8001/routes/ROUTE

修改Route

curl -X PATCH http://localhost:8001/routes/ROUTE \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "ROUTE",
	"paths": ["/PATH"]
}'

创建或修改Route

curl -X PUT http://localhost:8001/routes/ROUTE \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "ROUTE",
	"paths": ["/PATH"]
}'

列出Service的所有Route

curl http://localhost:8001/services/SERVICE/routes

为Service创建Route

curl -X POST http://localhost:8001/services/SERVICE/routes \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "ROUTE",
	"paths": ["/PATH"]
}'

删除Service的Route

curl -X DELETE http://localhost:8001/services/SERVICE/routes/ROUTE

获取Service的Route

curl http://localhost:8001/services/SERVICE/routes/ROUTE

修改Service的Route

curl -X PATCH http://localhost:8001/services/SERVICE/routes/ROUTE \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "ROUTE",
	"paths": ["/PATH"]
}'

创建或修改Service的Route

curl -X PUT http://localhost:8001/services/SERVICE/routes/ROUTE \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "ROUTE",
	"paths": ["/PATH"]
}'

Schema

校验实体模式

curl -X POST http://localhost:8001/schemas/ENTITYNAME/validate \
--header 'Content-Type: application/json' \
--data \
'{
}'

Service

列出所有Service

curl http://localhost:8001/services

创建Service

curl -X POST http://localhost:8001/services \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "SERVICE",
	"host": "UPSTREAM"
}'

删除Service

curl -X DELETE http://localhost:8001/services/SERVICE

获取Service

curl http://localhost:8001/services/SERVICE

修改Service

curl -X PATCH http://localhost:8001/services/SERVICE \
--header 'Content-Type: application/json' \
--data \
'{
	"host": "UPSTREAM"
}'

创建或修改Service

curl -X PUT http://localhost:8001/services/SERVICE \
--header 'Content-Type: application/json' \
--data \
'{
	"host": "UPSTREAM"
}'

Target

列出Upstream的所有Target

curl http://localhost:8001/upstreams/UPSTREAM/targets

为Upstream绑定Target

curl -X POST http://localhost:8001/upstreams/UPSTREAM/targets \
--header 'Content-Type: application/json' \
--data \
'{
	"target": "www.baidu.com:80",
	"weight": 100
}'

从Upstream删除Target

curl -X DELETE http://localhost:8001/upstreams/UPSTREAM/targets/TARGET

Upstream

列出所有Upstream

curl http://localhost:8001/upstreams?size=10

创建Upstream

curl -X POST http://localhost:8001/upstreams \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "UPSTREAM"
}'

删除Upstream

curl -X DELETE http://localhost:8001/upstreams/UPSTREAM

获取Upstream

curl http://localhost:8001/upstreams/UPSTREAM

修改Upstream

curl -X PATCH http://localhost:8001/upstreams/UPSTREAM \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "UPSTREAM"
}'

创建或修改Upstream

curl -X PUT http://localhost:8001/upstreams/UPSTREAM \
--header 'Content-Type: application/json' \
--data \
'{
	"name": "UPSTREAM"
}'

其它

查看监控数据

curl http://localhost:8001/metrics

示例

反向代理

1. 创建Upstream

   curl -X POST http://localhost:8001/upstreams \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "UPSTREAM"
   }'
   

2. 为Upstream绑定Target

   curl -X POST http://localhost:8001/upstreams/UPSTREAM/targets \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"target": "www.baidu.com:80",
   	"weight": 100
   }'
   

3. 创建Service

   curl -X POST http://localhost:8001/services \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "SERVICE",
   	"host": "UPSTREAM"
   }'
   

4. 创建Route

   curl -X POST http://localhost:8001/services/SERVICE/routes \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "ROUTE",
   	"paths": ["/PATH"]
   }'
   

5. 访问验证

   curl http://localhost:8000/PATH
   

Basic-auth鉴权

1. 为Service绑定Plugin

   curl -X POST http://localhost:8001/services/SERVICE/plugins \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "basic-auth",
   	"config": {
   		"hide_credentials": true
   	}
   }'
   

2. 创建Consumer

   curl -X POST http://localhost:8001/consumers \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"username": "CONSUMER",
   	"custom_id": "CUSTOMID"
   }'
   

3. 为Consumer创建Basic-auth凭证

   curl -X POST http://localhost:8001/consumers/CONSUMER/basic-auth \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"username": "USERNAME",
   	"password": "PASSWORD"
   }'
   

4. 计算鉴权头的值

   echo "USERNAME:PASSWORD" | base64
   

5. 访问验证

   curl http://localhost:8000/PATH \
   -H 'Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQK'
   

JWT鉴权

1. 为Service绑定Plugin

   curl -X POST http://localhost:8001/services/SERVICE/plugins \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "jwt"
   }'
   

2. 创建Consumer

   curl -X POST http://localhost:8001/consumers \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"username": "CONSUMER",
   	"custom_id": "CUSTOMID"
   }'
   

3. 为Consumer创建JWT凭证

   curl -X POST http://localhost:8001/consumers/CONSUMER/jwt
   

4. 计算Token的值

   在https://www.jwt.io/中使用JWT Encoder填写以下信息，生成Token：

   Header：

   {
     "alg": "HS256",
     "typ": "JWT"
   }
   

   Payload（iss为key的值）：

   {
     "iss": "X83Te6Zvz7RjevEcpcZXGO5gwSXzrGgN"
   }
   

   Sign JWT（为secret的值）：

   S6WfEaoNYaKZ2z1HPffKxcC6mhfhnJcT
   

5. 访问验证

   curl http://localhost:8000/PATH?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJYODNUZTZadno3UmpldkVjcGNaWEdPNWd3U1h6ckdnTiJ9.-Exb3k6ED4SAvujYzJSOhCWV8ovdgXUlHCocsjbCHEU
   

限流

1. 为Service绑定Plugin

   curl -X POST http://localhost:8001/services/SERVICE/plugins \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "rate-limiting",
   	"config": {
   		"minute": 3,
   		"policy": "local"
   	}
   }'
   

2. 访问验证

   curl http://localhost:8000/PATH -i
   

Kong API回路（Loopback）

1. 创建Service

   curl -X POST http://localhost:8001/services \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "SERVICE",
   	"url": "http://localhost:8001"
   }'
   

2. 创建Route

   curl -X POST http://localhost:8001/services/SERVICE/routes \
   --header 'Content-Type: application/json' \
   --data \
   '{
   	"name": "ROUTE",
   	"paths": ["/PATH"]
   }'
   

3. 访问验证

   curl http://localhost:8000/PATH/services
   

常见错误

以下为返回message字段的常见错误：

• an invalid response was received from the upstream server：后端服务宕机。
• failure to get a peer from the ring-balancer：漏配Target。
• no Route matched with those values：路由不匹配。
• Unauthorized：鉴权插件失败。