版本：3.10.x

开发自定义 Lua 插件

自定义 Lua 插件可以在请求/响应生命周期的不同阶段执行自定义逻辑，从而扩展 API7 网关功能。本指南将带你创建一个简单的 Lua 插件，在 API7 网关中注册该插件，并将其应用到路由。

前置条件

具备 Lua 编程语言基础知识。
熟悉 OpenResty 和 NGINX 请求生命周期。
能够访问 API7 网关实例及其控制台。
从控制台获取 Token。

插件结构

Lua 插件是一个导出 table 的模块，其中包含配置 Schema、优先级和阶段处理函数。

标准字段

每个插件都应定义以下字段：

name：插件的唯一名称。
version：插件版本。
priority：决定同一阶段内插件的执行顺序，优先级越高越先执行。
schema：定义插件配置参数的 JSON Schema。

执行阶段

API7 网关先完成路由匹配，然后执行该路由上配置的插件。路由匹配和插件的 rewrite 阶段都发生在 NGINX 的 access 处理过程中。即使请求未匹配任何路由，全局规则仍可能执行，随后网关返回 404。

之后，API7 网关按以下顺序执行插件阶段：

rewrite：路由匹配后的第一个插件阶段。可以修改发往上游的请求，例如 URI 或请求头，但不会使 APISIX 重新匹配路由。
access：主要处理阶段，例如身份认证和限流。
before_proxy：在 access 阶段之后、请求代理到上游之前执行。
header_filter：修改响应头。
body_filter：修改响应体。
log：响应发送给客户端后记录日志。

分步开发

1. 创建插件文件

为插件新建 Lua 文件。本示例使用名为 custom-header 的插件。

2. 定义 Schema 和优先级

使用 apisix.core 根据 JSON Schema 校验插件配置。

local core = require("apisix.core")

local schema = {
    type = "object",
    properties = {
        header_name = {
            type = "string",
            default = "X-Custom-Lua"
        },
        header_value = {
            type = "string",
            default = "loaded"
        }
    }
}

local plugin_name = "custom-header"

local _M = {
    version = 0.1,
    priority = 1500,
    name = plugin_name,
    schema = schema,
}

function _M.check_schema(conf)
    return core.schema.check(schema, conf)
end

3. 实现阶段处理函数

在适当阶段实现逻辑。若要在请求到达上游前添加请求头，请使用 access 阶段。

function _M.access(conf, ctx)
    core.request.set_header(ctx, conf.header_name, conf.header_value)
end

4. 完整插件示例

以下是 custom-header 插件的完整代码：

local core = require("apisix.core")

local schema = {
    type = "object",
    properties = {
        header_name = {
            type = "string",
            default = "X-Custom-Lua"
        },
        header_value = {
            type = "string",
            default = "loaded"
        }
    }
}

local plugin_name = "custom-header"

local _M = {
    version = 0.1,
    priority = 1500,
    name = plugin_name,
    schema = schema,
}

function _M.check_schema(conf)
    return core.schema.check(schema, conf)
end

function _M.access(conf, ctx)
    core.request.set_header(ctx, conf.header_name, conf.header_value)
end

return _M

在 API7 网关中注册插件

在 API7 网关中，自定义插件由控制面管理。通过控制台上传单个 Lua 文件或 ZIP 软件包，即可让该插件供对应网关组中的路由、服务、消费者和全局规则使用。

1. 在控制台中添加插件

自定义插件属于上传到的那个网关组。在控制台中打开需要运行该插件的网关组，进入 Custom Plugins，然后点击 Add Custom Plugin。

对于单文件示例，请上传 Lua 源文件并提供所需插件元数据：

Plugin Source Code File：上传 custom-header.lua。
Plugin Description：简要说明插件功能。
Plugin Documentation Link：可选，填写插件文档链接。
Plugin Author：标明插件所有者。

文件上传成功后，API7 网关会解析插件，并在添加前于对话框显示检测到的 name 和 version。

添加插件后，可以在该网关组的路由和服务 新增插件 对话框中选择它。若要在其他网关组中运行，请同样上传到该组，详见跨网关组发布。

有关产品操作流程，请参阅自定义插件。

3.10.6 之前，自定义插件在 Gateway Settings 中按控制面统一管理，由 Deployed Gateway Group 字段决定分发到哪些网关组。升级前已存在的插件会被迁移到它当时部署的每一个网关组中。

2. 确认插件可用

在该网关组中打开路由或服务，确认 新增插件 对话框中出现 custom-header。

打包私有 Lua 依赖

API7 网关 3.10.5 及更高版本支持使用 ZIP 软件包分发私有 Lua 依赖。控制面会把入口文件与依赖模块作为一个整体进行验证和分发，因此网关无需重启即可加载该软件包。在更早的 3.10.x 版本中，请使用单文件插件，或按照添加共享库或原生库中的说明在网关文件系统中安装依赖。

按如下方式组织归档，其中顶层入口文件名和依赖目录必须与插件的 name 一致：

custom-header.lua
custom-header/
└── validation.lua
metadata.json

入口文件可以通过 require("apisix.plugins.custom-header.validation") 加载依赖。在 metadata.json 中写入与插件声明一致的 name、version 和 schema，并包含控制台元数据：

metadata.json
{
  "name": "custom-header",
  "version": "0.1",
  "catalog": "General",
  "description": "Adds a configured header to the upstream request.",
  "documentation_link": "https://docs.example.com/custom-header",
  "author": "Acme Platform Team",
  "schema": {
    "type": "object",
    "properties": {
      "header_name": {
        "type": "string",
        "default": "X-Custom-Lua"
      },
      "header_value": {
        "type": "string",
        "default": "loaded"
      }
    }
  }
}

在包含这些文件的目录中创建归档：

zip -r custom-header.zip custom-header.lua custom-header metadata.json

将 custom-header.zip 作为 Plugin Source Code File 上传。更新软件包会替换该网关组中的插件代码及其私有依赖。

软件包只应用于某个插件专用的 Lua 源码依赖。软件包加载器会忽略非 Lua 依赖文件，也不会安装 LuaRocks 或原生库。

添加共享库或原生库

不要把共享库作为单独的自定义插件上传，以供其他插件 require。上传的插件不会安装到网关的常规 Lua 模块搜索路径，而且一个插件不能依赖另一个插件先行加载。

有些插件会共享辅助代码，或依赖第三方 Lua 模块或原生 C 库。请将依赖安装到网关的包路径，并像往常一样在插件中 require。

将依赖放到 Lua 或 C 路径

网关通过两类搜索路径解析模块：

Lua 模块通过 lua_package_path 解析。可使用 require("myorg.utils") 加载 <dir>/myorg/utils.lua。
原生 Lua/C 模块通过 lua_package_cpath 解析。可使用 require("myorg.native") 加载 <dir>/myorg/native.so。

可以使用网关内置路径或自定义目录：

内置路径：将文件放到网关内置搜索路径（例如 /usr/local/apisix/），并与 require 的模块名保持一致。
额外路径（推荐）：将代码与运行时分离，并在数据面 config.yaml 中添加自定义目录：
```
apisix:
  extra_lua_path: "/data/lua/?.lua"     # 扩展 lua_package_path
  extra_lua_cpath: "/data/clib/?.so"    # 扩展 lua_package_cpath
```
详情请参阅API7 网关数据面配置参考和配置文件。

备注

通过 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 上的解析方式相同，网关重启后仍然有效。

测试插件

在 API7 网关中注册插件后，可以使用 Admin API 或 ADC 在路由上启用它。控制面会将插件源代码分发到网关节点。

创建启用该插件的路由：

Admin API
ADC

curl -k "https://localhost:7443/apisix/admin/services/custom-header-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-header-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/custom-header-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-header-route",
    "methods": ["GET"],
    "paths": ["/get"],
    "service_id": "custom-header-service",
    "plugins": {
      "custom-header": {
        "header_name": "X-Trace-ID",
        "header_value": "docs-test"
      }
    }
  }'

adc.yaml
services:
  - name: custom-header-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: custom-header-route
        uris:
          - /get
        plugins:
          custom-header:
            header_name: X-Trace-ID
            header_value: docs-test
    labels:
      docs-example: custom-header-service

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=custom-header-service

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=custom-header-service

发送请求并验证上游响应体中的请求头：

curl -i "http://localhost:9080/get"

httpbin 响应的 headers 中应包含 X-Trace-ID: docs-test，这表明插件在代理前修改了请求。

如果路由创建后代理立即返回 404 Route Not Found，请等待几秒后重试。

跨网关组发布

自定义插件属于某一个网关组。每个网关组都是隔离的配置范围：上传到一个组的插件无法供其他组的路由或服务使用，各个组运行的都是各自上传的代码。借助这种隔离，可在插件（或插件的某次改动）影响生产流量前先在非生产组中验证。

推荐的发布流程如下：

**上传到测试网关组。**打开测试或预发布网关组并在其中添加插件，插件只对该组可用。
**验证。**按照测试插件在测试组的路由上启用插件并确认行为符合预期。生产组尚无该插件，因此迭代期间不受影响。
**发布到生产环境。**验证完成后，把同一个文件上传到生产网关组。控制面会立即把它分发到该组的网关，其他网关组不受影响。

已经在生产环境运行的插件同样按这个流程更新：先把新代码上传到测试组，此时生产组继续运行原有代码；验证通过后再上传到生产组。两份代码不需要使用不同的插件名，路由、服务和 plugin_metadata 中的引用始终保持不变。

请注意：

**一次上传只替换该网关组中的代码。**上传到测试组不会改变生产组运行的内容，反之亦然。
**删除只是从该网关组移除插件。**如果该组中的路由仍引用插件，删除会被拒绝，直到不再引用为止；其他网关组仍保留各自的副本。
**插件名称在网关组内唯一，而非控制面全局唯一。**两个网关组可以使用同名但互不相关的插件，因此发布过程中请保持名称稳定，并在各环境中把同一名称视为同一个插件。

自 API7 企业版 3.10.6 起可用。在此之前，自定义插件是带有一组部署网关组的控制面级对象，上传新代码会同时更新所有这些网关组。

3.10.6 之前，控制面还只按名称查找自定义插件：路由可以引用本网关组并不具备的插件，而网关从未运行过该插件。从 3.10.6 起，保存这类资源会被拒绝，需要把插件上传到该网关组，或从配置中移除该插件。

调试提示

检查错误日志：日志默认位于 /usr/local/apisix/logs/error.log。
语法错误：上传前使用 luac -p custom-header.lua 检查 Lua 语法。
插件可见性：如果控制台插件列表中未出现该插件，请确认它已上传到你正在配置的那个网关组。
Admin API 载荷结构：API7 网关创建路由时使用 paths 和 service_id，而不是 APISIX 风格的顶层 uri 和内联 upstream。
名称冲突：确保插件名称唯一且不与内置插件冲突。

后续步骤

插件开发最佳实践——编写正确、高效且易维护的插件代码。
Serverless 函数还是自定义插件——为用例选择合适的扩展机制。
插件——了解插件执行顺序和作用域。

前置条件​

插件结构​

标准字段​

执行阶段​

分步开发​

1. 创建插件文件​

2. 定义 Schema 和优先级​

3. 实现阶段处理函数​

4. 完整插件示例​

在 API7 网关中注册插件​

1. 在控制台中添加插件​

2. 确认插件可用​

打包私有 Lua 依赖​

添加共享库或原生库​

将依赖放到 Lua 或 C 路径​

让网关能够访问文件​

示例​

测试插件​

跨网关组发布​

调试提示​

后续步骤​