APISIX 的 proxy-cache 插件可以对上游的查询进行缓存,这样就不需要上游的应用服务自己实现缓存了,或者也能少实现一部分缓存,通用的交给插件来做。
下面的操作都是基于 APISIX 3.2 版本进行配置,关于 proxy-cache 的详细配置的可以参考文档:https://apisix.apache.org/docs/apisix/3.2/plugins/proxy-cache/ 不过文档很多地方说的不是太清楚,这里把重点的地方补充一下,首先是插件的参数:
- cache_strategy 这个表示我们插件的缓存策略,支持配置 disk 或 memory,默认是 disk
- cache_zone 这个表示我们使用的存储区域,对于内存或者磁盘都可以详细配置,这个需要在配置文件中进行配置。
- cache_key 这个是我们要缓存请求的 key,key 是判断是否缓存的依据,可以指定多个 APISIX 或者 nginx 的变量,也可以指定常量字符串。需要注意的是不是所有的变量都可以使用,比如 request_body 变量就是不能使用的,因为如果 body 太大,上下文传递会有比较大的开销,所以设置了结果也是空的。
- cache_bypass 这个指定不进行缓存的情况,也是一个数组,可以写多个变量,如果至少有 1 个变量的不为空并且不等于 0,那么就会跳过缓存。这个配置不太好理解,具体是什么变量并没有说,通过查看插件源码发现取的是 ctx.var 中的值,所以其实这个并不是请求的 URL 参数,也不是请求的 Header 内容,而是 APISIX 里面的变量,当然也包括 nginx 的变量,当变量存在时就会自动绕过请求,如果内置变量不满足要求,我们可以通过实现自定义变量来解决。
- cache_method 这个好理解,就是哪些方法会被缓存,可以指定一个数组。
- cache_http_status 这个表示上游的哪些状态码会被缓存,也是一个数组。
- hide_cache_headers 如果设置为 true,会将响应的 Expires 和 Cache-Control 头响应到客户端中,默认是会去掉的。
- cache_control 如果设置为 true,将按照 HTTP 规范中的行为进行缓存,这个仅对于内存策略生效。
- no_cache 这个和 cache_bypass 非常类似,同样是配置一个变量列表,不过这个是在响应阶段处理,也就是上游服务主动告诉 APISIX 这个请求是否缓存,变量的含义和上面一样,支持内置变量和自定义变量。
- cache_ttl 缓存的过期时间,单位是秒,当上面的 cache_control 未启用或者服务器未返回缓存控制头时生效,如果启动了 cache_control 则以响应的控制头为准,同样这个仅对内存策略生效。
根据官网的说明,有下面的几点需要注意:
- 如果是基于磁盘的缓存,无法在插件中设置过期时间,默认就是 10s,但是可以通过服务的响应头 Expires 和 Cache-Control 设置过期时间。
- 如果上游服务不可用时,那么 APISIX 会返回 502 和 504 状态码,这个时候缓存时间是默认的 10s。
- 在 cache_key, cache_bypass 以及 no_cache 中指定的变量,如果变量值不存在,则结果为空字符串。如果其中写了常量,结果会将变量值和常量一块拼接起来。
开启插件之前,首先需要在本地配置文件添加缓存区域的配置,否则启用插件以及后续调用时会报错,首先编辑 config.yaml
添加配置如下:
yaml
apisix:
# ...
proxy_cache:
# 磁盘缓存时间 默认是 10s,可以在这里修改
cache_ttl: 10s
zones:
# 磁盘的 cache_zone 的名称
- name: disk_cache_one
# 索引需要在内存中存储,设置内存的大小限制
memory_size: 50m
# 磁盘缓存的大小限制
disk_size: 1G
# 缓存文件的路径
disk_path: "/tmp/disk_cache_one"
# 缓存级别配置
cache_levels: "1:2"
# 内存的 cache_zone 名称
- name: memory_cache_one
# 内存缓存的大小限制
memory_size: 512m
上面就分别配置了磁盘和内存的 cache_zone 当然可以配置多个,比如大小限制不一样或者存储路径不一样,针对于不同插件的配置。再比如我们这里只使用内存作为缓存,所以也可以不配置磁盘的。总之,插件中需要用到的配置,在配置文件中必须找得到才可以,修改好之后我们保存配置,然后重启 APISIX 服务。
我们这里打算通过自定义一个 header 头来判断请求是否走缓存,由于变量在 APISIX 或 nginx 的内置变量中不存在,所以我们编写一个自定义变量的插件来解决,插件内容如下:
lua
--
-- Licensed to the Apache Software Foundation (ASF) under one or more
-- contributor license agreements. See the NOTICE file distributed with
-- this work for additional information regarding copyright ownership.
-- The ASF licenses this file to You under the Apache License, Version 2.0
-- (the "License"); you may not use this file except in compliance with
-- the License. You may obtain a copy of the License at
--
-- http://www.apache.org/licenses/LICENSE-2.0
--
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--
local ngx = ngx
local core = require("apisix.core")
local plugin = require("apisix.plugin")
local schema = {
type = "object",
properties = {
name = {type = "string"},
label = {type = "integer"}
},
required = {"name"},
}
local plugin_name = "custom-vars"
local _M = {
version = 0.1,
priority = 99,
name = plugin_name,
schema = schema,
}
defined_var_names = {"custom_username", "cache_bypass"}
core.ctx.register_var("custom_username", function(ctx)
return get_custom_username()
end)
core.ctx.register_var("cache_bypass", function(ctx)
local bypass = core.request.header(ctx, "cache-bypass")
if not bypass then
return ""
end
return bypass
end)
function get_custom_username()
local req_headers = ngx.req.get_headers()
local username = req_headers.user
if username ~= "" then
return username
end
return nil
end
function _M.check_schema(conf, schema_type)
if schema_type == core.schema.TYPE_METADATA then
return core.schema.check(metadata_schema, conf)
end
return core.schema.check(schema, conf)
end
function _M.init()
-- call this function when plugin is loaded
local attr = plugin.plugin_attr(plugin_name)
if attr then
core.log.info(plugin_name, " get plugin attr val: ", attr.val)
end
end
function _M.destroy()
-- call this function when plugin is unloaded
end
-- sorted phase:
-- rewrite -> access -> before_proxy -> header_filter -> body_filter -> delayed_body_filter -> log
function _M.rewrite(conf, ctx)
-- core.log.warn("plugin rewrite phase, conf: ", core.json.encode(conf))
-- core.log.warn("plugin rewrite phase, ctx: ", core.json.encode(ctx, true))
-- core.log.warn("plugin rewrite phase, username: ", get_username())
end
function _M.access(conf, ctx)
-- core.log.warn("plugin access phase, conf: ", core.json.encode(conf))
-- core.log.warn("plugin access phase, ctx: ", core.json.encode(ctx, true))
-- core.log.warn("plugin access phase, ngx headers: ", core.json.encode(ngx.req.get_headers()))
end
function _M.before_proxy(conf, ctx)
-- After access and before the request goes upstream
end
function _M.header_filter(conf, ctx)
-- Response header filter
end
function _M.body_filter(conf, ctx)
-- Response body filter
end
function _M.delayed_body_filter(conf, ctx)
-- delayed_body_filter is called after body_filter
-- it is used by the tracing plugins to end the span right after body_filter
end
function _M.log(conf, ctx)
-- Log processing after response
end
local function list_vars()
local args = ngx.req.get_uri_args()
if args["json"] then
return 200, defined_var_names
else
return 200, table.concat(defined_var_names, "\n") .. "\n"
end
end
function _M.control_api()
return {
{
methods = {"GET"},
uris = {"/v1/plugin/custom-vars"},
handler = list_vars,
}
}
end
return _M
这里插件名称我们叫 custom-vars
,是专门注册自定义变量的插件,我们注册了 custom_username
和 cache_bypass
这两个变量,并且添加了 Control API,我们将源码保存为 custom-vars.lua
并放到 APISIX 的 plugins
目录下,然后在配置文件中添加插件,如果之前没有添加过需要复制 config-default.yaml
中所有的插件,然后再补充上我们的插件。
具体如何加载插件可以参考之前写过的插件开发的文章。
由于我们在插件中注册了全局变量,只要插件被加载就可以,我们无需使用它也可以使用其中的自定义变量,但是假如我们要访问插件的 Control API 那么则必须在某个路由上启用插件。
使用专门的自定义变量插件的好处是我们不需要修改 proxy-cache 的源码在里面注册变量,这样假如 APISIX 升级了并且 proxy-cache 的源码有所变化我们也不需要再进行更新,只需要加入我们的 custom-vars 插件即可,对 APISIX 原有插件不会有任何影响,也是为了解耦。
加入插件后不要忘记重启 APISIX,然后我们来添加一个路由:
bash
curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/100 \
-H 'X-API-KEY: <api-key>' -d '
{
"uri": "/hello",
"name": "示例路由",
"plugins": {
"custom-vars": {
"name": "vars"
},
"proxy-cache": {
"cache_bypass": [
"$cache_bypass"
],
"cache_control": false,
"cache_http_status": [
200
],
"cache_key": [
"$uri",
"-cache-id"
],
"cache_method": [
"GET",
"PURGE"
],
"cache_strategy": "memory",
"cache_ttl": 30,
"cache_zone": "memory_cache_one",
"hide_cache_headers": false
}
},
"upstream": {
"nodes": [
{
"host": "10.0.1.12",
"port": 1980,
"weight": 1
}
],
"type": "roundrobin",
"hash_on": "vars",
"scheme": "http",
"pass_host": "pass"
},
"status": 1
}'
现在我们就添加了路由,然后我们访问路由添加 -i
参数就可以看到 APISIX 响应的字段,比如:
shell
curl localhost:9080/hello -i
第一次会看到 APISIX-Cache-Status: MISS
因为数据未缓存,然后再次请求就可以看到 APISIX-Cache-Status: HIT
表示缓存已经命中,同时会返回 Age
响应头,表示当前缓存的存活时间,当时间超过 TTL 时,缓存就会被删除。
然后我们也可以选择不使用缓存,比如:
shell
curl localhost:9080/hello -i -H 'Cache-Bypass: 1'
这时候我们会看到 APISIX-Cache-Status: BYPASS
表示没有使用缓存,而是直接请求上游服务。
假如我们要缓存 POST 之类的请求,那么这个时候 $request_body
肯定也要作为 cache_key 的一部分,但是这个时候上下文中又没有这个变量,那么怎么办呢?可以换一种方式,由于 $request_body
本身可能比较大,我们可以使用它做一个 Hash,只要请求体内容不变,那么 Hash 结果也是确定的,而且缓存的 key 也比较小,由于同时有 $uri
进行区分,选用 md5 这样的函数完全够了,碰撞的概率也是极小的,我们可以在上面插件中注册一个标识请求体的变量,比如:
lua
core.ctx.register_var("request_body_uuid", function(ctx)
local body = core.request.get_body()
if not body then
return ""
end
return ngx.md5(body)
end)
这样我们就可以使用 $request_body_uuid
这样的变量的,那么我们在创建路由的时候 cache_key 配置如下:
json
{
"cache_key": [
"$uri",
"$request_body_uuid"
]
}
这样就可以缓存 POST 请求了,如果要缓存带参数的 GET 请求可以将 $uri
变量替换为 $request_uri
变量,后者是包含参数并且未规范化的。
最后我们还可以删除路由的缓存,使用 HTTP 的 PURGE 方法发起请求:
shell
curl localhost:9088/hello -X PURGE -i
如果成功删除缓存会返回 200 OK,否则如果不存在缓存则会返回 404,但是前提路由配置中一定要允许 PURGE 方法,我们上面创建时就指定了,如果不指定则无法使用上面的命令删除缓存,并且启用了之后这个请求也是用于 APISIX 删除缓存,并不会请求上游的服务。
另外下面会给出 OpenResty 中两个 Lua 模块的仓库,其中有很多好用的函数可以参考,并且由于 APISIX 是基于 OpenResty 的,所以在 APISIX 插件开发中都是可用的。
Reference: