防盗链签名校验必须在路由匹配前执行，因Echo中间件默认在路由后运行且Static处理器不走中间件链；正确做法是e.Use()注册前置中间件，校验原始URL、过期时间与HMAC签名。
为什么 echo.MiddlewareFunc 里直接解析 URL 签名会失败
因为防盗链的核心逻辑必须在路由匹配前执行，而 Echo 的中间件默认在路由匹配之后才运行。如果你把签名校验写在普通中间件里，ctx.Request().URL.Query() 可能已经丢失原始查询参数（比如被重定向或代理修改），更关键的是——当请求命中静态文件路由（如 /static/xxx.jpg）时，Echo 默认的 Static 处理器根本不走你注册的中间件链。
正确做法是用 echo.WrapMiddleware 包装底层 http.Handler，或者直接在 echo.Group.Use() 前插入校验逻辑。但最稳的方式是：把签名校验提前到 echo.New() 后、任何 GET/POST 注册前，用 e.Use() 注册一个「前置中间件」：
// 必须放在所有路由注册之前
e.Use(func(next echo.ContextHandler) echo.ContextHandler {
return func(c echo.Context) error {
// 1. 提取原始请求路径和 query（避免被路由重写影响）
rawPath := c.Request().URL.EscapedPath()
rawQuery := c.Request().URL.RawQuery
// 2. 只对图片、视频等资源做校验，跳过 API 接口
if !strings.HasSuffix(rawPath, ".jpg") && !strings.HasSuffix(rawPath, ".png") &&
!strings.HasSuffix(rawPath, ".mp4") && !strings.HasSuffix(rawPath, ".webp") {
return next(c)
}
// 3. 解析签名参数，如 ?sign=xxx&expire=171xxxxx
q := c.Request().URL.Query()
sign := q.Get("sign")
expire := q.Get("expire")
if sign == "" || expire == "" {
return echo.NewHTTPError(http.StatusForbidden, "missing sign or expire")
}
// 4. 校验过期时间（防止 replay）
if t, err := strconv.ParseInt(expire, 10, 64); err != nil || time.Now().Unix() > t {
return echo.NewHTTPError(http.StatusForbidden, "signature expired")
}
// 5. 重新构造待签名字符串（注意顺序和编码一致性）
toSign := rawPath + "?" + rawQuery // 不用 Query().Encode()，避免排序/空格问题
expected := hmacSign(toSign, secretKey) // 自定义函数，用 HMAC-SHA256
if !hmac.Equal([]byte(sign), []byte(expected)) {
return echo.NewHTTPError(http.StatusForbidden, "invalid signature")
}
return next(c)
}
})
动态签名生成时 url.PathEscape 和 url.QueryEscape 怎么选
签名字符串必须和服务器端还原出的字符串完全一致，否则 HMAC 校验必然失败。常见错误是前端用 encodeURIComponent 编码，后端却用 url.QueryEscape ——二者对斜杠 /、问号 ? 等字符处理不同。
解决方案很直接：服务端签名时，**只对 query value 做 url.QueryEscape，path 部分保持原样**；客户端也必须严格按同样规则拼接：
- 路径部分（如
/images/banner.png）不作任何 escape，直接拼入待签名字符串 - 查询参数值（如文件名含空格）必须用
url.QueryEscape，不能用url.PathEscape（后者会把/变成%2F，导致服务端还原失败） - 签名前，query string 要按 key 字典序排序（否则多参数时前后端顺序不一致）
- 不要在签名字符串里包含
#及之后的 fragment，浏览器不会发给服务端
示例（Go 端生成签名）：
func genSignedURL(path string, params url.Values, secret string) string {
// 1. 对每个 value 单独 escape
for k := range params {
params[k] = []string{url.QueryEscape(params.Get(k))}
}
// 2. 按 key 排序拼 query（标准库无内置，需手写）
keys := make([]string, 0, len(params))
for k := range params {
keys = append(keys, k)
}
sort.Strings(keys)
var buf strings.Builder
for i, k := range keys {
if i > 0 {
buf.WriteByte('&')
}
buf.WriteString(k)
buf.WriteString("=")
buf.WriteString(params.Get(k))
}
query := buf.String()
// 3. 拼签名原文：path + "?" + sorted query（不带 #fragment）
toSign := path + "?" + query
sign := hmacSign(toSign, secret)
// 4. 返回完整 URL
u := &url.URL{Path: path, RawQuery: query + "&sign=" + sign}
return u.String()
}
使用 echo.Static 时如何让防盗链中间件生效
这是最常踩的坑：e.Static("/static", "./public") 是一个独立的 http.Handler，它绕过了 Echo 的中间件机制。即使你在上面挂了 Use()，也不会触发。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
解决方式只有两个，且必须二选一：
- 不用
Static，改用GET手动处理文件读取，并在 handler 内调用c.File()，这样中间件链完整生效 - 保留
Static，但用echo.WrapHandler把签名校验包装成标准http.Handler，再传给Static的第二个参数（不推荐，复杂且难调试）
推荐第一种，清晰可控：
// 替代 e.Static("/static", "./public")
e.GET("/static/*", func(c echo.Context) error {
// 中间件已在此处生效
path := c.Param("*")
fullPath := filepath.Join("./public", path)
// 额外校验：防止目录穿越（Static 默认有，手动实现也要加）
if strings.Contains(path, "..") || strings.HasPrefix(filepath.Base(fullPath), ".") {
return echo.NewHTTPError(http.StatusForbidden)
}
if _, err := os.Stat(fullPath); os.IsNotExist(err) {
return echo.NewHTTPError(http.StatusNotFound)
}
return c.File(fullPath)
})
签名密钥轮换时如何避免旧链接批量失效
线上一旦更换 secretKey，所有已分发的带签名 URL 立刻 403。不能简单粗暴地一刀切。
可行方案是支持双密钥验证：校验时先用新密钥试，失败再用旧密钥试一次。同时配合时间窗口控制旧密钥有效期：
- 在签名校验逻辑里，维护一个
oldSecret和对应的过期时间oldSecretExpiresAt - 若新密钥校验失败，且当前时间早于
oldSecretExpiresAt，则用旧密钥重试 - 前端生成签名时，始终只用新密钥；旧链接靠服务端兼容兜底
- 上线后观察日志中「旧密钥校验成功」的比例，逐步缩小
oldSecretExpiresAt，直到归零
这个逻辑要写进前面提到的 hmacSign 和校验函数里，而不是靠配置切换——因为切换时机必须精确到毫秒级。
密钥本身建议从环境变量或 Vault 加载，别硬编码；签名算法别用 MD5 或 SHA1，必须是 HMAC-SHA256 或更高。
