Lua处理GitHub Webhook时ngx.req.get_body_data()返回nil问题排查

常见根因排查 #

• 最高发场景：请求体被Nginx缓存到磁盘临时文件
  ngx.req.get_body_data() 仅能读取存放在Nginx内存缓冲区的请求内容。默认配置下client_body_buffer_size通常仅为16k~32k，当GitHub推送的JSON载荷大小超过这个阈值时，Nginx会自动把超出的部分写入磁盘临时文件，内存中不会留存全量请求体，此时接口必然返回nil。
• 配置强制落盘
  如果Nginx配置中开启了client_body_in_file_only on，无论请求体大小都会被强制写入磁盘，同样会导致内存中无可用数据可读取。
• 调用时机错误
  若将这段读取逻辑放在header_by_lua、log_by_lua等非合法执行阶段调用ngx.req.read_body()，会因为阶段不匹配无法正确获取内存中的请求体。
• 无缓冲模式影响
  若开启了request_buffering off，Nginx不会对请求体做内存缓存，直接透传的模式下也无法通过上述接口读取完整内容。

落地解决步骤 #

第一步：调整Nginx配置，减少落盘场景 #

在Webhook对应的location块中补充配置，确保足够大的请求体可以直接存在内存中：

# 调整请求体缓冲区大小，足以容纳GitHub Webhook的最大载荷
client_body_buffer_size 1m;
# 放宽允许的最大请求体限制，匹配GitHub webhook的载荷上限
client_max_body_size 5m;
# 强制请求体存入内存单缓冲区，避免拆分写临时文件
client_body_in_single_buffer on;
# 关闭强制落盘开关
client_body_in_file_only off;
# 确保临时目录对Nginx进程有读写权限
client_body_temp_path /var/lib/nginx/body;

配置调整后重载Nginx，再次推送测试即可验证是否可以直接读到内存中的请求体。

第二步：增加代码兜底逻辑，兼容落盘场景 #

如果因为服务器性能、目录权限等原因不想把所有请求体都放内存，直接修改原有Lua代码，增加临时文件读取的兜底分支，避免依赖单一接口：

local method = ngx.var.request_method
local headers = ngx.req.get_headers()

if method == "POST" then
   ngx.req.read_body()
   local body_data = ngx.req.get_body_data()
   -- 内存中拿不到时，主动读取临时文件存储的请求体
   if not body_data then
       local body_tmp_path = ngx.req.get_body_file()
       if body_tmp_path then
           local fp = io.open(body_tmp_path, "r")
           if fp then
               body_data = fp:read("*a")
               fp:close()
           end
       end
   end
   -- 此时即可拿到完整的Webhook载荷
   ngx.print(body_data)
   local sha = headers['X-Hub-Signature-256']
end

第三步：校验执行阶段合法性 #

确认这段处理请求体的代码是挂载在access_by_lua或content_by_lua阶段，不要在过早/过晚的阶段调用，否则会出现逻辑失效。

额外注意点 #

• 不要在调用ngx.req.read_body()之前手动读取原始请求流，否则会清空内存中缓存的请求体内容。
• 检查client_body_temp_path对应目录的权限，确保Nginx运行用户有读写权限，临时文件生成失败也会导致请求体读取异常。

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