添加自定义插件
API7 网关的主要特性之一是其通过插件实现的可扩展性。除了广泛的现有插件外，API7 网关还允许你构建自定义插件，以添加额外功能并通过自定义流程管理 API 流量。通常，你会使用 Lua 编程语言来实现新插件。API7 网关分阶段处理请求，并在请求路由期间的每个阶段执行相关的插件逻辑。
前置条件
添加自定义插件
- 从侧边导航栏选择 Gateway Settings，然后选择 Custom Plugin。
- 点击 Add Custom Plugin。
- 在添加自定义插件对话框中，执行以下操作：
- Plugin Source Code File：上传自定义插件的源代码。
- Plugin Catalog：选择插件的目录，例如
General。 - Plugin Description：填写插件描述，例如
Replace the response body。 - Plugin Documentation Link：添加插件文档的 URL。
- Plugin Author：填写插件作者的姓名。
- Deployed Gateway Group：选择插件要部署到的网关组。为了安全发布，建议先只选择一个测试网关组，详见在网关组之间灰度发布。
- 点击 Add。
- 现在你的自定义插件已添加到插件列表中。它可以在 Add Plugin 对话框中被全局规则、服务、路由、消费者或插件选中。
以下是一个交互式演示，提供了添加自定义插件的实践 介绍。通过点击并按照步骤操作，你将更好地了解如何在 API7 企业版中使用它。
在网关组之间灰度发布
自定义插件按网关组下发。每个网关组都是一个隔离的配置作用域：部署到某个网关组的插件，对其他网关组内的路由或服务不可见。借助这种隔离，你可以在插件影响生产流量之前，先在非生产网关组中完成验证。
推荐的发布流程如下：
- 先部署到测试网关组。 添加插件时，在 Deployed Gateway Group 中只选择一个测试或预发网关组，插件将仅在该网关组内可用。
- 验证。 在测试网关组的某个路由上启用该插件，确认其行为符合预期。此时生产网关组尚未部署该插件，因此在你迭代期间不受影响。
- 推广到生产。 验证通过后，编辑该自定义插件，把生产网关组加入 Deployed Gateway Group。控制面会立即将插件下发到新选中网关组的网关实例。
修改部署范围的方式：进入 Gateway Settings 的 Custom Plugin 标签页，打开该 插件，更新 Deployed Gateway Group 后保存。
需要注意：
- 更新会同时作用于所有已部署的网关组。 上传新版本会同时更新该插件所在的全部网关组，不存在按网关组分别管理版本的能力。因此这套“先测试后推广”的流程能干净地适用于新插件。若要在插件已上生产后验证一次变更，请把它作为另一个唯一命名的插件、只部署到测试网关组，在那里验证通过后，再把该变更应用到生产插件上。
- 移除网关组会撤下插件。 如果该网关组内仍有路由引用此插件，它们可能会因此出错。请在确认没有任何配置依赖该插件后，再移除对应网关组。
- 插件名称全局唯一。 一个自定义插件是“一个命名对象 + 一组部署网关组”，而不是每个网关组一份拷贝。在整个发布过程中，请保持名称唯一且稳定。
添加依赖库
从 Dashboard 上传的自定义插件会被注册为一个独立、自包含的插件模块。控制面将其源代码下发到各网关并直接加载到运行时——文件不会写入网关的 Lua 模块搜索路径。因此，上传的自定义插件无法被另一个插件可靠地通过 require() 解析，你也不应把共享库作为自定义插件上传，再让其他插件去 require 它。这种用法初看可能正常，但在网关重启后会失效，因为无法再保证该依赖会先于依赖它的插件被加载。
当多个插件共享辅助代码，或某个插件依赖第三方 Lua 模块或原生（C）库时，应将该依赖安装到网关的包搜索路径上，再在插件中正常 require 它。
将依赖放到 Lua 或 C 路径
网关通过两个搜索路径解析模块：
- Lua 模块通过
lua_package_path解析。位于<dir>/myorg/utils.lua的文件用require("myorg.utils")加载。 - 原生 Lua/C 模块通过
lua_package_cpath解析。位于<dir>/myorg/native.so的文件用require("myorg.native")加载。
你可以使用网关内置路径，也可以使用自定义目录：
-
内置路径——将文件放到运行时的默认搜索路径下（例如
/usr/local/apisix/下），并使路径与你require的模块名匹配。 -
额外路径（推荐）——将你的代码与运行时分开存放，在数据面
config.yaml中添加你自己的目录：apisix:extra_lua_path: "/data/lua/?.lua" # 扩展 lua_package_pathextra_lua_cpath: "/data/clib/?.so" # 扩展 lua_package_cpath详见配置参考。
通过 LuaJIT FFI 的 ffi.load() 加载的原生库由系统动态链接器解析，而非 lua_package_cpath。这类库应放到系统库路径下（例如 /usr/local/lib），或在网关上设置 LD_LIBRARY_PATH。
让网关能访问到这些文件
依赖文件必须在网关启动前存在于每个网关节点上：
- Kubernetes / Helm——通过卷（例如 ConfigMap 或持久卷）将文件挂载进网关 Pod，并将
extra_lua_path/extra_lua_cpath指向挂载路径。 - Docker / Docker Compose——将目录绑定挂载进网关容器。
与由控制面动态下发的自定义插件不同，包搜索路径上的库在网关 worker 启动时加载。新增或修改这些文件后，需要重载或重启网关使其生效。
示例
将共享的辅助函数放到网关路径上的一个普通 Lua 模块中——例如 /data/lua/myorg/base.lua：
local _M = {}
function _M.verify(token)
-- 多个插件共用的逻辑
return token ~= nil
end
return _M
在数据面配置中添加该目录：
apisix:
extra_lua_path: "/data/lua/?.lua"
然后在任意自定义插件中 require 它：
local core = require("apisix.core")
local base = require("myorg.base")
-- ...
function _M.access(conf, ctx)
if not base.verify(core.request.header(ctx, "Authorization")) then
return 401
end
end
由于该模块位于包搜索路径上，require("myorg.base") 在每个 worker 上都以相同方式解析，并能在网关重启后继续生效。
附加资源
- 最佳实践
- 核心概念