Docker部署Kong：自定义头部验证插件未显示于插件列表求助

问题背景 #

使用Docker运行Kong，开发了一个验证请求头Key值为Test123的自定义插件，执行以下操作后插件未显示在插件列表中：

• 将插件目录custom-plugin复制到容器内/usr/local/share/lua/5.1/kong/plugins路径
• 将修改后的kong.conf（添加plugins = bundled,custom-plugin）复制到容器/usr/local/etc/kong路径
• 重启容器

自定义插件代码（修正后） #

handler.lua

local kong = kong
local CustomPlugin = {
  PRIORITY = 1000,
  VERSION = "0.1",
}

function CustomPlugin:access(conf)
  -- 验证请求头
  local header_value = kong.request.get_header("Key")
  if header_value ~= "Test123" then
    return kong.response.exit(401, { message = "Unauthorized: Invalid or missing 'Key' header" })
  end

  kong.log.debug("Header validation passed. Continuing to the upstream service.")
end

return CustomPlugin

schema.lua

local typedefs = require "kong.db.schema.typedefs"

return {
  name = "custom-plugin",
  fields = {
    { config = {
      type = "record",
      fields = {}
    } }
  }
}

解决步骤 #

1. 检查插件目录结构 #

容器内插件必须放在正确的路径下，且目录包含核心文件：

# 验证目录结构
docker exec c3b65b77458c ls -l /usr/local/share/lua/5.1/kong/plugins/custom-plugin/

需确保输出包含handler.lua和schema.lua，若结构错误重新复制：

docker cp ./custom-plugin/ c3b65b77458c:/usr/local/share/lua/5.1/kong/plugins/

2. 修复代码中的语法错误 #

原代码存在中文符号问题（中文引号、中文注释符），Lua解释器无法识别，需全部替换为英文符号：

• 字符串引号替换为英文双引号"或单引号'
• 注释符号替换为英文破折号--
• 移除无意义的CustomPlugin.super.access(self)调用（该插件未继承基类，调用会触发报错）

3. 验证kong.conf配置生效 #

确认容器内配置文件的plugins项正确：

docker exec c3b65b77458c grep "plugins =" /usr/local/etc/kong/kong.conf

正确输出应为：plugins = bundled,custom-plugin

4. 正确重载Kong配置 #

直接重启容器可能无法触发插件重新加载，优先使用Kong内置重载命令：

docker exec c3b65b77458c kong reload

若需重启容器：

docker restart c3b65b77458c

5. 验证插件加载状态 #

查看已加载插件列表：

docker exec c3b65b77458c kong plugins list

若仍未显示，查看日志定位错误：

docker logs c3b65b77458c | grep -i "custom-plugin"

内容的提问来源于stack exchange，提问作者bics siva