feat(cache): 新增缓存清理 API

支持通过 HTTP API 主动清理代理缓存，提供精确路径和通配符模式清理。
包含 IP 白名单和 Token 认证支持。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

internal/cache/purge.go

@@ -0,0 +1,329 @@
+// Package cache 提供文件缓存和代理缓存功能，支持 LRU 淘汰和缓存锁防击穿。
+//
+// 该文件实现了缓存清理 API，用于主动清理代理缓存。
+//
+// 主要功能：
+//   - 精确路径清理：删除指定路径的缓存条目
+//   - 通配符模式清理：按模式批量删除缓存条目
+//   - IP 白名单访问控制
+//   - Token 认证支持
+//
+// 作者：xfy
+package cache
+
+import (
+	"encoding/json"
+	"hash/fnv"
+	"net"
+	"strings"
+
+	"github.com/valyala/fasthttp"
+	"rua.plus/lolly/internal/config"
+)
+
+// PurgeAPI 缓存清理 API 处理器。
+//
+// 提供 HTTP API 用于主动清理代理缓存，支持精确路径和通配符模式清理。
+//
+// 注意事项：
+//   - 所有方法均为并发安全
+//   - 支持 IP 白名单和 Token 认证
+//   - 仅处理 POST 请求
+type PurgeAPI struct {
+	// cache 代理缓存实例
+	cache *ProxyCache
+
+	// allowed 允许访问的 IP 网络列表
+	allowed []net.IPNet
+
+	// auth 认证配置
+	auth config.CacheAPIAuthConfig
+
+	// path API 端点路径
+	path string
+}
+
+// PurgeRequest 清理请求结构。
+type PurgeRequest struct {
+	// Path 精确路径
+	Path string `json:"path,omitempty"`
+
+	// Pattern 通配符模式（支持 * 通配符）
+	Pattern string `json:"pattern,omitempty"`
+}
+
+// PurgeResponse 清理响应结构。
+type PurgeResponse struct {
+	// Deleted 被删除的缓存条目数
+	Deleted int `json:"deleted"`
+}
+
+// PurgeErrorResponse 错误响应结构。
+type PurgeErrorResponse struct {
+	// Error 错误信息
+	Error string `json:"error"`
+}
+
+// NewPurgeAPI 创建缓存清理 API 处理器。
+//
+// 参数：
+//   - cache: 代理缓存实例
+//   - cfg: 缓存 API 配置
+//
+// 返回值：
+//   - *PurgeAPI: 配置好的处理器
+//   - error: IP 解析失败时返回非 nil 错误
+func NewPurgeAPI(cache *ProxyCache, cfg *config.CacheAPIConfig) (*PurgeAPI, error) {
+	p := &PurgeAPI{
+		cache: cache,
+		auth:  cfg.Auth,
+		path:  cfg.Path,
+	}
+
+	// 解析允许的 IP 列表
+	for _, cidr := range cfg.Allow {
+		_, network, err := net.ParseCIDR(cidr)
+		if err != nil {
+			// 尝试作为单个 IP 解析
+			ip := net.ParseIP(cidr)
+			if ip == nil {
+				return nil, err
+			}
+			// 转换为 CIDR 格式
+			if ip.To4() != nil {
+				_, network, _ = net.ParseCIDR(cidr + "/32")
+			} else {
+				_, network, _ = net.ParseCIDR(cidr + "/128")
+			}
+		}
+		if network != nil {
+			p.allowed = append(p.allowed, *network)
+		}
+	}
+
+	return p, nil
+}
+
+// Path 返回 API 端点路径。
+func (p *PurgeAPI) Path() string {
+	if p.path == "" {
+		return "/_cache/purge"
+	}
+	return p.path
+}
+
+// ServeHTTP 处理缓存清理请求。
+//
+// 仅处理 POST 请求，支持精确路径和通配符模式清理。
+// 返回 JSON 格式的响应。
+func (p *PurgeAPI) ServeHTTP(ctx *fasthttp.RequestCtx) {
+	// 仅允许 POST 方法
+	if string(ctx.Method()) != "POST" {
+		p.sendError(ctx, fasthttp.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+
+	// 检查 IP 访问权限
+	if !p.checkAccess(ctx) {
+		p.sendError(ctx, fasthttp.StatusForbidden, "forbidden")
+		return
+	}
+
+	// 检查认证
+	if !p.checkAuth(ctx) {
+		p.sendError(ctx, fasthttp.StatusUnauthorized, "unauthorized")
+		return
+	}
+
+	// 解析请求体
+	var req PurgeRequest
+	if err := json.Unmarshal(ctx.PostBody(), &req); err != nil {
+		p.sendError(ctx, fasthttp.StatusBadRequest, "invalid request body")
+		return
+	}
+
+	// 执行清理
+	deleted := 0
+	if req.Path != "" {
+		deleted = p.purgeByPath(req.Path)
+	} else if req.Pattern != "" {
+		deleted = p.purgeByPattern(req.Pattern)
+	} else {
+		p.sendError(ctx, fasthttp.StatusBadRequest, "missing path or pattern")
+		return
+	}
+
+	// 返回响应
+	ctx.SetContentType("application/json; charset=utf-8")
+	ctx.SetStatusCode(fasthttp.StatusOK)
+	json.NewEncoder(ctx).Encode(PurgeResponse{Deleted: deleted}) //nolint:errcheck
+}
+
+// checkAccess 检查客户端 IP 是否在允许列表中。
+func (p *PurgeAPI) checkAccess(ctx *fasthttp.RequestCtx) bool {
+	// 如果没有配置允许列表，允许所有访问
+	if len(p.allowed) == 0 {
+		return true
+	}
+
+	clientIP := p.getClientIP(ctx)
+	if clientIP == nil {
+		return false
+	}
+
+	// 检查是否在允许列表中
+	for _, network := range p.allowed {
+		if network.Contains(clientIP) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// checkAuth 检查认证。
+func (p *PurgeAPI) checkAuth(ctx *fasthttp.RequestCtx) bool {
+	// 无需认证
+	if p.auth.Type == "" || p.auth.Type == "none" {
+		return true
+	}
+
+	// Token 认证
+	if p.auth.Type == "token" {
+		// 从 Authorization header 获取 token
+		authHeader := ctx.Request.Header.Peek("Authorization")
+		if len(authHeader) == 0 {
+			return false
+		}
+
+		// 支持 Bearer token 格式
+		authStr := string(authHeader)
+		if token, ok := strings.CutPrefix(authStr, "Bearer "); ok {
+			return token == p.auth.Token
+		}
+
+		// 也支持直接传递 token
+		return authStr == p.auth.Token
+	}
+
+	return false
+}
+
+// getClientIP 从请求上下文提取客户端 IP。
+func (p *PurgeAPI) getClientIP(ctx *fasthttp.RequestCtx) net.IP {
+	// 检查 X-Forwarded-For 头部
+	if xff := ctx.Request.Header.Peek("X-Forwarded-For"); len(xff) > 0 {
+		ips := strings.Split(string(xff), ",")
+		if len(ips) > 0 {
+			ipStr := strings.TrimSpace(ips[0])
+			ip := net.ParseIP(ipStr)
+			if ip != nil {
+				return ip
+			}
+		}
+	}
+
+	// 检查 X-Real-IP 头部
+	if xri := ctx.Request.Header.Peek("X-Real-IP"); len(xri) > 0 {
+		ip := net.ParseIP(string(xri))
+		if ip != nil {
+			return ip
+		}
+	}
+
+	// 使用 RemoteAddr
+	if addr := ctx.RemoteAddr(); addr != nil {
+		if tcpAddr, ok := addr.(*net.TCPAddr); ok {
+			return tcpAddr.IP
+		}
+	}
+
+	return nil
+}
+
+// purgeByPath 按精确路径清理缓存。
+func (p *PurgeAPI) purgeByPath(path string) int {
+	if p.cache == nil {
+		return 0
+	}
+
+	// 计算缓存键的哈希值
+	hashKey := hashPath(path)
+
+	// 尝试删除
+	p.cache.mu.Lock()
+	defer p.cache.mu.Unlock()
+
+	if _, ok := p.cache.entries[hashKey]; ok {
+		delete(p.cache.entries, hashKey)
+		return 1
+	}
+
+	return 0
+}
+
+// purgeByPattern 按通配符模式清理缓存。
+func (p *PurgeAPI) purgeByPattern(pattern string) int {
+	if p.cache == nil {
+		return 0
+	}
+
+	p.cache.mu.Lock()
+	defer p.cache.mu.Unlock()
+
+	deleted := 0
+	for hashKey, entry := range p.cache.entries {
+		if matchPattern(pattern, entry.OrigKey) {
+			delete(p.cache.entries, hashKey)
+			deleted++
+		}
+	}
+
+	return deleted
+}
+
+// hashPath 使用 FNV-64a 计算路径的哈希值。
+// 与代理层 buildCacheKeyHash 使用相同的算法，确保一致性。
+// 注意：代理层的 key 格式为 "METHOD:URI"，purge 时默认使用 GET 方法。
+func hashPath(path string) uint64 {
+	// 默认使用 GET 方法，与代理层 key 格式一致
+	key := "GET:" + path
+	h := fnv.New64a()
+	h.Write([]byte(key))
+	return h.Sum64()
+}
+
+// matchPattern 检查路径是否匹配通配符模式。
+// 仅支持 * 通配符，匹配任意字符。
+func matchPattern(pattern, path string) bool {
+	// 特殊情况：* 匹配所有
+	if pattern == "*" {
+		return true
+	}
+
+	// 检查是否有通配符
+	if !strings.Contains(pattern, "*") {
+		return path == pattern
+	}
+
+	// 简单的前缀匹配：/api/users/* 匹配 /api/users/123
+	if prefix, ok := strings.CutSuffix(pattern, "*"); ok {
+		return strings.HasPrefix(path, prefix)
+	}
+
+	// 中间通配符：/api/*/users 匹配 /api/v1/users
+	parts := strings.Split(pattern, "*")
+	if len(parts) == 2 {
+		return strings.HasPrefix(path, parts[0]) && strings.HasSuffix(path, parts[1])
+	}
+
+	// 复杂模式不支持，返回 false
+	return false
+}
+
+// sendError 发送错误响应。
+func (p *PurgeAPI) sendError(ctx *fasthttp.RequestCtx, status int, errMsg string) {
+	ctx.SetContentType("application/json; charset=utf-8")
+	ctx.SetStatusCode(status)
+	json.NewEncoder(ctx).Encode(PurgeErrorResponse{Error: errMsg}) //nolint:errcheck
+}

internal/config/config.go

@@ -271,6 +271,10 @@ type ServerConfig struct {
 	// 支持单位：b, kb, mb, gb 或纯数字表示字节
 	// 默认值为 1MB
 	ClientMaxBodySize string `yaml:"client_max_body_size"`
+
+	// CacheAPI 缓存 API 配置
+	// 用于主动清理代理缓存
+	CacheAPI *CacheAPIConfig `yaml:"cache_api"`
 }
 
 // StaticConfig 静态文件服务配置。
@@ -1445,6 +1449,54 @@ type StatusConfig struct {
 	Format string `yaml:"format"`
 }
 
+// CacheAPIConfig 缓存 API 配置。
+//
+// 配置缓存清理 API 端点，支持主动清理代理缓存。
+//
+// 注意事项：
+//   - Enabled 默认为 false，需显式启用
+//   - Allow 限制可访问的 IP 地址列表
+//   - Auth 配置认证方式，推荐使用 token 认证
+//
+// 使用示例：
+//
+//	cache_api:
+//	  enabled: true
+//	  path: "/_cache/purge"
+//	  allow: ["127.0.0.1", "10.0.0.0/8"]
+//	  auth:
+//	    type: "token"
+//	    token: "${CACHE_API_TOKEN}"
+type CacheAPIConfig struct {
+	// Enabled 是否启用缓存 API
+	// 默认为 false
+	Enabled bool `yaml:"enabled"`
+
+	// Path API 端点路径
+	// 默认为 "/_cache/purge"
+	Path string `yaml:"path"`
+
+	// Allow 允许访问的 IP 列表
+	// 可访问缓存 API 的 IP 地址或 CIDR
+	Allow []string `yaml:"allow"`
+
+	// Auth 认证配置
+	Auth CacheAPIAuthConfig `yaml:"auth"`
+}
+
+// CacheAPIAuthConfig 缓存 API 认证配置。
+type CacheAPIAuthConfig struct {
+	// Type 认证类型
+	// 支持 "none" 和 "token" 两种类型
+	// 默认为 "none"
+	Type string `yaml:"type"`
+
+	// Token 认证令牌
+	// 当 Type 为 "token" 时使用
+	// 支持环境变量替换，如 "${CACHE_API_TOKEN}"
+	Token string `yaml:"token"`
+}
+
 // StreamConfig TCP/UDP Stream 代理配置。
 //
 // 用于四层网络代理，如数据库、Redis 等 TCP/UDP 服务。

internal/config/defaults.go

@@ -45,6 +45,15 @@ func DefaultConfig() *Config {
 			IdleTimeout:        120 * time.Second,
 			MaxConnsPerIP:      1000,
 			MaxRequestsPerConn: 10000,
+			CacheAPI: &CacheAPIConfig{
+				Enabled: false,
+				Path:    "/_cache/purge",
+				Allow:   []string{"127.0.0.1"},
+				Auth: CacheAPIAuthConfig{
+					Type:  "none",
+					Token: "",
+				},
+			},
 			Static: []StaticConfig{{
 				Path:  "/",
 				Root:  "/var/www/html",