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

前言

SafeLine 作为一款专业的 Web 应用防火墙，其扩展插件系统为用户提供了强大的自定义防护能力。本文将全面解析 SafeLine 10 扩展插件系统的开发方法，帮助开发者快速掌握插件开发的核心要点。

插件系统概述

SafeLine 扩展插件系统采用 Lua 5.1 作为脚本语言，通过轻量级的脚本实现对请求的深度分析和处理。插件系统主要提供两种类型的插件：

1. Process 插件：基于请求特征触发的处理插件
2. Ticker 插件：基于时间间隔触发的定时任务插件

开发环境准备

在开始开发前，需要了解以下基础配置：

1. 插件管理入口位于 SafeLine 控制台的「入侵检测」→「扩展插件管理」页面
2. 所有插件必须导入 skynet 模块才能使用系统提供的接口
3. 出于安全考虑，部分标准库函数被禁用（如 IO 库全部函数）

插件开发详解

基础结构

每个插件都必须包含以下基本结构：

local skynet = require "skynet"

-- 插件配置和回调函数定义

skynet.register(插件类型, 配置参数, 回调函数)

Process 插件开发

Process 插件是最常用的插件类型，它可以根据请求特征进行匹配和处理。

匹配规则配置

匹配规则通过 match 表定义，支持以下字段：

local match = {
    ip = "192.168.1.0/24",  -- CIDR格式的IP段
    host = "example\\.com",  -- 正则表达式匹配域名
    urlpath = "/admin/.*",  -- 正则表达式匹配路径
    type = skynet.MATCH_TYPE_ALL,  -- 触发模式
    target = skynet.MATCH_TARGET_DETECT  -- 请求类型
}

匹配规则最佳实践：

1. 只声明必要的匹配字段，避免不必要的性能开销
2. 正则表达式会进行全匹配（自动添加$）
3. 合理选择触发模式（DEFAULT或ALL）

处理函数

处理函数接收匹配到的请求参数：

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

Ticker 插件开发

Ticker 插件适合执行定时任务：

local duration = 60  -- 60秒间隔

function ticker(dur)
    -- 定时执行的任务
end

skynet.register(skynet.TYPE_TICKER, duration, ticker)

核心API详解

请求统计API

-- 获取过去time秒内的请求数
local count = skynet.stat_visit(key, time)

-- 获取过去time秒内的请求耗时总和（秒）
local total_time = skynet.stat_time(key, time)

-- 获取状态码统计
local codes = skynet.stat_resp_code(key, time)

TopN查询API

-- 获取5秒内访问量最高的10个IP
local top_ips = skynet.top_n(skynet.TOP_IP, 10, skynet.TOP_DURATION_5S)

防护动作API

-- 封禁指定IP 60秒
skynet.action_ban(key, 60)

-- 限速：60秒内每10秒最多5次请求
skynet.action_limit(key, 60, 10, 5)

数据存储API

-- 全局存储
skynet.db_set(skynet.DB_GLOBAL, "key", "value")

-- 插件私有存储
skynet.db_add(skynet.DB_LOCAL, "counter", 1)

HTTP请求API

-- GET请求示例
local resp, err = skynet.http_get("http://example.com", {
    ["User-Agent"] = "SafeLine-Plugin"
})

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

实战案例

高频访问自动封禁

local skynet = require "skynet"

local match = {
    ip = "0.0.0.0/0",
    type = skynet.MATCH_TYPE_DEFAULT
}

function process(ip)
    local key = {ip = ip}
    local count = skynet.stat_visit(key, 10)  -- 10秒内的访问次数
    
    if count > 100 then  -- 阈值100次
        skynet.action_ban(key, 300)  -- 封禁5分钟
        skynet.log("security", "IP "..ip.." banned for frequent access")
    end
end

skynet.register(skynet.TYPE_PROCESS, match, process)

定时统计热门URL

local skynet = require "skynet"

local duration = 30  -- 30秒间隔

function ticker()
    local top_urls = skynet.top_n(skynet.TOP_HOST_URLPATH, 5, skynet.TOP_DURATION_5S)
    
    for _, item in ipairs(top_urls) do
        skynet.log("stats", "Popular URL: "..item.host..item.urlpath.." - "..item.count.." visits")
    end
end

skynet.register(skynet.TYPE_TICKER, duration, ticker)

性能优化建议

1. 避免在process插件中进行耗时操作
2. 合理设置匹配规则，减少不必要的触发
3. 对于高频操作，考虑使用ticker插件替代
4. 谨慎使用日志功能，避免产生大量日志

结语

SafeLine 10 扩展插件系统提供了强大的自定义防护能力，通过本文的介绍，开发者可以快速掌握插件开发的核心技术。在实际应用中，建议结合具体业务场景，设计出更加精准、高效的防护策略。