使用 Lua 创建自定义插件

APISIX 的主要功能之一是其通过 插件 的可扩展性。除了各种现有插件外，APISIX 还允许你构建自定义插件以添加额外功能并使用自定义流程管理 API 流量。通常，你使用 Lua 编程语言来实现新插件。APISIX 分 阶段 处理请求，相关的插件逻辑在请求路由期间的每个阶段执行。

本指南将引导你完成为 APISIX 开发一个新的自定义 Lua 插件的示例过程。

前置条件

• 安装 Docker。
• 安装 cURL 以向服务发送请求进行验证。
• 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
• 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 ADMIN_API_KEY。请在 deployment.admin.admin_key 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

开发文件代理插件

在本节中，你将使用 Lua 为 APISIX 创建一个名为 file-proxy 的新自定义插件。此插件将用于通过 API 公开静态文件（YAML、JSON、JavaScript、CSS 或图像文件）并从指定的 URL 获取文件。 例如，API 用户可以通过指定的 URL http://127.0.0.1:9080/openapi.yaml 访问 openapi.yaml 文件。

创建 Lua 文件

为插件源代码创建一个名为 file-proxy.lua 的新 Lua 文件。

导入模块

为 file-proxy 插件导入必要的模块：

local core = require("apisix.core")
local io = require("io")
local ngx = ngx

定义插件名称

为插件声明一个唯一的名称：

local plugin_name = "file-proxy"

定义插件架构

为插件参数创建一个架构。架构定义了可用参数及其数据类型、属性、默认值、有效值等。

file-proxy 示例仅接受 /usr/local/apisix/openapi.yaml，也就是下文创建的公开规范文件。限制 Schema 可以避免通过路由配置暴露任意网关文件。请勿使用教程插件提供凭证或其他私有文件。

local plugin_schema = {
    type = "object",
    properties = {
        path = {
            type = "string",
            enum = {"/usr/local/apisix/openapi.yaml"}
        },
    },
    required = {"path"}
}

❶ 要服务的文件的路径。

❷ 路径设置为必需参数。

定义 Lua 模块表

为插件定义属性 version、priority、name 和 schema。name 和 schema 是之前定义的插件名称和架构。version 和 priority 由 APISIX 用于管理插件。

local _M = {
    version = 1.0,
    priority = 1000,
    name = plugin_name,
    schema = plugin_schema
}

❶ version：该字段通常是指当前正在使用的版本。如果你发布并更新你的插件逻辑，它将是 1.1（你可以设置你希望的任何版本）。

❷ priority：该字段用于在执行插件的每个阶段之前对插件进行排序。具有较高优先级的插件首先执行。确保自定义插件的优先级适合现有插件的优先级。现有插件的优先级记录在 config.yaml.example 文件中。

❸ name：插件的名称。

❹ schema：插件的架构。

定义架构检查函数

定义一个架构检查器以根据定义的架构验证用户输入的参数：

function _M.check_schema(conf)
  local ok, err = core.schema.check(plugin_schema, conf)
  if not ok then
      return false, err
  end
  return true
end

定义自定义逻辑

APISIX 允许你在各种 阶段 中注入自定义逻辑。请参阅 Lua NGINX 模块指令 以了解有关不同阶段的更多信息。

在 access 函数中实现 file-proxy 插件的自定义逻辑，该函数将在 access 阶段执行。逻辑应该打开插件配置中指定的文件，读取其内容，并将内容作为响应返回。如果文件无法打开，它应该记录错误并返回 404 Not Found。

function _M.access(conf, ctx)
  local fd = io.open(conf.path, "rb")
  if fd then
    local content = fd:read("*all")
    fd:close()
    ngx.header.content_length = #content
    ngx.say(content)
    ngx.exit(ngx.OK)
  else
    ngx.exit(ngx.HTTP_NOT_FOUND)
    core.log.error("File is not found: ", conf.path, ", error info: ", err)
  end
end

定义日志逻辑

log 函数在 log 阶段执行。日志记录是可选的，但有助于调试和检查插件是否正常工作。

仅记录该示例中已受约束的配置。不要转储请求上下文，因为其中可能包含凭证和其他私有请求数据：

function _M.log(conf, ctx)
    core.log.warn("conf: ", core.json.encode(conf))
end

组合所有内容

当你组合上面的所有代码时，file-proxy.lua 应该如下所示：

-- Introduce the necessary modules/libraries we need for this plugin
local core     = require("apisix.core")
local io       = require("io")
local ngx      = ngx

-- Declare the plugin's name
local plugin_name = "file-proxy"

-- Define the plugin schema format
local plugin_schema = {
    type = "object",
    properties = {
        path = {
            type = "string", -- The path of the file to be served
            enum = {"/usr/local/apisix/openapi.yaml"}
        },
    },
    required = {"path"} -- The path is a required field
}

-- Define the plugin with its version, priority, name, and schema
local _M = {
    version = 1.0,
    priority = 1000,
    name = plugin_name,
    schema = plugin_schema
}

-- Function to check if the plugin configuration is correct
function _M.check_schema(conf)
  -- Validate the configuration against the schema
  local ok, err = core.schema.check(plugin_schema, conf)
  -- If validation fails, return false and the error
  if not ok then
      return false, err
  end
  -- If validation succeeds, return true
  return true
end

-- Function to be called during the access phase
function _M.access(conf, ctx)
  -- Open the file specified in the configuration
  local fd = io.open(conf.path, "rb")
  -- If the file is opened successfully, read its content and return it as the response
  if fd then
    local content = fd:read("*all")
    fd:close()
    ngx.header.content_length = #content
    ngx.say(content)
    ngx.exit(ngx.OK)
  else
    -- If the file cannot be opened, log an error and return a 404 Not Found status
    ngx.exit(ngx.HTTP_NOT_FOUND)
    core.log.error("File is not found: ", conf.path, ", error info: ", err)
  end
end


-- Function to be called during the log phase
function _M.log(conf, ctx)
    -- Log the constrained plugin configuration
    core.log.warn("conf: ", core.json.encode(conf))
end

-- Return the plugin so it can be used by APISIX
return _M

加载自定义插件

有两种方法可以将自定义插件代码加载到 APISIX 中：

1. 将插件源代码放在默认的 APISIX 插件目录 /apisix/plugins 中，与其他 APISIX 插件放在一起。
2. 将插件源代码放在单独的目录中，并在 config.yaml 中的 extra_lua_path 中指定搜索路径。

以下部分提供了第二种方法的说明，因为建议在单独的目录中管理自定义代码。

Create Custom Plugin File

APISIX 在你的自定义目录中的 /apisix/plugins 中查找 L7 插件，在 /apisix/stream/plugins 中查找 L4 插件。

对于自定义插件，创建一个具有自定义名称的目录，并在该目录中创建 /apisix/plugins：

docker exec apisix-quickstart /bin/sh -c "mkdir -p custom-plugin/apisix/plugins"

将插件文件保存到该目录：

docker exec apisix-quickstart /bin/sh -c "echo '
local core     = require(\"apisix.core\")
local io       = require(\"io\")
local ngx      = ngx

local plugin_name = \"file-proxy\"

local plugin_schema = {
    type = \"object\",
    properties = {
        path = {
            type = \"string\",
            enum = {\"/usr/local/apisix/openapi.yaml\"}
        },
    },
    required = {\"path\"}
}

local _M = {
    version = 1.0,
    priority = 1000,
    name = plugin_name,
    schema = plugin_schema
}

function _M.check_schema(conf)
  local ok, err = core.schema.check(plugin_schema, conf)
  if not ok then
      return false, err
  end
  return true
end

function _M.access(conf, ctx)
  local fd = io.open(conf.path,\"rb\")
  if fd then
    local content = fd:read(\"*all\")
    fd:close()
    ngx.header.content_length = #content
    ngx.say(content)
    ngx.exit(ngx.OK)
  else
    ngx.exit(ngx.HTTP_NOT_FOUND)
    core.log.error(\"File is not found: \", conf.path, \", error info: \", err)
  end
end

function _M.log(conf, ctx)
    core.log.warn(\"conf: \", core.json.encode(conf))
end

return _M
' > /usr/local/apisix/custom-plugin/apisix/plugins/file-proxy.lua"

更新 APISIX 配置文件

将完整的当前配置文件复制到宿主机并保留备份：

docker cp apisix-quickstart:/usr/local/apisix/conf/config.yaml ./config.yaml
cp ./config.yaml ./config.yaml.backup

在 config.yaml 中现有的 apisix 映射下设置自定义插件搜索路径：

config.yaml（自定义插件搜索路径）

apisix:
  extra_lua_path: "/usr/local/apisix/custom-plugin/?.lua"

将 file-proxy 追加到完整的现有顶层 plugins 列表。如果当前配置文件省略了该列表，请先从此版本的配置示例中复制完整的默认列表，再追加 file-proxy。保留其他所有设置，尤其是 Admin API 白名单、身份验证和 etcd 连接设置。

警告

定义顶层 plugins 列表会替换默认列表。请勿配置仅包含 file-proxy 的单插件列表。

将候选配置复制到容器中并进行测试，仅在验证成功后重新加载 APISIX：

docker cp ./config.yaml apisix-quickstart:/usr/local/apisix/conf/config.yaml
docker exec apisix-quickstart apisix test && \
  docker exec apisix-quickstart apisix reload

如果验证失败，请先恢复备份，再进行其他更改：

docker cp ./config.yaml.backup apisix-quickstart:/usr/local/apisix/conf/config.yaml

测试自定义插件

存储测试文件

在 APISIX 实例中存储一个静态 openapi.yaml 文件：

docker exec apisix-quickstart /bin/sh -c "echo '
openapi: 3.0.1
info:
  title: OpenAPI Spec
  description: OpenAPI Spec file description.
' > /usr/local/apisix/openapi.yaml"

创建路由

要使用 file-proxy 自定义插件，你需要在 APISIX 中创建一个使用该插件的路由：

Admin API

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id":"openapi-file-proxy",
  "uri":"/openapi.yaml",
  "plugins":{
     "file-proxy":{
        "path":"/usr/local/apisix/openapi.yaml"
     }
  }
}'

ADC

adc.yaml

services:
  - name: OpenAPI File Proxy Service
    routes:
      - uris:
          - /openapi.yaml
        name: openapi-file-proxy
        plugins:
          file-proxy:
            path: /usr/local/apisix/openapi.yaml

将配置同步到 APISIX：

adc sync -f adc.yaml

验证插件

向路由发送请求：

curl "http://127.0.0.1:9080/openapi.yaml"

响应应该是 openapi.yaml 文件的内容：

openapi: 3.0.1
info:
  title: OpenAPI Spec
  description: OpenAPI Spec file description.

下一步

Lua开发自定义插件是扩展APISIX的一种方式. 从这里:

• 如需在不重新部署或重启 APISIX 的情况下检查插件运行时状态，请参阅设置断点。
• 如需使用 Lua 之外的语言编写插件，请参阅创建 WASM 插件。APISIX 还支持通过外部插件运行器执行 Go、Java 和 Python 插件。