ApiSix全动态能力

谁践踏了优雅 2022-11-27 15:54 304阅读 0赞

## 一、前言： ##

*  [热更新和热插件][Link 1]: 无需重启服务，就可以持续更新配置和插件。
 *  [代理请求重写][Link 2]: 支持重写请求上游的`host`、`uri`、`schema`、`enable_websocket`、`headers`信息。
 *  [输出内容重写][Link 3]: 支持自定义修改返回内容的 `status code`、`body`、`headers`。
 *  [Serverless][]: 在 APISIX 的每一个阶段，你都可以添加并调用自己编写的函数。
 *  动态负载均衡：动态支持有权重的 round-robin 负载平衡。
 *  支持一致性 hash 的负载均衡：动态支持一致性 hash 的负载均衡。
 *  [健康检查][Link 4]：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
 *  熔断器: 智能跟踪不健康上游服务。
 *  [代理镜像][Link 5]: 提供镜像客户端请求的能力。

## 二、知识汇总 ##

### 2.1热更新和热插件 ###

APISIX 的插件是热加载的，不管你是新增、删除还是修改插件，都不需要重启服务。

只需要通过 admin API 发送一个 HTTP 请求即可：

curl http://127.0.0.1:9080/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT

### 2.2 代理请求重写proxy-rewrite（暂时未用） ###

上游代理信息重写插件。

配置参数

<table> 
 <thead> 
  <tr> 
   <th>名字</th> 
   <th>可选</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>scheme</td> 
   <td>可选</td> 
   <td>转发到上游的新&nbsp;<code>schema</code>&nbsp;协议，可以是&nbsp;<code>http</code>&nbsp;或&nbsp;<code>https</code>，默认&nbsp;<code>http</code>&nbsp;协议</td> 
  </tr> 
  <tr> 
   <td>uri</td> 
   <td>可选</td> 
   <td>转发到上游的新&nbsp;<code>uri</code>&nbsp;地址</td> 
  </tr> 
  <tr> 
   <td>regex_uri</td> 
   <td>可选</td> 
   <td>转发到上游的新&nbsp;<code>uri</code>&nbsp;地址, 使用正则表达式匹配来自客户端的uri，当匹配成功后使用模板替换转发到上游的uri, 未匹配成功时将客户端请求的uri转发至上游。当<code>uri</code>和<code>regex_uri</code>同时存在时，<code>uri</code>优先被使用。例如：["^/iresty/(.<em>)/(.</em>)/(.*)","/$1-$2-$3"] 第一个元素代表匹配来自客户端请求的uri正则表达式，第二个元素代表匹配成功后转发到上游的uri模板</td> 
  </tr> 
  <tr> 
   <td>host</td> 
   <td>可选</td> 
   <td>转发到上游的新&nbsp;<code>host</code>&nbsp;地址，例如：<code>iresty.com</code></td> 
  </tr> 
  <tr> 
   <td>headers</td> 
   <td>可选</td> 
   <td>转发到上游的新<code>headers</code>，可以设置多个。头信息如果存在将重写，不存在则添加。想要删除某个 header 的话，把对应的值设置为空字符串即可</td> 
  </tr> 
 </tbody> 
</table>

### 示例 ###

**开启插件**

下面是一个示例，在指定的 route 上开启了 `proxy rewrite` 插件:

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
        "methods": ["GET"],
        "uri": "/test/index.html",
        "plugins": {
            "proxy-rewrite": {
                "uri": "/test/home.html",
                "scheme": "http",
                "host": "iresty.com",
                "headers": {
                    "X-Api-Version": "v1",
                    "X-Api-Engine": "apisix",
                    "X-Api-useless": ""
                }
            }
        },
        "upstream": {
            "type": "roundrobin",
            "nodes": {
                "127.0.0.1:80": 1
            }
        }
    }'

**测试插件**

基于上述配置进行测试：

curl -X GET http://127.0.0.1:9080/test/index.html

发送请求，查看上游服务`access.log`，如果输出信息与配置一致：

127.0.0.1 - [26/Sep/2019:10:52:20 +0800] iresty.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107

即表示 `proxy rewrite` 插件生效了。

禁用插件

当你想去掉 `proxy rewrite` 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：

现在就已经移除了 `proxy rewrite` 插件了。其他插件的开启和移除也是同样的方法。

### 2.3输出内容重写 respinse-rewrite ###

该插件支持修改上游服务返回的 body 和 header 信息。

使用场景： 1、可以设置 `Access-Control-Allow-*` 等 header 信息，来实现 CORS (跨域资源共享)的功能。 2、另外也可以通过配置 status\_code 和 header 里面的 Location 来实现重定向，当然如果只是需要重定向功能，最好使用 [redirect][] 插件。

**配置参数**

<table> 
 <thead> 
  <tr> 
   <th>名字</th> 
   <th>可选</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>status_code</td> 
   <td>可选</td> 
   <td>修改上游返回状态码，默认保留原始响应代码。</td> 
  </tr> 
  <tr> 
   <td>body</td> 
   <td>可选</td> 
   <td>修改上游返回的&nbsp;<code>body</code>&nbsp;内容，如果设置了新内容，header 里面的 content-length 字段也会被去掉</td> 
  </tr> 
  <tr> 
   <td>body_base64</td> 
   <td>可选</td> 
   <td>布尔类型，描述&nbsp;<code>body</code>&nbsp;字段是否需要 base64 解码之后再返回给客户端，用在某些图片和 Protobuffer 场景</td> 
  </tr> 
  <tr> 
   <td>headers</td> 
   <td>可选</td> 
   <td>返回给客户端的&nbsp;<code>headers</code>，这里可以设置多个。头信息如果存在将重写，不存在则添加。想要删除某个 header 的话，把对应的值设置为空字符串即可</td> 
  </tr> 
 </tbody> 
</table>

## 示例 ##

### 开启插件 ###

下面是一个示例，在指定的 route 上开启了 `response rewrite` 插件:

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
        "methods": ["GET"],
        "uri": "/test/index.html",
        "plugins": {
            "response-rewrite": {
                "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
                "headers": {
                    "X-Server-id": 3,
                    "X-Server-status": "on"
                }
            }
        },
        "upstream": {
            "type": "roundrobin",
            "nodes": {
                "127.0.0.1:80": 1
            }
        }
    }'

### 测试插件 ###

基于上述配置进行测试：

curl -X GET -i  http://127.0.0.1:9080/test/index.html

如果看到返回的头部信息和内容都被修改了，即表示 `response rewrite` 插件生效了。

HTTP/1.1 200 OK
    Date: Sat, 16 Nov 2019 09:15:12 GMT
    Transfer-Encoding: chunked
    Connection: keep-alive
    X-Server-id: 3
    X-Server-status: on
    
    {"code":"ok","message":"new json body"}

### 2.4serverless ###

serverless 的插件有两个，分别是 `serverless-pre-function` 和 `serverless-post-function`， 前者会在指定阶段的最开始运行，后者是在指定阶段的最后运行。

这两个插件接收的参数都是一样的。

## Parameters ##

*  `phase`: 指定的运行阶段，没有指定的话默认是 `access`。允许的阶段有：`rewrite`、`access` `header_filer`、`body_filter`、`log` 和 `balancer` 阶段。
 *  `functions`: 指定运行的函数列表，是数组类型，里面可以包含一个函数，也可以是多个函数，按照先后顺序执行。

需要注意的是，这里只接受函数，而不接受其他类型的 Lua 代码。比如匿名函数是合法的：

return function()
        ngx.log(ngx.ERR, 'one')
    end

闭包也是合法的：

local count = 1
    return function()
        count = count + 1
        ngx.say(count)
    end

但不是函数类型的代码就是非法的：

local count = 1
    ngx.say(count)

## 示例 ##

### 启动插件 ###

下面是一个示例，在指定的 route 上开启了 serverless 插件:

curl -i http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
        "uri": "/index.html",
        "plugins": {
            "serverless-pre-function": {
                "phase": "rewrite",
                "functions" : ["return function() ngx.log(ngx.ERR, \"serverless pre function\"); end"]
            }
        },
        "upstream": {
            "type": "roundrobin",
            "nodes": {
                "39.97.63.215:80": 1
            }
        }
    }'

### 测试插件 ###

使用 curl 访问：

curl -i http://127.0.0.1:9080/index.html

然后你在 error.log 日志中就会发现 `serverless pre function` 这个 error 级别的日志， 表示指定的函数已经生效。

### 移除插件 ###

当你想去掉插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
        "methods": ["GET"],
        "uri": "/index.html",
        "upstream": {
            "type": "roundrobin",
            "nodes": {
                "39.97.63.215:80": 1
            }
        }
    }'

现在就已经移除了 serverless 插件了。其他插件的开启和移除也是同样的方法。

### 2.5 Upstream的健康检查 ###

[https://github.com/apache/apisix/blob/master/doc/zh-cn/health-check.md][Link 4]

[Link 1]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins.md
[Link 2]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins/proxy-rewrite.md
[Link 3]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins/response-rewrite.md
[Serverless]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins/serverless.md
[Link 4]: https://github.com/apache/apisix/blob/master/doc/zh-cn/health-check.md
[Link 5]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins/proxy-mirror.md
[redirect]: https://github.com/apache/apisix/blob/master/doc/zh-cn/plugins/redirect.md