Kong Api Gateway

什么是API 网关

在微服务的架构中，一个应用可能背拆分许多个小的服务系统，这些小系统可能自成一体，有自己的硬件资源、数据库、框架，甚至连语言都各不相同，这些小系统通常以Restfull API风格的借口提供给前端或者其他系统调用，一个应用可能会被拆分上百上千个API，管理起来极其不变，这个时候出现了API网关，API网关提供了一个统一的入口，将流量转发给对应的后端取得数据后再一次返回，并且在次基础上提供各种认证鉴权流控等等功能让后端专心于自己的业务。

使用API 网关带来以下几个好处：

• 统一API入口
• 隔离后端
• 认证鉴权流控
• 负载均衡
• 降低后端开发对API安全性的考虑

其实无论是否是微服务的架构，只要用到了认证鉴权流控功能，我觉得都应该使用API网关，这将大大减低后端开发的成本和速度，未来扩展也方便。

下面是开源的几种方案：

名称	说明
Tyk	Tyk是一个开放源码的API网关，它是快速、可扩展和现代的。Tyk提供了一个API管理平台，其中包括API网关、API分析、开发人员门户和API管理面板。Try 是一个基于Go实现的网关服务。
Kong	Kong是一个可扩展的开放源码API Layer(也称为API网关或API中间件)。Kong 在任何RESTful API的前面运行，通过插件扩展，它提供了超越核心平台的额外功能和服务。
Orange	Orange和Kong类似也是基于OpenResty的一个API网关程序，是由国人开发的。
Zuul	Zuul是一种提供动态路由、监视、弹性、安全性等功能的边缘服务。Zuul是Netflix出品的一个基于JVM路由和服务端的负载均衡器。
apiaxle	Nodejs 实现的一个 API 网关。
api-umbrella	Ruby 实现的一个 API 网关。

在以上的产品中，还是比较推荐是用kong的，kong基于nginx，使用了lua语言，这将大大提供了性能和稳定性。

为什么是 Kong

Kong 的插件机制是其高可扩展性的根源，Kong 可以很方便地为路由和服务提供各种插件，网关所需要的基本特性，Kong 都如数支持：

• Cloud-Native 云原生: 与平台无关，Kong可以从裸机运行到Kubernetes。
• Dynamic Load Balancing 动态路由：Kong 的背后是 OpenResty+Lua，所以从 OpenResty 继承了动态路由的特性。
• Circuit-Breaker 熔断。
• Health Checks 健康检查。
• Logging 日志: 可以记录通过 Kong 的 HTTP，TCP，UDP 请求和响应。
• Security 鉴权: 权限控制，IP 黑白名单，同样是 OpenResty 的特性。
• SSL: Setup a Specific SSL Certificate for an underlying service or API.
• 监控: Kong 提供了实时监控插件。
• 认证: 如数支持 HMAC, JWT, Basic, OAuth2.0 等常用协议。
• Rate-limiting限流：Block and throttle requests based on many variables.
• REST API: 通过 Rest API 进行配置管理，从繁琐的配置文件中解放。
• 可用性: 天然支持分布式。
• 高性能: 背靠非阻塞通信的 nginx，性能自不用说。
• Plugins 插件机制: 提供众多开箱即用的插件，且有易于扩展的自定义插件接口，可以使用 Lua或者go等自行开发插件。

上面这些特性中，反复提及了 Kong 背后的 OpenResty，实际上，使用 Kong 之后，Nginx 可以完全摒弃，Kong 的功能是 Nginx 的父集。

安装Kong

Kong支持PostgreSQL 9.5+ 和Cassandra 3.xx 作为其数据存储。所以在暗转Kong之前我们需要先安装配置好数据库，并且给Kong创建好数据库和用户名等等。

Kong提供了丰富的安装方式，你可以基于docker来安装kong，也可以使用包管理器来安装它，当然也可以通过源码编译安装。

通过包管理器来安装

yum install https://download.konghq.com/gateway-3.x-rhel-8/Packages/k/kong-enterprise-edition-3.1.1.1.rhel8.amd64.rpm

检查一下都安装到哪个目录了。

[root@Kong ~]# whereis kong
kong: /etc/kong /usr/local/bin/kong /usr/local/kong

如上，/ect/kong目录为配置文件目录，安装后会有一个官方的默认配置文件kong.conf.default 复制这个文件为kong.conf即可启动Kong.

/usr/local/kong为Kong的运行目录，Kong启动后会生成nginx的配置文件放在此目录，当然缓存文件也会存放在这个目录中。

Kong的配置文件中，如果没有启用某一项目配置，那么Kong会使用其默认的配置文件.

Kong基于openresty，所以通过包管理器来安装也会安装openresty，安装目录为/usr/local/openresty/

基本上我们不需要去修改这个目录，如果需要修改nginx的配置，我们可以通过Kong的配置文件注入nginx配置，Kong在启动的时候会生成nginx的配置文件。

启动Kong

Kong提供了CLI以此来控制Kong的启动停止等等的操作，我们可以通过kong --help命令来查看CLI提供了哪些功能，如下：

[root@Kong ~]# kong --help
No such command: --help
 
Usage: kong COMMAND [OPTIONS]
 
The available commands are:
 check
 health
 migrations
 prepare
 quit
 reload
 restart
 roar
 start
 stop
 version
 
Options:
 --v              verbose
 --vv             debug

对应的参数功能如下：

参数	功能
check	检查配置文件
health	检查节点的健康状态
migrations	迁移数据库，再第一次配置Kong时候必须要运行此命令，用来初始化数据库… 数据库的信息保存再配置文件中，所以使用此命令需要通过-c指定配置文件，在migrations参数中，还可以跟上list、up、reset的参数，其中，list是显示当前迁移的信息，up参数查询缺少的部分，并且修复、reset的重置所有的迁移
prepare	在配置的前缀目录中准备Kong前缀。这个命令可以用于从nginx二进制文件启动Kong而不使用’kong start’
quit	优雅的停止Kong，在退出之前会先处理完已经接受到的请求
reload	重载配置文件
restart	重启Kong
start	启动kong，通过 -c 来指定配置文件
stop	停止运行kong
version	查看版本
–v	以上任意参数都可以加张-v选项，此选项会打印出信息。
–vv	以上任意参数都可以加张-v选项，此选项会打印出更为丰富的debug信息。

现在，来启动Kong，因为是第一次启动，所以需要先运行迁移命令，以初始化数据库。

[root@Kong ~]$ kong migrations list -v
....

迁移成功之后可以使用kong start来启动Kong

 kong start --vv
 ....

指定了–vv之后会打印出启动的debug信息，启动成功之后会自动再后台以daemon的方式运行。

启动之后我们看一下Kong默认监听了那些端口

[root@Kong ~]# netstat -ntlp
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 0.0.0.0:8443            0.0.0.0:*               LISTEN      2369/nginx: master  
tcp        0      0 127.0.0.1:8444          0.0.0.0:*               LISTEN      2369/nginx: master  
tcp        0      0 0.0.0.0:8000            0.0.0.0:*               LISTEN      2369/nginx: master  
tcp        0      0 127.0.0.1:8001          0.0.0.0:*               LISTEN      2369/nginx: master  

Kong 默认监听了4个端口，分别是：

• 8000：API网关http代理端口
• 8443：API网关https代理端口
• 8001：Kong管理API的http端口
• 8444：Kong管理API的https端口

再观察一下，启动的进程名称均为nginx。

Kong的默认运行目录在/usr/local/kong。其中，里面的nginx.conf 和 nginx-kong.conf 就是Kong在启动的时候自动生成的nginx配置文件啦。

配置文件详解

Kong配置文件是Kong服务的核心文件，它配置了Kong以怎么的方式运行，并且依赖于这个配置生成Nginx的配置文件，本文通过解读Kong配置文件，以了解Kong的运行和配置。

在成功安装Kong以后，会有一个名为kong.conf.default默认的配置文件示例,如果是通过包管理器安装的，通常位于/etc/kong/kong.conf.default，我们要将其复制为kong.conf以便于我们修改使用他。

在Kong的配置文件中，约定了以下的几条规则：

• 配置文件中以#开头的行均为注释行，程序不会读取这些内容。
• 在官方提供的默认配置文件中，以#开头的有值的配置项目均为默认配置。
• 所有的配置项，均可以在系统环境变量中配置，但是必须要加上KONG_为前缀。
• 值为布尔型的配置，可以使用on/off或者true/false。
• 值为列表的，必须使用半角逗号分割。

Kong的配置，大概分为几种，分别是：

• 常规配置：配置服务运行目录，插件加载，日志等等
• NGINX配置：配置Nginx注入，例如监听IP和端口配置等等，用于Kong在启动的时候生成Nginx配置文件
• 数据库存储配置：配数据库类型，地址、用户名密码等等信息
• 数据库缓存配置：配置数据的缓存规则，Kong会缓存诸如API信息、用户、凭证等信息，以减少访问数据库次数提高性能
• DNS解析器配置：默认情况会使用系统设置，如hosts和resolv.conf的配置，你也可以通过DNS的解析器配置来修改
• 其他杂项配置：继承自lua-nginx模块的其他设置允许更多的灵活性和高级用法。

1、常规配置

在常规配置中，主要是控制Kong一些运行时的一些配置，主要有如下配置：

配置项	默认值	说明
prefix	/usr/local/kong/	配置Kong的工作目录，相当于Nginx的工作目录，这个目录存放运行时的临时文件和日志，包括Kong启动的时候自动生成的Nginx的配置文件。每一个Kong经常必须有一个单独的工作目录
log_level	notice	Nginx的日志级别。日志存放logs/error.log
proxy_access_log	logs/access.log	代理端口请求的日志文件，可以设置为off来关闭日志的记录，也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径，则日志文件会保存在的目录下
proxy_error_log	logs/error.log	代理端口请求的错误日志文件，可以设置为off来关闭日志的记录，也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径，则日志文件会保存在的目录下
admin_access_log	logs/admin_access.log	Kong管理的API端口请求的日志文件，可以设置为off来关闭日志的记录，也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径，则日志文件会保存在的目录下
admin_error_log	logs/error.log	Kong管理的API端口请求的错误日志文件，可以设置为off来关闭日志的记录，也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径，则日志文件会保存在的目录下
plugins	bundled	Kong启动的时候加载的插件，如果多个必须要使用半角逗号分割。默认情况下，只有捆绑官方发行版本的插件通过 bundled 这个值来加载。加载插件只是Kong在启动的时候载入插件的代码，但是并不会使用它，如果要使用他，还必须要通过管理API来配置 当然，如果你不想加载任何插件，可以使用off来关闭它，值得强调的一点bundled值可以和其他插件名称一起使用，bundled并不是一个插件名称，它代表了随官方发行的所有插件。
anonymous_reports	on	如果Kong进程发生了错误，会以匿名的方式将错误提交给Kong官方， 以帮助改善Kong。

在常规的配置中，主要配置了Kong运行的目录日志等信息。配置文件或者目录Kong必须要用权限访问，否则会报错。

2、Nginx注入配置

Kong基于Nginx，当然需要配置Nginx来满足Kong的运行要求，Kong提供了Nginx的注入配置，使得我们更轻松控制。

在Nginx注入配置中，有如下配置：

配置项	默认值	说明
proxy_listen	0.0.0.0:8000, 0.0.0.0:8443 ssl	配置Kong代理监听的地址和端口，这个是Kong的入口，API调用都将通过这个端口请求。这个配置和Ngxin中的配置一致，通过SSL可以指定接受https的请求支持IPv4和IPv6
admin_listen	127.0.0.1:8001, 127.0.0.1:8444 ssl	配置Kong的管理API监听的端口，和proxy_listen配置一样，但是这个配置不建议监听在公网IP上。
nginx_user	nobody nobody	配置Nginx的用户名和用户组，和Nginx的配置规则一样
nginx_worker_processes	auto	设置Nginx的进程书，通常等于CPU核心数
nginx_daemon	on	是否以daemon的方式运行Ngxin
mem_cache_size	128m	内存的缓存大小，可以使用k和m为单位
ssl_cipher_suite	modern	定义Nginx提供的TLS密码，可以配置的值有：modern,intermediate, old, custom.
ssl_ciphers		定义Nginx提供的TLS密码的列表，参考Nginx的配置
ssl_cert		配置SSL证书的crt路径，必须是要绝对路径
ssl_cert_key		设置SSL证书的key文件，必须是绝对路径
client_ssl	off	……
client_ssl_cert		……
client_ssl_cert_key		……
admin_ssl_cert		……
admin_ssl_cert_key		……
headers	server_tokens, latency_tokens	设置再相应客户端时候应该注入的头部，可以设置的值如下：– server_tokens: 注入’Via’和’Server’头部.– latency_tokens: 注入’X-Kong-Proxy-Latency’和’X-Kong-Upstream-Latency’ 头部.– X-Kong-: 只有在适当的时候注入特定的头部这个配置可以被设置为off。当然，即便设置了off以后，插件依然可以注入头部
trusted_ips		定义可信的IP地址段，通常不建议在此处限制请求，应该再插件中过滤
real_ip_header		X-Real-IP
real_ip_recursive	off	这个值在Nginx配置中设置了同名的ngx_http_realip_module指令
client_max_body_size	0	配置Nginx接受客户端最大的body长度，如果超过此配置 将返回413。 设置为0则不检查长度
client_body_buffer_size	8k	设置读取缓冲区大小，如果超过内存缓冲区大小，那么NGINX会缓存在磁盘中，降低性能。
error_default_type	text/plain	当请求’ Accept ‘头丢失，Nginx返回请求错误时使用的默认MIME类型。可以配置的值为：text/plain,text/html, application/json, application/xml.
在Nginx注入配置中，配置了Nginx的基本的参数，这些参数大部分和NGINX的配置值是一样的。

3、数据库存储配置

数据库配置的模块配置数据库相关的连接信息等等。主要有如下配置：

配置项	默认值	说明
database	postgres	设置数据库类型，Kong支持两种数据库，一种是postgres，一种是cassandra
PostgreSQL配置		如果database设置为postgres以下配置生效
pg_host	127.0.0.1	设置PostgreSQL的连接地址
pg_port	5432	设置PostgreSQL的端口
pg_user	kong	设置PostgreSQL的用户名
pg_password		设置PostgreSQL的密码
pg_database	kong	设置数据库名称
pg_ss	off	是否开启ssl连接
pg_ssl_verify	off	如果启用了’ pg_ssl ‘，则切换服务器证书验证。
cassandra	配置	如果database设置为cassandra以下配置生效
cassandra_contact_points	127.0.0.1	……
cassandra_port	9042	……
cassandra_keyspace	kong	……
cassandra_timeout	5000	……
cassandra_ssl	off	……
cassandra_ssl_verify	off	……
cassandra_username	kong	……
cassandra_password		……
cassandra_consistency	ONE	……
cassandra_lb_policy	RoundRobin	……
cassandra_local_datacenter	……
cassandra_repl_strategy	SimpleStrategy	……
cassandra_repl_factor	1	……
cassandra_data_centers	dc1:2,dc2:3	……
cassandra_schema_consensus_timeout	10000	……

4、数据库缓存配置

配置了Kong持久化存储，显然如果每次的请求都需要去查询数据库中的相关信息那无疑是非常消耗资源，性能和稳定性也会大大降低，作为一个API网关肯定是不能忍的，解决这个问题的办法就是缓存，Kong将数据缓存在内存中，这样会大大提高性能，本节介绍Kong的缓存配置。

配置项	默认值	说明
db_update_frequency	5	节点更新数据库的时间，以秒为单位。
db_update_propagation	0	数据库节点的更新时间。如果使用了Cassandra数据库集群，那么如果数据库有更新，最多需要db_update_propagation时间来同步所有的数据库副本。如果使用PostgreSQL或者单数据库，这个值可以被设置为0
db_cache_ttl	0	缓存生效时间，单位秒。如果设置为0表示永不过期 。Kong从数据库中读取数据并且缓存，在ttl过期后会删除这个缓存然后再一次读取数据库并缓存
db_resurrect_ttl	30	缓存刷新时间，单位秒。当数据存储中的陈旧实体无法刷新时(例如，数据存储不可访问)，应该对其进行恢复。当这个TTL过期时，将尝试刷新陈旧的实体。

DNS解析器配置

默认情况下，DNS解析器将使用标准配置文件/etc/hosts和/etc/resolv.conf。如果设置了环境变量LOCALDOMAIN和RES_OPTIONS，那么后一个文件中的设置将被覆盖。

配置项	默认值	说明
dns_resolver		配置DNS服务器列表，用半角逗号分割，每个条目使用ip[:port]的格式，这个配置仅提供给Kong使用，不会覆盖节点系统的配置，如果没有配置则使用系统的设置。接受IPv4和IPv6的地址。
dns_hostsfile	/etc/hosts	配置Kong的hosts文件，这个配置同样仅提供给Kong使用，不会覆盖节点系统的配置。需要说明的是这个文件仅读取一次，读取的内容会缓存再内存中，如果修改了此文件，必须要重启Kong才能生效。
dns_order	LAST,SRV,A,CNAME	解析不同记录类型的顺序。“LAST”类型表示最后一次成功查找的类型(用于指定的名称)
dns_stale_ttl	4	配置DNS记录缓存过期时间
dns_not_found_ttl	30	这个配置值不知道该如何理解？？
dns_error_ttl	1	……
dns_no_sync	off	如果启用了该项，那么在DNS缓存过期之后，每一次请求都会发起DNS查询。在禁用此项时，那么相同的域名多次请求会同步到一个查询中共享返回值。

在DNS配置中，我们基本上不需要更改，官网的配置给出了最优的配置。如果我们需要在host文件中定义后端绑定的域名，一定要在编辑hosts文件后重载Kong的配置，或者重启Kong，无论hosts的文件是否是/etc/hosts，否则都不会生效的。

其他杂项配置

杂项配置基本上关于LUA的配置，如果不熟悉请不要修改，按照官方默认即可。

配置项	默认值	说明
lua_ssl_trusted_certificate		….
lua_ssl_verify_depth		1
lua_package_path	./?.lua;./?/init.lua;	….
lua_package_cpath		….
lua_socket_pool_size	30	….

API 管理详解

安装好了Kong，那么如何使用和管理它呢？Kong附带了一个管理的API接口，我们通过这个API接口来管理所有的API以及其他的资源，这个接口具有最高的权限，所以在生产环境中我们要特别注意这个接口的权限，通常我们不会将这个接口暴露在外网中。

如果Kong是以集群的状态的运行的，那么你只需要将管理API的请求发送到其中的一个节点中，Kong会自动同步信息到其他的节点。Kong默认监听8001和8444两个端口用接受管理API的请求，8001为http端口，8444为https端口

Kong支持application/x-www-form-urlencoded和application/json两种类型，POST的数据我们需要以json的格式发送。

Kong大概有以下几个管理对象：

• 节点信息
• 服务
• 路由
• 用户
• 插件
• 证书
• SNI
• 上游信息
• 目标

1、查看节点信息

接口信息：

接口名称	查看节点详细信息
请求端点	/
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

无

请求示例：

curl -s http://127.0.0.1:8001 | python -m json.tool

2、查看节点状态

这个接口查询节点的状态，主要是显示nginx进程处理连接的情况，以及数据库连接的情况。

如果Kong是以集群的方式运行，那么如果要查看其他节点的情况，必须要要一个一个访问节点的此接口。

因为Kong是基于nginx的，你也可以直接使用Nginx的监控工具。

接口信息：

接口名称	查看节点状态
请求端点	/status
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

无

请求示例：

curl -s http://127.0.0.1:8001/status  | python -m json.tool

返回值：

{
    "database": {
        "reachable": true
    },
    "server": {
        "connections_accepted": 111,
        "connections_active": 1,
        "connections_handled": 111,
        "connections_reading": 0,
        "connections_waiting": 0,
        "connections_writing": 1,
        "total_requests": 64
    }
}

在返回的数据中，各个值的含义如下：

• total_requests：客户端请求的总数。
• connections_active：当前活动客户端连接数，包括等待连接。
• connections_accepted：已接受的客户端连接总数。
• connections_handled：已处理连接的总数。通常，参数值与accept相同，除非已达到某些资源限制。
• connections_reading：Kong正在读取请求标头的当前连接数。
• connections_writing：nginx将响应写回客户端的当前连接数。
• connections_waiting：等待请求的当前空闲客户端连接数。

服务是每一个后端真实接口的抽象，它与路由关联，客户端发起请求，如果路由匹配到了，那么会将这个请求代理到与匹配路由相关联的服务中。

3、添加服务

接口信息：

接口名称	添加服务
请求端点	/services
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
name	string		否	服务名称，全局唯一
protocol	string	http	是	和上游通讯的协议取值http或https
host	string		是	上游服务器的主机
port	int	80	是	上游服务器的端口
path	string		否	上游服务器请求中的路径，必须以 /开头
retries	int	5	否	代理失败时要执行的重试次数
connect_timeout	int	60000	否	与上游连接的超时时间，单位毫秒
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

如果在创建服务的时候没有指定name，那么Kong并不会自动创建name，但是会创建UUID形式的ID，Kong在调用、匹配等等的操作都是可以基于这个ID，所以这个ID绝对是全局唯一的。

如果在创建服务的时候没有指定name，那么Kong并不会自动创建name，但是会创建UUID形式的ID，Kong在调用、匹配等等的操作都是可以基于这个ID，所以这个ID绝对是全局唯一的。

在其他的对象管理中，name字段可能是必须的，通常这个name资源也是全局唯一的，即便如此，Kong也会创建ID字段，也可以通过这个ID字段来匹配。

在服务对象中，能组合起来成为上游服务也是唯一的，也就是说，在一个服务中无法同时存在 http和https，如果上游提供http和https服务，同时也需要Kong代理它们的话，那必须要设置两个服务。

4、查询服务

接口信息：*

接口名称	查询服务
请求端点	/services/{name or id}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:
无

请求示例：

curl -s http://127.0.0.1:8001/services/{service_id}  | python -m json.tool

返回值：

{
    "database": {
        "reachable": true
    },
    "server": {
        "connections_accepted": 111,
        "connections_active": 1,
        "connections_handled": 111,
        "connections_reading": 0,
        "connections_waiting": 0,
        "connections_writing": 1,
        "total_requests": 64
    }
}

5、查询所有服务

接口信息：*

接口名称	查询所有服务
请求端点	/services/
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
offset	string		否	分页偏移，用于定义列表中的唯一
size	iny	100	否	每页返回数量

请求示例：

curl -s http://127.0.0.1:8001/services/?size=1  | python -m json.tool

返回值：

{
    "data": [
        {
            "connect_timeout": 60000,
            "created_at": 1537986798,
            "host": "www.baidu.com",
            "id": "27f30248-fef1-4ddc-9fdc-4ca73f354c64",
            "name": "infvie_server",
            "path": null,
            "port": 80,
            "protocol": "http",
            "read_timeout": 60000,
            "retries": 5,
            "updated_at": 1537986798,
            "write_timeout": 60000
        }
    ],
    "next": "/services?offset=WyIyN2YzMDI0OC1mZWYxLTRkZGMtOWZkYy00Y2E3M2YzNTRjNjQiXQ",
    "offset": "WyIyN2YzMDI0OC1mZWYxLTRkZGMtOWZkYy00Y2E3M2YzNTRjNjQiXQ"
}

6、更新服务

接口信息：*

接口名称	更新服务
请求端点	/services/{name or id}
请求方法	PATCH
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
name	string		否	服务名称，全局唯一
protocol	string	http	是	和上游通讯的协议取值http或https
host	string		是	上游服务器的主机
port	int	80	是	上游服务器的端口
path	string		否	上游服务器请求中的路径，必须以 /开头
retries	int	5	否	代理失败时要执行的重试次数
connect_timeout	int	60000	否	与上游连接的超时时间，单位毫秒
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

7、更新或者创建服务

接口信息：*

接口名称	查看节点详细信息
请求端点	/services/{name or id}
请求方法	PUT
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
name	string		否	服务名称，全局唯一
protocol	string	http	是	和上游通讯的协议取值http或https
host	string		是	上游服务器的主机
port	int	80	是	上游服务器的端口
path	string		否	上游服务器请求中的路径，必须以 /开头
retries	int	5	否	代理失败时要执行的重试次数
connect_timeout	int	60000	否	与上游连接的超时时间，单位毫秒
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

8、删除服务

接口信息：*

接口名称	删除服务
请求端点	/services/{name or id}
请求方法	DELETE
返回状态	HTTP 204 No Content

请求参数:
无

请求示例：

curl -i  -X DELETE --url http://127.0.0.1:8001/services/{service_id}

9、添加路由

接口信息：*

接口名称	添加路由
请求端点	/routes/
请求方法	POST
返回状态	HTTP 201 Created

请求参数:

参数名	类型	默认值	是否必须	说明
protocols	list	[“http”, “https”]	否	此路由允许的协议，取值http或https
methods	list	null	*否	此路由允许的http 方法
hosts	list	null	*否	此路由允许的域名
paths	list	80	是	上游服务器的端口
strip_path	bool	true	否	匹配到path时，是否删除匹配到的前缀
preserve_host	bool	true	否	匹配到hosts时，使用请求头部的值为域名向后端发起请求，请求的头部为”host”,例如”host:api.abc.com”
service	string		是	关联服务id
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

请求示例：

curl -X POST http://localhost:8001/routes -H 'Content-Type: application/json' -d '{"name":"sase-server","protocols":["http","https"],"paths":["/"],"hosts":["10.41.38.4:9443"],"service":{"id":"5d3637d3-a4e9-4dc3-bf9d-a2381eb86148"}}'

值得注意的是，methods，hosts，paths这三个参数必须要指定一个，否则无法创建路由。

10、查看路由

接口信息：*

接口名称	查看路由
请求端点	/routes/{id}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:
无

请求示例：

curl -s http://127.0.0.1:8001/routes/{route_id} | python -m json.tool

11、查询所有路由

接口信息：*

接口名称	查询所有路由
请求端点	/routes
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
offset	string		否	分页偏移，用于定义列表中的唯一
size	iny	100	否	每页返回数量

请求示例：

curl -s http://127.0.0.1:8001/routes/?size=1 | python -m json.tool

12、更新路由

接口信息：

接口名称	更新路由
请求端点	/routes/{id}
请求方法	PATCH
返回状态	HTTP 200 OK

请求参数

参数名	类型	默认值	是否必须	说明
protocols	list	[“http”, “https”]	否	此路由允许的协议，取值http或https
methods	list	null	*否	此路由允许的http 方法
hosts	list	null	*否	此路由允许的域名
paths	list	80	是	上游服务器的端口
strip_path	bool	true	否	匹配到path时，是否删除匹配到的前缀
preserve_host	bool	true	否	匹配到hosts时，使用请求头部的值为域名向后端发起请求，请求的头部为”host”,例如”host:api.abc.com”
service	string		是	关联服务id
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

13、更新或者添加路由

接口信息：

接口名称	更新或者添加路由
请求端点	/routes/{id}
请求方法	PUT
返回状态	HTTP 201 Created or HTTP 200 OK

请求参数

参数名	类型	默认值	是否必须	说明
protocols	list	[“http”, “https”]	否	此路由允许的协议，取值http或https
methods	list	null	*否	此路由允许的http 方法
hosts	list	null	*否	此路由允许的域名
paths	list	80	是	上游服务器的端口
strip_path	bool	true	否	匹配到path时，是否删除匹配到的前缀
preserve_host	bool	true	否	匹配到hosts时，使用请求头部的值为域名向后端发起请求，请求的头部为”host”,例如”host:api.abc.com”
service	string		是	关联服务id
write_timeout	int	60000	否	向上游发送请求两次连续写操作的超时时间 ，单位毫秒
read_timeout	int	60000	否	用于向上游服务器发送请求的两次连续读取操作之间的超时 ，单位毫秒

14、查看和服务关联的路由

接口信息：

接口名称	查看和服务关联的路由
请求端点	/services/{service name or id}/routes
请求方法	GET
返回状态	HTTP 200 OK

请求参数
无

请求示例：

curl -s http://127.0.0.1:8001/services/{service_id}/routes | python -m json.tool

15、查看和路由关联的服务

接口信息：

接口名称	查看和路由关联的服务
请求端点	/routes/{route id}/service
请求方法	GET
返回状态	HTTP 200 OK

请求参数
无

请求示例：

curl -s http://127.0.0.1:8001/routes/{route_id}/service | python -m json.tool

16、删除路由

接口信息：

接口名称	删除路由
请求端点	/routes/{id}
请求方法	DELETE
返回状态	HTTP 204 No Content

请求参数
无

请求示例：

curl -s http://127.0.0.1:8001/routes/{route_id}| python -m json.tool

17、添加用户

接口信息：

接口名称	添加用户
请求端点	/consumers
请求方法	POST
返回状态	HTTP 201 Created

请求参数

参数名	类型	默认值	是否必须	说明
username	string		*否	全局唯一用户名
custom_id	string	null	*否	全局唯一用户id

18、查询用户

接口信息：

接口名称	查看节点详细信息
请求端点	/consumers/{username or id}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:
无

请求示例：

curl -s http://127.0.0.1:8001/consumers/{custom_id}| python -m json.tool

19、查询所有用户

接口信息：

接口名称	查询所有用户
请求端点	/consumers
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
offset	string		否	分页偏移，用于定义列表中的唯一
size	iny	100	否	每页返回数量

请求示例：

curl -s http://127.0.0.1:8001/consumers/size=10| python -m json.tool

20、更新用户

接口信息：

接口名称	更新用户
请求端点	/consumers/{username or id}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
username	string		*否	全局唯一用户名
custom_id	string	null	*否	全局唯一用户id

21、更新或者添加用户

接口信息：

接口名称	更新或者添加用户
请求端点	/consumers/{username or id}
请求方法	PUT
返回状态	HTTP 201 Created or HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
username	string		*否	全局唯一用户名
custom_id	string	null	*否	全局唯一用户id

删除用户

接口信息：

接口名称	删除用户
请求端点	/consumers/{username or id}
请求方法	DELETE
返回状态	HTTP 204 No Content

请求示例：

curl -i -X DELETE --url http://192.168.0.184:8001/consumers/{custom_id} 

插件概述

Kong提供了一个插件的功能，你可以通过配置指定某个服务或者路由或者用户启用某个插，插件始终只运行一次，所以对于不同的实体配置相同插件时就有优先级的概念。

多次配置插件的优先级如下：

• 在以下组合上配置的插件：路由，服务和使用者。 （消费者意味着必须对请求进行身份验证）。
• 在Route和Consumer的组合上配置的插件。 （消费者意味着必须对请求进行身份验证）。
• 在服务和使用者的组合上配置的插件。 （消费者意味着必须对请求进行身份验证）。
• 在路由和服务的组合上配置的插件。
• 在Consumer上配置的插件。 （消费者意味着必须对请求进行身份验证）。
• 在路由上配置的插件。
• 在服务上配置的插件。
• 配置为全局运行的插件。

从以上的优先级可以看出全局配置的插件优先级最小，而越具体的组合优先级越高。

23、添加插件

可以通过以下几种不同的方式添加插件：

• 对于每个Service/Route和consumer。不要设置consumer_id和设置service_id或route_id。
• 适用于每个Service/Route和特定consumer。只有设定consumer_id。
• 适用于每个consumer和特定Service。仅设置service_id（警告：某些插件只允许设置route_id）
  对于每个consumer和特定的Route。仅设置route_id（警告：某些插件只允许设置service_id）
  对于特定的Service/Route和consumer。设置两个service_id/ route_id和consumer_id。

并非所有插件都允许指定consumer_id。检查插件文档。

接口信息：

接口名称	添加插件
请求端点	/plugins
请求方法	POST
返回状态	HTTP 201 Created

请求参数:

参数名	类型	默认值	是否必须	说明
name	string		是	要添加的插件的名称。目前，插件必须分别安装在每个Kong实例中。
consumer_id	string	null	否	使用者的唯一标识符，用于覆盖传入请求中此特定使用者的现有设置。
service_id	string	null	否	服务的唯一标识符，用于覆盖传入请求中此特定服务的现有设置。
route_id	string	null	否	路由的唯一标识符，它覆盖传入请求中此特定路由的现有设置。
config	object	null	否	插件的配置属性，可以在Kong Hub的插件文档页面找到。
enabled	bool	true	否	是否应用插件。默认值：true。
tags	list		否	与插件关联的一组可选字符串，用于分组和筛选。

24、查询插件

接口信息：

接口名称	查询插件
请求端点	/plugins{id}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
id	string		是	要检索的插件的唯一标识符

请求示例：

curl -s  --url http://127.0.0.1:8001/plugins/{id}  | python -m json.tool

25、查询所有插件

接口信息：

接口名称	查询所有插件
请求端点	/plugins/
请求方法	GET
返回状态	HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
id	string		否	通过id查询
name	string		是	通过name查询
consumer_id	string		否	通过consumer_id查询
service_id	string		否	通过service_id查询
route_id	string		否	通过route_id查询
offset	string		否	分页偏移，用于定义列表中的唯一
size	iny	100	否	每页返回数量

请求示例：

curl -s --url http://127.0.0.1:8001/plugins/?size=1 | python -m json.tool

26、更新或添加插件

接口信息：

接口名称	更新或添加插件
请求端点	/plugins/
请求方法	PUT
返回状态	HTTP 201 Created or HTTP 200 OK

请求参数:

参数名	类型	默认值	是否必须	说明
name	string		是	要添加的插件的名称。目前，插件必须分别安装在每个Kong实例中。
consumer_id	string	null	否	使用者的唯一标识符，用于覆盖传入请求中此特定使用者的现有设置。
service_id	string	null	否	服务的唯一标识符，用于覆盖传入请求中此特定服务的现有设置。
route_id	string	null	否	路由的唯一标识符，它覆盖传入请求中此特定路由的现有设置。
config	object	null	否	插件的配置属性，可以在Kong Hub的插件文档页面找到。
enabled	bool	true	否	是否应用插件。默认值：true。
tags	list		否	与插件关联的一组可选字符串，用于分组和筛选。

28、删除插件

接口信息：

接口名称	删除插件
请求端点	/plugins/{plugin_id}
请求方法	DELETE
返回状态	HTTP 204 No Content

请求参数:

参数名	类型	默认值	是否必须	说明
plugin_id	string		是	要删除的插件配置的唯一标识符

curl -s -X DELETE --url http://127.0.0.1:8001/plugins/{plugin_id} | python -m json.tool

29、查询已启用的插件

接口信息：

接口名称	查询已启用的插件
请求端点	/plugins/enabled
请求方法	GET
返回状态	HTTP 200 OK

请求参数:
无

请求示例：

curl -s -X GET --url http://127.0.0.1:8001/plugins/enabled | python -m json.tool

30、检索插件架构

接口信息：

接口名称	检索插件架构
请求端点	/plugins/schema/{plugin_name}
请求方法	GET
返回状态	HTTP 200 OK

请求参数:
无

请求示例：

curl -s -X GET --url http://192.168.0.184:8001/plugins/schema/{plugin_name} | python -m json.tool