微服务Kong（八）——代理参考

Kong侦听四个端口的请求，默认情况是：

　　8000：此端口是Kong用来监听来自客户端的HTTP请求的，并将此请求转发到您的上游服务。这也是本教程中最主要用到的端口。

　　8443：此端口是Kong监听HTTP的请求的端口。该端口具有与8000端口类似的行为，但是它只监听HTTPS的请求，并不会产生转发行为。可以通过配置文件来禁用此端口。

　　8001：用于管理员对KONG进行配置的端口。

　　8444：用于管理员监听HTTPS请求的端口。

　　在本文中，我们将介绍Kong的路由功能，并详细说明8000端口上的客户端请求如何根据请求头、URI或HTTP被代理到配置中的上游服务。

基础术语：

　　API：指Kong的API实例。您可以通过管理员身份配置您的API。

　　Plugin：他指的是Kong的“插件”，它们是在代理生命周期中运行的业务逻辑。可以通过管理员身份进行全局配置，也可针对每个API进行分别配置。

　　Client：指向Kong的代理端口发出请求的下游客户，即第三方客户端。

　　Upstream service：指的是位于Kong后面的您自己的API服务，客户端请求被转发的最终目的地。nginx中的上游服务器。

概述

　　从整体上来看，Kong侦听其配置的代理端口上的HTTP请求（默认为8000），并识别正在请求的是哪个上游服务，然后运行在该API上的配置插件（如果没有则不执行），并将上游的HTTP请求转发到您自己的API服务。

　　当客户端向代理端口发出请求时，Kong将根据API在KONG里的配置情况，来决定将请求传入到哪个上游服务中。 您可以在KONG里对每个API添加许多属性，但是有三个是必须要配置的，他们是hosts、uris和methods。如果KONG无法确定API请求的上游服务地址，则会返回一下内容：

HTTP/1.1  Not Found
Content-Type: application/json
Server: kong/<x.x.x>

{
    "message": "no API found with those values"
}

回忆下：如何向KONG添加一个API

　　　　在之前的添加一个API的指南中，有学习过如何使用8001端口，在KONG服务中添加一个API的操作：

$ curl -i -X POST http://localhost:8001/apis/ \
    -d 'name=my-api' \
    -d 'upstream_url=http://my-api.com' \
    -d 'hosts=example.com' \
    -d 'uris=/my-api' \
    -d 'methods=GET,HEAD'
HTTP/1.1  Created
...

　　　　该代码表示用户成功在Kong里注册一个名为“my-api”的API，可通过访问“http://example.com”发送请求。它还指定了一些HTTP请求的属性，但请注意，这里有且只有一个HOST，URIS和METHODS属性。当完成此配置后，以后所有的符合此host、uris和methods的请求，都将由KONG来代理过滤转发。Kong是一个透明的代理，它会将请求转发给您的上游服务，除了添加诸如Connection之类的各种标题。

转发功能

　　　　现在我们来讨论一下，一个HTTP请求是如何与API配置属性（如host、uris、methods）相匹配的。需要注意的是，这三个字段（h、u、m）都是可选的，但至少要有一个被指定。对于客户端请求与API的匹配：

　　　　· 请求必须包含所有已配置的字段

　　　　· 请求中的字段值必须与至少一个已配置的值相匹配（尽管字段配置接受一个或多个值，请求只需要考虑匹配其中之一）

　　　　让我们来看几个例子。请看如下一个API配置：

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "hosts": ["example.com", "service.com"],
    "uris": ["/foo", "/bar"],
    "methods": ["GET"]
}

　　　　与该API相匹配的一些请求可能是：

GET /foo HTTP/1.1
Host: example.com

GET /bar HTTP/1.1
Host: service.com

GET /foo/hello/world HTTP/1.1
Host: example.com

　　　　以上的三个请求都满足API定义中设置的条件。但是，以下的几个请求则与配置的条件不匹配：

GET / HTTP/1.1
Host: example.com

POST /foo HTTP/1.1
Host: example.com

GET /foo HTTP/1.1
Host: foo.com

　　　　以上的三个请求只满足两个配置条件。第一个请求的URI不匹配，第二个请求的HTTP方法不匹配，第三个请求的Host头不匹配。

　　　　现在我们了解了hosts、uris、methods是如何一起工作的。下面我们来逐个了解他们是如何单独工作的。

　　　　1. 请求的HOST头：

　　　　　　基于HOST头发送请求，是通过KONG发送请求的最直接的一种方式，这也是HOST头的基本用法之一。KONG使通过HOST访问API实体的流程更加简便快捷。HOSTS 接受多种参数，当使用管理员API进行请求时，需要将每个参数间用逗号分隔开来配置：

$ curl -i -X POST http://localhost:8001/apis/ \
    -d 'name=my-api' \
    -d 'upstream_url=http://test-api.com' \
    -d 'hosts=test-api.com,demo.com,service.com'
HTTP/1.1  Created
...

此时，客户端可使用 hosts=test-api.com, demo.com, service.com 中的任意一个HOST头对 my-api 进行访问，但不能缺省HOST的值。

　　　　1.1 使用通配符查找主机名

　　为了使代理更灵活，KONG允许使用通配符来配置HOSTS。通配符允许任何满足条件的HOST头对API实体进行访问。在配置通配符时，只允许在HOST的最左或最右配置一个星号（*），例如：

*.example.com ：允许类似于 a.example.com 或 a.b.example.com 等形式的HOST头访问。
example.*　　　：允许类似于 example.a 或 example.b.cn 等形式的HOST头访问。

　　一个完整的例子：

{
    "name": "test-api",
    "upstream_url": "http://test-api.com",
    "hosts": ["*.example.com", "service.com"]
}

　　匹配的HOST头请求类似于一下几种，但不限于一下的例子中的形式：

GET / HTTP/1.1
Host: an.example.com

GET / HTTP/1.1
Host: service.com

　　　　1.2. preserve_host属性

　　　　　　当启用代理时，KONG默认将API的 upstream_url 的值配置为上游服务主机的 host 。preserve_host提供一个boolean值，对KONG的这个行为进行限制。例如，当使用preserve_host的默认值进行配置时，API的配置信息大致为：

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "hosts": ["service.com"],
}

此时，客户端发送的请求信息格式大致为：

GET / HTTP/1.1
Host: service.com

KONG会从API的upstream_url中提取HOST值，在做代理时，会向上游服务发送类似的请求：

GET / HTTP/1.1
Host: my-api.com

然而，当管理员在配置API时，明确指定了preserver_host=true时：

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "hosts": ["service.com"],
    "preserve_host": true
}

并假设客户端发送了相同的请求：

GET / HTTP/1.1
Host: service.com

KONG将会保留客户端发送来的HOST值，在做代理时，会向上游服务发送以下的请求：

GET / HTTP/1.1
Host: service.com

　　　　2 请求URI

　　　　　　KONG将请求转发给上游服务的另一种方式，是通过配置uris属性来指定请求的URI值。uris可以配置多个值，此时客户端在进行请求时，必须选择uris中的一个值作为请求的前缀。

　　例如，如果API的配置为：

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "uris": ["/service", "/hello/world"]
}

　　以下的几种请求方式都可以对此API进行访问：

GET /service HTTP/1.1
Host: my-api.com

GET /service/resource?param=value HTTP/1.1
Host: my-api.com

GET /hello/world/resource HTTP/1.1
Host: anything.com

　　以上几种方式在进行请求时，KONG侦测到他们的前缀与API的uris属性值是匹配的，所以这些请求是可用的。

　　当uris属性配置好后，在进行请求时，KONG首先会取最长的uris值对URI进行匹配筛选，如果未匹配，然后才会取次长度的uris值进行匹配，依次类推，直到匹配成功为止或拒绝访问。譬如上面的例子里，在发送请求时，KONG首先会取 `/hello/world` 与请求uri进行匹配，如果未成功，才会继续取 `/service` 继续匹配工作。

　　　　2.1 strip_uri属性

　　　　　　在配置API的uris时，如果你希望隐藏上游服务的真实uri，并以另外的一种URI提供给客户端时，通过简单的配置API的strip_uri属性就可以实现。例如：

{
    "name": "my-api",
    "upstream_url": "http://my-api.com",
    "uris": ["/service"],
    "strip_uri": true
}

　　启用strip_uri属性来指示Kong在代理此API时，在上游请求的URI中不应包含匹配的URI前缀。针对上面的API配置，当客户端发送请求时

GET /service/path/to/resource HTTP/1.1
Host:

　　KONG代理到上游服务的真实uri为（此时的uri不包含uris中配置的内容）

GET /path/to/resource HTTP/1.1
Host: my-api.com

　　　　3. HTTP请求方法

　　　　　　从KONG 0.10版本开始，可以通过配置API的methods属性来指定客户端的请求。默认情况下，无论HTTP请求方式如何，Kong都会将请求将其代理到API的。但是，当配置methods属性后，只有HTTP请求方式匹配时才会被KONG代理。methods属性可以配置多个值：

{
    "name": "api-1",
    "upstream_url": "http://my-api.com",
    "methods": ["GET", "HEAD"]
}

　　以下的两种HTTP请求方式都可以被代理

GET / HTTP/1.1
Host:

HEAD /resource HTTP/1.1
Host:

　　但是不会匹配POST或DELETE等其他的请求方式。配置此属性，可以更细粒度的管理你的API。

代理的优先级

　　　　　　一个API可以通过配置hosts、uris和methods属性定义匹配规则。对于Kong来说，只有当所有的字段都匹配时，才会进行转发。然而，KONG允许两个或更多的API拥有相同的配置。此时，就涉及到请求的优先级问题了。

　　　　匹配优先级原则是：在评估请求时，Kong会首先与匹配规则最多的API进行匹配（when evaluating a request, Kong will first try to match the APIs with the most rules.）。例如有两个API的配置如下

{
    "name": "api-1",
    "upstream_url": "http://my-api.com",
    "hosts": ["example.com"]
},

{
    "name": "api-2",
    "upstream_url": "http://my-api-2.com",
    "hosts": ["example.com"],
    "methods": ["POST"]
}

　　api-2比api-1多了一个methods配置，所以KONG会最先将请求与api-2进行匹配。通过此配置，我们就能避免在请求api-2时，错误的转发到api-1。

此时，这个请求会被转发到api-1：

GET / HTTP/1.1
Host: example.com

而这个请求，会被转发到api-2：

POST / HTTP/1.1
Host: example.com

　　以此类推，如果一个api同时配置了hosts、methods、uris，则这个API会最先与请求进行匹配，他的优先级会是三个中最高的。

代理行为

　　上述内容详细讲述了KONG将请求代理到上游服务的代理规则。下面我们将详细说明，在KONG将请求转发到上游服务的这段时间内实际发生的一些事。

　　1. 负载平衡

　　　　从KONG 1.10 版本开始，Kong继承实现了负载平衡的功能，可以将转发的请求分发到多个上游服务实例。在 Kong 0.10之前，一般情况下，Kong会将代理的请求转发到指定的upstream_url上，如果想实现服务的负载平衡，需要额外的工具来完成。您可以通过查阅负载平衡相关资料，找到更多有关向API添加负载平衡的信息。

　　2. 插件扩展

　　　　使用者可以通过plugins来自定义扩展插件，并将插件应用到request/response的生命周期中。插件可以在您的生产环境中对代理行为进行多种操作。通过对插件进行配置，可以将插件应进行全局应用或针对个别API应用。如果对给定的某个或某些API应用了一个插件或多个插件，则在代理请求到上游服务前，会首先执行API的匹配，匹配成功后再执行定义的插件，当插件执行完后，如果满足天剑，才会将请求最终代理到上游服务中去。这里包含了插件的访问时段的概念，具体参考插件开发配置相关资料。

　　3. 代理或请求超时

　　　　当KONG将所有的代理逻辑，包括API验证和插件等，都处理完后，才会将请求代理到上游服务。这些是通过Nginx的代理模块来实现的。从KONG 0.10开始，可以通过配置以下三个API属性来定义连接超时时间：

　　upstream_connect_timeout: 定义同上游服务建立连接的超时时间，单位是毫秒，默认值为60000.

　　upstream_send_timeout: 定义两个连续向上游服务发送的写入操作的超时时间，单位是毫秒，默认值为60000.

　　upstream_read_timeout: 定义两个连续向上游服务发送读取操作的超时时间，单位是毫秒，默认值为60000.

　　　　在使用HTTP/1.1时，KONG会默认添加以下请求头信息：

　　HOST：<上游服务的host>

　　Connection：keep-alive : 允许重复使用上游连接

　　X-REAL-IP:<$proxy_add_x_forwarded_for>: 参见 nginx_http_proxy_module.

　　X-Forwarded-Proto:<protocol>: protocol是客户端使用的协议名

　　　　其他的请求头都按默认配置添加。

　　　　当使用WebSocket时，会有例外发生。如果发生，KONG允许通过以下请求头对协议进行升级：

　　Connection：Upgrade

　　Upgrade：WebSocket

　　4. Response

　　　　Kong接收上游服务的响应，并以流式方式将其发回下游客户端。此时，Kong将执行添加到该特定API的后续插件，并且这些插件继承了header_filter子句。当所有继承了header_filter的插件执行完后，以下的几种头信息将返回给客户端：

　　Via：kong/x.x.x KONG的版本信息，x.x.x是他的版本号。

　　Kong-Proxy-Latency：<latency>，其中 latency 表示Kong接收来自客户端的请求并将请求发送到上游服务所消耗的时间值（毫秒）。

　　Kong-Upstream-Latency：<latency>，其中 latency 表示Kong等待上游服务响应的第一个字节所消耗的时间数（毫秒）。

　　　　当headers发送到客户端后，Kong将执行此API上已注册的、继承了body_filter的插件。body_filter将上游返回的数据成功处理后，然后再发送给客户端。

配置一个fallback API

　　默认情况下，当向KONG发送请求时，如果请求失败，KONG会返回 HTTP 404，“API not found” 等信息。为了避免这种情况的发生，我们可以通过配置 fallback API 实现自定义 “异常\错误” 信息。

　　下面是一个例子：

{
    "name": "root-fallback",
    "upstream_url": "http://www.error.page",
    "uris": ["/"]
}

　　观察此配置中的“uris”，会发现，此处配置“/”可以适配所有的请求，根据uris的匹配规则，每个请求都会首先匹配最长的uri，依次递减。所以当所有的uri都不匹配时，请求会自动转发到这里配置的上有服务中去，因此而实现了自定义 “异常\错误” 信息。

配置API的SSL

　　Kong提供了一种在每个连接的基础上动态提供SSL证书的方法。从0.10版本开始，SSL插件已被删除，SSL证书由内核直接处理，并可通过Admin API进行配置。你的客户端HTTP库必须支持SNI（Server Name Indication）扩展以确保SSL可用。

　　SSL证书由Kong Admin API的两个资源处理：

　　　　· /certificates　　存储您的密钥和证书。

　　　　· /snis　　将注册的证书与服务器名称指示相关联。

　　以下是为给定的API配置SSL证书的方法：

　　　　首先，通过Admin API上传SSL证书和密钥：

$ curl -i -X POST http://localhost:8001/certificates \
    -F "cert=@/path/to/cert.pem" \
    -F "key=@/path/to/cert.key" \
    -F "snis=ssl-example.com,other-ssl-example.com"
HTTP/1.1  Created
...

　　snis是加密参数，直接插入SNI并将上传的证书与之相关联。

　　您现在必须在Kong内注册以下API。为方便起见，我们将使用Host头将请求转发到此API：

$ curl -i -X POST http://localhost:8001/apis \
    -d "name=ssl-api" \
    -d "upstream_url=http://my-api.com" \
    -d "hosts=ssl-example.com,other-ssl-example.com"
HTTP/1.1  Created
...

　　好了，现在你可以向KONG发送HTTPs请求了：

$ curl -i https://localhost:8443/ \
  -H "Host: ssl-example.com"
HTTP/1.1  OK
...

　　1. https_only参数：

　　　　如果你希望仅通过HTTPS提供API，可以通过启用其https_only属性来实现：

$ curl -i -X POST http://localhost:8001/apis \
    -d "name=ssl-only-api" \
    -d "upstream_url=http://example.com" \
    -d "hosts=my-api.com" \
    -d "https_only=true"
HTTP/1.1  Created
...

　　　　这样配置后，KONG将拒绝代理非HTTPS的请求。如果此时使用HTTP请求来访问这个API，KONG会提示用户需要将客户端升级到HTTPS：

$ curl -i http://localhost:8000 \
    -H "Host: my-api.com"
HTTP/1.1
Content-Type: application/json; charset=utf-
Transfer-Encoding: chunked
Connection: Upgrade
Upgrade: TLS/1.2, HTTP/1.1
Server: kong/x.x.x

{"message":"Please use HTTPS protocol"}

　　2. http_if_terminated参数：

　　　　当API被锁定在HTTPS请求时，如果你想在请求头信息中添加X-Forwarded-Proto，只要为API配置http_if_terminated属性即可：

$ curl -i -X PATCH http://localhost:8001/apis/ssl-only-api \
    -d "http_if_terminated=true"
HTTP/1.1  OK
...

　　　　并且我们使用X-Forwarded-Proto（假设它来自可信任的客户端）发出请求：

$ curl -i http://localhost:8000 \
    -H "Host: my-api.com" \
    -H "X-Forwarded-Proto: https"
HTTP/1.1  OK
...

　　　　Kong现在代理了这个请求，因为它假定你的体系结构的先前组件已经实现了SSL。

代理WebSocket

　　由于KONG的底层实现了Nginx，所以他也支持WebSocket。如果你希望在客户端和KONG之间建议一个WebSocket连接，那么你必须首先建立一个WebSocket握手。这个通过HTTP Upgrade机制完成。这个可以通过客户端对KONG进行操作，例如：

GET / HTTP/1.1
Connection: Upgrade
Host: my-websocket-api.com
Upgrade: WebSocket

　　此时，KONG会将Connection和Upgrade两个请求头转发到上游服务中去。

小结

　　通过本指南，希望你了解了Kong的底层代理相关的知识，从API的uris匹配，到如何使用WebSocket协议、为API配置SSL。如果想了解更多的相关知识，请参考Nginx的负载平衡相关内容。