ngx_lua_waf模块安装与配置深度指南

一、什么是ngx_lua_waf？
ngx_lua_waf是基于Nginx和Lua开发的轻量级Web应用防火墙（WAF），通过Lua脚本实现DDoS防护、SQL注入拦截、XSS攻击检测等功能。其核心优势在于：

高性能：基于Nginx的事件驱动架构，低资源消耗。
灵活性：通过修改Lua脚本可自定义规则。
轻量级：无需额外数据库或中间件。


? 重要提示：需结合Nginx和Lua模块（如 lua-nginx-module）使用。


二、安装依赖与前置条件
1. 安装Nginx与LuaJIT
sudo apt update && sudo apt install nginx lua5.1 liblua5.1-0-dev
​
解释：

nginx：Web服务器核心。
lua5.1：Lua解释器（基础依赖）。
liblua5.1-0-dev：Lua开发库，用于编译依赖模块。

2. 安装Nginx的Lua模块
# 安装Lua扩展模块（如lua-nginx-module和NDK）
sudo apt install libnginx-mod-http-lua
​
解释：

libnginx-mod-http-lua：提供Nginx与Lua的交互支持，是ngx_lua_waf的必需依赖。
若未安装，后续模块加载会报错。


三、下载与配置ngx_lua_waf
1. 获取模块源码
# 推荐使用GitHub最新分支（原仓库可能迁移）
git clone https://github.com/your-repo/ngx_lua_waf.git  # 替换为实际仓库地址
cd ngx_lua_waf
​
解释：

直接使用 git clone比下载zip包更稳定，可获取最新版本。
若原仓库地址变更，需查找官方维护仓库（如GitHub或Gitee）。

2. 备份并复制模块文件
sudo cp -r ./* /usr/share/nginx/modules/  # 假设Nginx模块目录为/usr/share/nginx/modules
​
解释：

cp -r递归复制所有Lua脚本和配置文件。
重要路径：/usr/share/nginx/modules/需替换为实际模块目录（通过 nginx -V查看编译参数中的 --add-module路径）。


四、配置Nginx加载WAF模块
1. 修改 nginx.conf
http {
    # 设置Lua模块搜索路径
    lua_package_path "/usr/share/nginx/modules/?.lua;;";  # 替换实际路径

    server {
        listen 80;
        server_name your_domain.com;

        # 加载WAF入口脚本
        location / {
            access_by_lua_file /usr/share/nginx/modules/waf.lua;
            # 其他代理或静态资源配置...
        }
    }
}
​
关键配置说明：

lua_package_path：指定Lua模块的搜索路径，确保Nginx能找到 waf.lua依赖的库。
access_by_lua_file：在请求到达时执行WAF规则（需位于 location块内）。


五、验证与重启Nginx
1. 检查配置语法
sudo nginx -t
​
解释：

若报错需修正路径或依赖问题，常见错误如 lua_package_path未正确指向模块目录。

2. 重启Nginx生效
sudo systemctl restart nginx  # 或使用旧版service命令
​
重要提示：

若使用 systemctl失败，检查Nginx服务状态：systemctl status nginx。


六、常见问题与解决方案
**Q：加载模块时提示 no LuaJIT？**A：

确认已安装LuaJIT：lua -v应显示LuaJIT版本。
若未安装，手动编译：
sudo apt install libluajit-5.1-dev  # 或从源码安装
​


**Q：WAF规则未生效？**A：

检查 waf.lua路径是否正确，权限是否为 644且属主为 nginx。
在 nginx.conf中添加 error_log /var/log/nginx/error.log debug;，查看日志排查。

**Q：如何自定义防护规则？**A：

修改 /usr/share/nginx/modules/rules.lua文件，添加自定义正则表达式或IP黑名单。
示例：拦截特定User-Agent：
if ngx.re.match(ngx.var.http_user_agent, "BadBot") then
    return ngx.exit(403)
end
​



七、进阶配置建议
1. 配置黑白名单
在 waf.lua中添加：
                                    
label : 

                                    

                                        

                                            

                                                                                                
Nginx
                                                                                                
ngx_lua_waf