BFE mod_secure_link 模块实战:链接签名校验、防盗链与时效控制

原创2026-10-09 21:37:031,813 阅读
文章标签:后端网络/通信云原生

BFE mod_secure_link 模块实战:链接签名校验、防盗链与时效控制

导读

本文聚焦 BFE(七层负载均衡器)内置的 mod_secure_link 模块,讲解如何通过模块配置与规则配置对请求链接进行签名校验,从而保护资源不被未授权访问,并限制链接的有效期。读完本文,你将掌握 mod_secure_link.conf 与 secure_link_rule.data 的完整配置语法、六种表达式节点(ExpressionNode)的计算逻辑、签名生成与校验的底层算法,以及模块暴露的 7 个监控指标的含义。

mod_secure_link 是 BFE 中典型的"请求校验型"模块:它不修改请求内容,只在路由定位之后对请求做合法性检查,非法请求直接返回 403。其核心思路是:请求方在生成链接时,把"过期时间 + 若干请求特征 + 密钥"拼接成原文,经 MD5 + Base64 变形后作为校验和放入 URL 参数;BFE 收到请求后按相同规则重新计算校验和并比对,同时检查过期时间,从而同时实现防盗链与链接时效控制。

模块简介与校验流程

mod_secure_link 用于检查请求链接的真实性(authenticity),防止资源被未授权访问,并限制链接的生命周期。从源码看,该模块在 Init() 中注册了两个钩子(见 mod_secure_link.go):

  • bfe_module.HandleAfterLocation 过滤器:在请求完成路由定位后执行 validateHandler,对请求做校验;
  • web_monitor.WebHandleReload 处理器:支持通过监控接口热加载规则数据。

validateHandler 的处理逻辑(mod_secure_link.go)可概括为:

  1. 按请求所属产品(request.Route.Product)在规则表中查找规则;若该产品没有规则,直接放行;
  2. 逐条匹配规则的 Cond 条件表达式,命中的规则才参与校验;
  3. 校验通过 → 计数 ReqAccept 并放行(BfeHandlerGoOn);
  4. 校验失败 → 根据具体错误类型累加对应指标,并返回 403 响应(BfeHandlerResponse)。

校验过程中可能出现的 5 类错误与源码中定义的错误对象一一对应(checker.go):

错误 含义 触发场景
ErrReqWithoutExpiresKey 缺少过期时间参数 请求 URL 中没有 ExpiresKey 指定的参数
ErrReqInvalidExpiresValue 过期时间非法 ExpiresKey 参数无法解析为整数
ErrReqExpired 链接已过期 time.Now().Unix() > expiredUnix
ErrReqWithoutChecksumKey 缺少校验和参数 请求 URL 中没有 ChecksumKey 指定的参数
ErrReqInvalidChecksum 校验和不匹配 重算出的签名与请求携带的签名不一致

模块基础配置:mod_secure_link.conf

模块的基础配置文件为 conf/mod_secure_link/mod_secure_link.conf,完整参数说明见 mod_secure_link 基础配置文档。它只负责两件事:规则数据文件路径与调试开关。

配置项 类型 含义 必填 补充说明
Basic.DataPath String 规则配置文件路径 是 默认值为 mod_secure_link/secure_link_rule.data;类型为 FilePath,文件必须存在且可读
Log.OpenDebug Boolean 模块调试开关 否 -

标准配置示例:

[Basic]
DataPath = ./mod_secure_link/secure_link_rule.data

[Log]
OpenDebug = true

从源码 conf_load.go 可以看到两个关键行为:若 DataPath 未设置,模块会打印告警并使用默认值 mod_secure_link/secure_link.data;随后该路径会经过 bfe_util.ConfPathProc 结合配置根目录(confRoot)处理成绝对路径。仓库自带的示例配置 conf/mod_secure_link/mod_secure_link.conf 内容与上述格式一致,可直接作为部署参考。

规则配置:secure_link_rule.data

规则文件 secure_link_rule.data 是 JSON 格式,完整参数说明见 mod_secure_link 规则配置文档。其顶层结构按产品(product)维度组织规则列表。

配置项 类型 含义 必填 补充说明
Version String 配置文件版本号 是 通常为时间戳,如 2019-12-10184356;类型为 Version
Config Object 各产品的规则集合 是 Key 为产品名
Config{k} String 产品名称 是 -
Config{v} Array 规则列表 是 -
Config{v}<a href="https://link.gitcode.com/i/4b32aa89f246a850d3635276b746047f" target="_blank">].Cond String 条件表达式 是 语法参见 [条件表达式语法
Config{v}[].ChecksumKey String 存放校验和的 Query 参数名 是 -
Config{v}[].ExpiresKey String 存放过期时间的 Query 参数名 是 -
Config{v}[].ExpressionNodes Array 参与校验和计算的节点 是 -
Config{v}[].ExpressionNodes[].Type String 节点类型 是 合法值见下文"节点类型"
Config{v}[].ExpressionNodes[].Param String 节点取值参数 条件必填 当 Type 为 label、query、header 时必须提供

一个完整规则示例:

{
    "Version": "2019-12-10184356",
    "Config": {
        "p1": [{
            "Cond": "default_t()",
            "ChecksumKey": "sign",
            "ExpiresKey": "time",
            "ExpressionNodes": [{
                    "Type": "query",
                    "Param": "time"
                },
                {
                    "Type": "uri"
                },
                {
                    "Type": "remote_addr"
                },
                {
                    "Type": "label",
                    "Param": " secret"
                }
            ]
        }]
    }
}

几点值得注意的实现细节(依据 data_load.go):

  • Cond 会被 condition.Build() 编译成条件对象,规则在请求校验前先做条件匹配;
  • ChecksumKey 未显式配置时默认取 "md5";若显式配置为空字符串则报错;
  • ExpressionNodes 为 nil 时直接判定为非法规则;
  • Version 与 Config 缺失时加载失败(bad Version node / bad Config node)。

仓库测试数据 testdata/mod_secure_link/secure_link_rule.data 展示了同一产品 p1 配置 ChecksumKey/ExpiresKey、产品 p2 不配置这两个 key(使用默认值 md5)两种写法,可作为理解"默认值生效"行为的参考。

节点类型与校验和计算逻辑

ExpressionNodes 中的每个节点按顺序拼接出一个字符串(原始原文 origin),其取值逻辑由 checker.go 中对应节点实现确定:

Type 计算逻辑 对应源码实现
label 直接取 $Param 字符串(常用于注入密钥) labelNode.Value 返回固定值
query 取 req.URL.Query($Param) 的查询参数值 queryNode.Value 调用 CachedQuery().Get(key)
header 取 req.Header.Get($Param) 的请求头值 headerNode.Value
host 取 req.Host hostNode.Value
uri 取 req.RequestURI(原始请求 URI,含路径与查询串) uriNode.Value
remote_addr 取 req.RemoteAddr(客户端地址) remoteAddrNode.Value

Expression.Value() 将各节点结果按顺序写入同一个缓冲区拼接为原始字符串(checker.go)。因此,示例配置生成的原文为:

{expires}{req.RequestURI}{req.RemoteAddr}{labelParam}

即 "2147483647/s/link127.0.0.1 secret" 这类形态(过期时间 + URI + 客户端地址 + 密钥)。将密钥放在 label 节点中、与请求特征拼接后再做签名,是典型的 HMAC 式防篡改设计。

签名生成与校验算法

校验和(sign)的编码算法由 Checker.encode() 实现(checker.go),规则文档中以伪代码完整给出了生成链接的步骤:

func WrapSecureLinkParam (req *http.Request) {
    now := time.Now().Unix()
    expires := now + int64(time.Hour*24/time.Second)
    // step1: get origin data
    origin := fmt.Sprintf("%d%s%s%s", expires, req.RequestURI, req.RemoteAddr, " secret")

    // step2: generator sign
    sign := func(origin string) string {
        tmpB := md5.Sum([]byte(origin))
        tmp := base64.StdEncoding.EncodeToString(tmpB[:])
        tmp = strings.ReplaceAll(tmp, "+", "-")
        tmp = strings.ReplaceAll(tmp, "/", "_")
        tmp = strings.ReplaceAll(tmp, "=", "")
        return tmp
    }

    // step3: generate link
    req.URL.Query().Set("sign", sign(origin))
    req.URL.Query().Set("time", fmt.Sprintf("%d", expires))
}

编码过程与 Go 源码中的 encode() 完全一致:MD5 摘要 → 标准 Base64 编码 → 将 + 替换为 -、/ 替换为 _、去掉末尾的 =。这样得到的字符串可直接安全地放进 URL 而无需转义。该算法同样可以在 shell 中复现,便于在脚本、CDN 或客户端侧生成签名链接:

echo -n $origin | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =

# 示例:
echo -n '2147483647/s/link127.0.0.1 secret' | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
# 输出:_e4Nc3iduzkWRm01TBBNYw

服务端校验流程对应 checker.go 的 Check(),顺序为:先取 ExpiresKey 参数(缺失 → ErrReqWithoutExpiresKey,非数字 → ErrReqInvalidExpiresValue,当前时间晚于过期时间 → ErrReqExpired),再取 ChecksumKey 参数(缺失 → ErrReqWithoutChecksumKey),最后用 ExpressionNodes 重算原文并 encode(),与请求携带的签名比对,不一致 → ErrReqInvalidChecksum。

规则加载与热更新

规则数据支持运行时热加载。模块初始化时把规则文件一次性载入内存中的 SecureLinkTable(prodcut_table.go),表内使用 sync.RWMutex 保护读写:

  • Update(conf):整表替换 productRules 与 version;
  • Search(product):按产品名取规则列表。

热加载通过 Web 监控接口触发:loadConfData(query) 支持通过 URL 参数 path 指定新规则文件路径;未指定时使用配置中的默认路径(mod_secure_link.go)。加载完成后调用 DataLoad 解析 JSON 并经 NewData 逐产品、逐规则构建 Rule,任一节点非法都会导致整次加载失败并返回错误,避免半更新状态。

监控指标

模块通过 web-monitor/metrics 暴露 7 个计数器指标(定义见 mod_secure_link.go),完整列表如下:

Metric Description
REQ_TOTAL Total count of requests(进入校验的请求总数)
REQ_ACCEPT Count of accepted requests(校验通过的请求数)
REQ_WITHOUT_EXPIRES_KEY Count of requests missing expires key(缺少过期时间参数的请求数)
REQ_INVALID_EXPIRES_VALUE Count of requests with invalid expires value(过期时间非法的请求数)
REQ_WITHOUT_CHECKSUM_KEY Count of requests missing checksum key(缺少校验和参数的请求数)
REQ_INVALID_CHECKSUM Count of requests with invalid checksum(校验和不匹配的请求数)
REQ_EXPIRED Count of expired requests(链接已过期的请求数)

指标名以 mod_secure_link 为前缀注册。运维上可重点关注 REQ_EXPIRED 与 REQ_INVALID_CHECKSUM 的占比:前者异常升高通常说明链接时效设置过短或客户端时钟偏差;后者异常升高则往往意味着密钥泄露、签名算法实现不一致,或存在恶意构造的请求。

实践要点小结

  • 密钥管理:label 节点中的密钥(如示例中的 " secret")应视为机密,仅部署在可信的签名生成方(如应用服务器或 CDN 边缘)与 BFE 之间,避免出现在前端代码中;
  • 节点顺序即签名顺序:ExpressionNodes 中节点顺序决定原文拼接顺序,生成与校验两侧必须完全一致,否则签名必然不匹配;
  • 时效粒度:过期时间以 Unix 秒为单位,生成链接时按需设置有效期(示例中为 24 小时);BFE 只校验"当前时间 ≤ 过期时间",不校验链接是否已被使用;
  • 按产品隔离:规则按产品名(Config 的 key)组织,未配置规则的产品默认全部放行,不影响既有业务;
  • 调试与热加载:开启 Log.OpenDebug 可辅助排查校验差异;规则文件变更可通过监控接口即时生效,无需重启 BFE。
登录后查看全文
bfe