SafeLine 20 扩展插件开发完全指南

前言

SafeLine 20 作为新一代 Web 应用防火墙，提供了强大的扩展插件系统，允许开发者通过 Lua 脚本实现自定义的安全防护逻辑。本文将全面介绍 SafeLine 20 扩展插件的开发方法，帮助开发者快速掌握插件开发的核心要点。

插件系统概述

SafeLine 20 扩展插件系统基于 Lua 5.1 标准，提供了丰富的 API 接口，支持三种主要类型的触发器：

1. Match 触发器：基于请求特征进行匹配处理
2. Ticker 触发器：实现定时任务功能
3. Query 触发器：支持类 SQL 的流式统计分析

开发环境准备

在开始开发前，需要了解以下基本要求：

• Lua 5.1 语法兼容
• 受限的标准库访问（IO 库完全禁用，OS 库部分函数可用）
• 必须导入 safeline 模块

local safeline = require "safeline"

触发器类型详解

1. Match 触发器开发

Match 触发器是最常用的触发器类型，用于处理符合特定条件的 HTTP 请求。

基本结构

local match = {
    ip = "192.168.1.0/24",
    host = [[example\.com:80]],
    url_path = [[/admin/.*]],
    target = safeline.MATCH_TARGET_DETECT
}

function process(ip, host, url_path)
    -- 处理逻辑
end

safeline.register(safeline.TYPE_MATCH, match, process)

匹配条件详解

字段	说明	示例
ip	支持 CIDR 格式	"192.168.1.0/24"
host	正则表达式匹配	[[.*.example.com:80]]
url_path	正则表达式匹配	[[/admin/.*]]
target	请求类型过滤	safeline.MATCH_TARGET_ALL

请求上下文获取

在回调函数中可获取请求的详细信息：

local target = safeline.get_target()  -- 获取请求类型
local session = safeline.get_session()  -- 获取会话信息
local details = safeline.get_detailed_info()  -- 获取完整请求详情

2. Ticker 触发器开发

Ticker 触发器用于实现定时任务，即使在集群环境下也能保证定时准确性。

local interval = 60  -- 60秒间隔

function tick(duration)
    -- 定时执行的任务
    safeline.log("ticker", "定时任务执行，间隔:"..duration)
end

safeline.register(safeline.TYPE_TICKER, interval, tick)

3. Query 触发器开发

Query 触发器提供类 SQL 的流式分析能力，适合统计场景。

基本查询示例

local query = [[
    SELECT ip, COUNT(*) as cnt 
    FROM access_log 
    GROUP BY TUMBLE_WINDOW(timestamp, 60), ip 
    HAVING cnt > 100
]]

function process(key, rows)
    for row in rows do
        safeline.log("高频IP", row.ip.." 访问次数:"..row.cnt)
    end
end

safeline.register(safeline.TYPE_QUERY, query, process)

SQL 语法要点

• 支持标准 SELECT 语法
• 支持时间窗口函数：TUMBLE_WINDOW
• 支持聚合函数：COUNT, SUM
• 数据源目前仅支持 access_log

核心 API 详解

1. 访问控制 API

-- 封禁IP
safeline.action_ban(safeline.ACTION_SCOPE_ALL, {ip="1.2.3.4"}, 3600)

-- 限频控制
safeline.action_limit(safeline.ACTION_SCOPE_URL, 
    {ip="1.2.3.4", url_path="/api"}, 3600, 60, 100)

2. KV 存储 API

-- 本地存储
safeline.db_set(safeline.DB_LOCAL, "key", "value")
local val = safeline.db_get(safeline.DB_LOCAL, "key")

-- 全局存储
safeline.db_add(safeline.DB_GLOBAL, "counter", 1)

3. HTTP 客户端 API

-- GET 请求
local resp, err = safeline.http_get("http://example.com/api", {
    ["X-Token"] = "abc123"
})

-- POST 请求
local resp, err = safeline.http_post("http://example.com/api", {
    ["Content-Type"] = "application/json"
}, '{"key":"value"}')

4. 日志记录 API

safeline.log("plugin_tag", "日志内容")

高级特性：异步处理

对于批量操作，使用 Promise 模式可显著提高性能：

-- 批量封禁IP的异步实现
for row in rows do
    safeline.promise(function(ip)
        return safeline.action_ban(..., {ip=ip}, ...)
    end, row.ip)(function(err)
        if err then
            safeline.log("ban", "封禁失败:"..err)
        end
    end)()
end

最佳实践

1. 正则表达式优化：使用 [[ ]] 语法避免转义
2. 性能考虑：优先使用本地存储 DB_LOCAL
3. 错误处理：检查 API 调用的返回值
4. 日志分类：使用有意义的 tag 便于排查

完整示例

local safeline = require "safeline"

-- 高频访问检测
local query = [[
    SELECT ip, COUNT(*) as cnt 
    FROM access_log 
    GROUP BY TUMBLE_WINDOW(timestamp, 60), ip 
    HAVING cnt > 500
]]

function process(key, rows)
    for row in rows do
        safeline.promise(function(ip)
            return safeline.action_ban(
                safeline.ACTION_SCOPE_ALL,
                {ip = ip},
                3600  -- 封禁1小时
            )
        end, row.ip)(function(err)
            local msg = err and ("封禁失败:"..err) or "封禁成功"
            safeline.log("auto_ban", row.ip..": "..msg)
        end)()
    end
end

safeline.register(safeline.TYPE_QUERY, query, process)

结语

SafeLine 20 的扩展插件系统提供了强大的自定义能力，通过本文的介绍，开发者可以快速掌握插件开发的核心技术。无论是简单的请求过滤，还是复杂的统计分析，都能通过 Lua 脚本灵活实现。建议从简单的 Match 触发器开始，逐步尝试更高级的 Query 和异步功能，构建出符合业务需求的安全防护方案。