開發插件的步驟

在APISIX中(zhong)，要自定義插件，一般需要按照以下步(bu)驟進行操作：

1. 編寫Lua腳本：首先，你(ni)(ni)需(xu)要編寫(xie)Lua腳本來實現你(ni)(ni)想要的(de)功能。可以根據APISIX提(ti)供的(de)插件開發文檔(dang)和示(shi)例進行(xing)編寫(xie)。

2. 將Lua腳本放置到APISIX插件目錄：將編寫好的Lua腳本文件放置到APISIX的插件目錄下，一般是/usr/local/apisix/lua-plugins/目錄。

3. 編輯配置文件：修改APISIX的配置文件，啟用自定義插件。在conf/config.yaml文件中添加對(dui)應的插件配置，指(zhi)定使(shi)用(yong)你編寫的Lua腳本。

4. 重啟APISIX服務：完成以上步驟后，記得重啟APISIX服務使配置生效，可以使用命令apisix restart來(lai)重啟APISIX。

5. 測試插件：在完成上述步驟后，你(ni)就可以通過發送請求測試你(ni)自定義(yi)的插件是否按(an)照預期工(gong)作(zuo)了。

總的(de)來說，自定義(yi)插(cha)件的(de)過程(cheng)主(zhu)要包括編(bian)寫Lua腳本、放置到插(cha)件目錄、編(bian)輯配置文件、重啟(qi)APISIX服務以及測試插(cha)件。詳細的(de)開發步驟和示例可以參考APISIX官(guan)方文檔。

多個plugins的配置,value.yaml中的配置

apisix:
  customPlugins:
    enabled: true
    luaPath: "/opt/?.lua"
    plugins:
      - name: "user-xx-auth"
        configMap:
          name: "apisix-plugins-config"
          mounts:
            - name: "user-xx-auth.lua"
              path: "/opt/apisix/plugins/" # 如果只有path參數，這塊到目錄級就可以了，配置中的文件自動復制到這個目錄下面
      - name: "file-upload-proxy"
        configMap:
          name: "apisix-plugins-config"
          mounts:
            - name: "file-upload-proxy.lua"
              path: "/opt/apisix/plugins/"

部署到k8s

如(ru)果你使用Helm將APISIX部署到Kubernetes中(zhong)，并且(qie)想要添加自定義插件(jian)，可以按(an)照以下步驟進行操作：

1. 編寫Lua腳本：首先，按照之前(qian)提到的步驟(zou)編寫Lua腳(jiao)本，實(shi)現你需要的功(gong)能(neng)。

2. 創建ConfigMap：將編寫好(hao)的Lua腳本內容放入一個ConfigMap中(zhong)，可以使用如下命(ming)令創(chuang)建一個ConfigMap：

   kubectl create configmap my-custom-plugin --from-file=my_plugin.lua
   

3. 修改Helm Chart模板：編輯APISIX的Helm Chart模板，找到對應的配置文件（一般是values.yaml或者configmap.yaml），在(zai)其中添(tian)加對應的ConfigMap配置，指定使用你(ni)的Lua腳本。

4. 升級APISIX部署：通過(guo)Helm命令升(sheng)級APISIX的部署，使新(xin)的ConfigMap生效：

 helm -n apisix upgrade apisix -f ./apisix/values.override.yaml ./apisix

5. 驗證插件：升級完成后，可以發送請求測試你自定義的插件是否按照預期工作了。

通過以(yi)(yi)上步驟，你(ni)就可(ke)以(yi)(yi)在使用Helm部署的APISIX中添加自定義插件。記得根據實際情況修改(gai)對應的文件路徑和配置項(xiang)，確保插件能(neng)夠(gou)成(cheng)功加載并發揮作用。

對dash board可見自定義插件

1 配置中添加插件

只有添加(jia)到(dao)配置文(wen)件中(zhong)(zhong)的插件才(cai)可以被apisix使用(yong)。在(zai)apisix 的conf 目(mu)錄的config.yaml 中(zhong)(zhong)有個plugins字(zi)段，將示例插件的插件名"insert-header"添加(jia)到(dao)該字(zi)段下。

2 裝載插件

需(xu)要對(dui)apisix 進行reload。直(zhi)接運行 apisix reload 就可以裝載插件

3 dashboard中添加插件

雖然apisix 提供了(le)管(guan)理接口可(ke)以通過接口的(de)方(fang)式給路由添(tian)加插件，但使用dashboard 操(cao)作會(hui)方(fang)便(bian)很多。

1、重(zhong)新生成(cheng)schema.json.

curl 127.0.0.1:9092/v1/schema > /usr/local/apisix/dashboard/conf/schema.json

2、重啟(qi)dashboard

kill -9
(ps -ef|grep "/usr/local/apisix/dashboard"|gawk '

OpenResty

OpenResty階段

在OpenResty中，階(jie)段（phase）指的(de)是請求(qiu)處(chu)理過程(cheng)中的(de)不(bu)同(tong)階(jie)段或(huo)環節。OpenResty基于Nginx并(bing)使(shi)用Lua語(yu)言進行擴展，通過定義不(bu)同(tong)的(de)階(jie)段可(ke)以在請求(qiu)處(chu)理過程(cheng)中插入自定義的(de)Lua代(dai)碼來實現各(ge)種功能。

在(zai)(zai)OpenResty中，請求(qiu)經過一系列預定義的(de)處(chu)理階(jie)(jie)段，每個階(jie)(jie)段都有(you)對應的(de)處(chu)理函(han)數，開(kai)發者(zhe)可以(yi)在(zai)(zai)這(zhe)些階(jie)(jie)段中編(bian)寫Lua代碼來實現各種功能，例如請求(qiu)重寫、訪(fang)問(wen)控制、日志記錄(lu)等。這(zhe)些階(jie)(jie)段可以(yi)被稱為(wei)請求(qiu)生(sheng)命周期中的(de)鉤子點(dian)，允許開(kai)發者(zhe)在(zai)(zai)特定的(de)時機(ji)執(zhi)行自定義邏輯。

常見(jian)的OpenResty階段包括：

• init_by_lua：在Nginx啟動時執行，用于初始化Lua代碼。
• init_worker_by_lua：在Worker進程啟動時執行，用于初始化Lua代碼。
• ssl_certificate_by_lua：用于SSL證書處理。
• rewrite_by_lua：用于請求重寫。
• access_by_lua：用于訪問控制。
• content_by_lua：用于生成響應內容。
• header_filter_by_lua：用于處理響應頭。
• body_filter_by_lua：用于處理響應體。

通過在不同階段(duan)插入(ru)Lua代碼(ma)，開發(fa)者可以實現高(gao)度定制化的(de)(de)請(qing)求處(chu)理邏(luo)輯，從而滿足(zu)各種需(xu)求，如API網關、反向代理、緩存控制等。因此，OpenResty的(de)(de)階段(duan)機(ji)制提供(gong)了靈(ling)活且(qie)強大的(de)(de)擴(kuo)展能(neng)力，使得開發(fa)者能(neng)夠更(geng)好地控制請(qing)求處(chu)理流程。

相關處理器方法

在APISIX中，這些_M開頭的(de)方(fang)法是OpenResty的(de)階段處(chu)理器，用于(yu)對(dui)請求(qiu)或(huo)響應進(jin)行處(chu)理。下(xia)面是它(ta)們各自的(de)作(zuo)用：

• _M.check_schema**：用于定義插件配置的校驗規則，可以確保插件配置符合預期的格式和類型。通過定義校驗規則，可以在配置插件時進行參數檢查，避免配置錯誤導致的問題。
• _M.header_filter：用于處理響應頭，在API響應返回給客戶端之前執行。
• _M.new：用于創建新的請求或響應對象，可以在此階段對請求或響應進行初始化操作。
• _M.incoming：用于處理請求體，在請求被路由到后端服務之前執行。
• _M.access：用于訪問控制，可以在此階段進行權限驗證、IP過濾等操作。
• _M.rewrite：用于重寫請求，可以在此階段修改請求的URI、參數等信息。
• _M.api()**：用于注冊插件的API接口，使得插件可以通過API方式被外部調用。通過定義API接口，可以讓插件暴露特定的功能給用戶使用，實現更加靈活的插件擴展和定制
  除了上述提到的預置方法外，APISIX還提供了其他一些預置的方法，例如：
• _M.balancer：用于負載均衡，可以在此階段選擇合適的后端節點進行請求轉發。
• _M.init_worker：用于初始化Worker進程，在啟動時執行一次，通常用于加載配置、初始化數據等操作。
• _M.log：用于日志記錄，可以在此階段記錄請求、響應信息到日志系統。

總結來說，APISIX通(tong)過(guo)這些(xie)預置(zhi)的方法（階(jie)段(duan)處(chu)理器）提供(gong)了(le)豐富的擴展點，開(kai)發(fa)者可(ke)以根據(ju)需求(qiu)在不(bu)同階(jie)段(duan)對請求(qiu)和響(xiang)應進行定(ding)制化處(chu)理，實(shi)現靈活的API網關功能(neng)。

一個完整的插件demo

• 向響應頭輸出X-Custom-Header頭

-- 定義一個 Lua 函數，用于處理請求
local core      = require("apisix.core")
local ngx = ngx
local ngx_encode_base64 = ngx.encode_base64
local ngx_decode_base64 = ngx.decode_base64
local ngx_time = ngx.time

local schema={} -- 注意，需要先定義它，再使用它

local _M={
    version=0.1,
    priority=1011,
    name = "lind-test",
    schema=schema
}

function _M.access(api_ctx)
    core.log.warn("hit access phase")
end


function _M.header_filter(ctx)
    core.log.warn("hit header_filter phase") -- 在apisix控制臺打印日志
    core.response.add_header("X-Custom-Header", "apisix-3.9.1")
end


function _M.body_filter(ctx)
    core.log.warn("hit body_filter phase")
end


function _M.log(ctx)
    core.log.warn("hit log phase")
end

-- 注冊插件
return _M

注冊插件

values.yaml

• 找到plugins節點，將現有的config-default.xml中的默認插件添加，避免自定義插件覆蓋默認插件的情況
• 默認插件列表獲取方式： 9180是apisix-admin的容器端口

plugins: ["real-ip","ai","client-control","proxy-control","request-id","zipkin","ext-plugin-pre-req","fault-injection","mocking","serverless-pre-function","cors","ip-restriction","ua-restriction","referer-restriction","csrf","uri-blocker","request-validation","chaitin-waf","multi-auth","openid-connect","cas-auth","authz-casbin","authz-casdoor","wolf-rbac","ldap-auth","hmac-auth","basic-auth","jwt-auth","jwe-decrypt","key-auth","consumer-restriction","forward-auth","opa","authz-keycloak","proxy-cache","body-transformer","proxy-mirror","proxy-rewrite","workflow","api-breaker","limit-conn","limit-count","limit-req","gzip","server-info","traffic-split","redirect","response-rewrite","degraphql","kafka-proxy","grpc-transcode","grpc-web","public-api","prometheus","datadog","loki-logger","elasticsearch-logger","echo","loggly","http-logger","splunk-hec-logging","skywalking-logger","google-cloud-logging","sls-logger","tcp-logger","kafka-logger","rocketmq-logger","syslog","udp-logger","file-logger","clickhouse-logger","tencent-cloud-cls","inspect","example-plugin","aws-lambda","azure-functions","openwhisk","openfunction","serverless-post-function","ext-plugin-post-req","ext-plugin-post-resp"]

values.override.yaml

• 添加自定義插件
• 通過ConfigMap的方式將插件內容放到配置文件中

apisix:
  admin:
    type: NodePort
    nodePort: 30087

  customPlugins:
    enabled: true
    luaPath: "/opt/?.lua"
    plugins:
      - name: "lind-test"
        configMap:
          name: "my-plugins-config"
          mounts:
            - key: "lind-test.lua"
              path: "/opt/apisix/plugins/lind-test.lua" #相當于把my-plugins-config下的lind-test.lua這個key，映射到容器下面/opts/custom_plugins目錄，apisix/plugins是相對目錄（是固定的），文件名還是lind-test.lua

向route添加自定義插件

• 目前在dashborad中無法看到自定義插件
• 在/apisix/admin/plugins/list中可以看到插件

curl //127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/test",
    "id": 1,
    "plugins": {
        "lind-test": {
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

訪問頁面

• 將test前綴的請求，轉發到upstream，真實地址是127.0.0.1的1980端口指向的服務
• 在瀏覽器的響應頭中，看到由lind-test插件添加的標識X-Custom-Header