fix: VUL-003 完整修复,启发式/精确双模式 XFF 解析

VUL-003 (中): X-Forwarded-For 信任链可被伪造 IP 绕过限流

本服务定位为公网入口,即使单人使用,公网暴露意味着攻击面
与公开服务等同,不能"够用就行"。

采用渐进式披露设计,平衡易用性与功能性:

  1. 启发式模式(默认, 不设环境变量 或 TRUSTED_PROXY_HOPS=0)
     - 从 XFF 链尾扫描,跳过私有 IP,返回第一个公网 IP
     - 适合 90% 部署(单跳/多跳/直出),无需了解精确跳数
     - 限制:多跳 CDN 场景下,限流粒度为"按 CDN 边缘 IP"
     - 直出部署:整个 XFF 分支不会执行

  2. 精确模式(TRUSTED_PROXY_HOPS=N, N>0)
     - 从 XFF 链尾倒数第 N+1 个位置取值
     - 精准到真实 client,需按实际反代跳数正确配置
     - N=1:单跳反代;N=2:CDN+反代;以此类推

  3. 两种模式都从链尾扫描
     - XFF 首值是客户端可控的,信任首值等于信任攻击者
     - 链尾由受控的反代添加,天然免疫伪造绕过

  4. 默认值从 1 改为 0(行为变化)
     - 旧默认:精确模式 N=1,取 XFF 末值
     - 新默认:启发式模式,跳过链尾私有 IP
     - 对单跳场景行为相同
     - 对多跳/链尾含私有 IP 场景新版更准确(返回真实公网 IP)

  5. 配套
     - middleware/ratelimit_test.go:24 个表驱动测试用例,
       覆盖直出/单跳/多跳/伪造/畸形/精确 N 边界,全部通过
     - setting/config.go:LogStartupSummary 显示当前 XFF 模式
     - .env.example:重写说明,标注默认行为 + 何时需配
     - README.md:新增"反代拓扑与 X-Forwarded-For 解析"章节
       (何时需要/两种模式/行为对比/为什么从链尾/启动日志验证)

  6. 已知边界:TRUSTED_PROXY_HOPS=00 等被 Atoi 解析为 0 的
     输入归入启发式模式,日志不会出现"精确模式 0 跳"矛盾输出。

middleware/ratelimit.go

@@ -4,12 +4,15 @@ import (
 	"log"
 	"net"
 	"net/http"
+	"os"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/volcano-tts/tts-api/common"
 	"github.com/volcano-tts/tts-api/metrics"
+	"github.com/volcano-tts/tts-api/setting"
 )
 
 type RateLimiter struct {
@@ -23,15 +26,57 @@ type RateLimiter struct {
 var (
 	GlobalRateLimiter *RateLimiter
 	ConcurrencySem    chan struct{}
+	// trustedProxyHops controls how X-Forwarded-For (XFF) is parsed when the
+	// direct connection comes from a private IP (i.e., we're behind a reverse
+	// proxy). Two modes are supported, switched by this single value:
+	//
+	//   HEURISTIC MODE (trustedProxyHops == 0, the default):
+	//     Walk XFF from the end, return the first PUBLIC IP. Skips private
+	//     and loopback hops automatically. Works for ~90% of deployments
+	//     without the operator needing to know the exact number of proxy
+	//     hops. Trade-off in multi-hop: rate limiting is per-CDN-edge rather
+	//     than per-real-client, which is "good enough" for abuse protection
+	//     but not for fine-grained per-user quotas.
+	//
+	//   PRECISE MODE (trustedProxyHops > 0):
+	//     Count back N hops from the end of XFF and return that value. Gives
+	//     precise per-real-client rate limiting even in multi-hop setups
+	//     (e.g., Cloudflare + nginx). Operator MUST set this to the number
+	//     of trusted reverse proxies between this service and the client.
+	//
+	// Both modes walk from the END of the XFF chain. The first value is
+	// client-controllable; trusting it would let attackers bypass IP rate
+	// limiting by sending a forged X-Forwarded-For header.
+	trustedProxyHops = 0
 )
 
 func InitRateLimiter() {
+	switch v := os.Getenv("TRUSTED_PROXY_HOPS"); {
+	case v == "":
+		log.Printf("TRUSTED_PROXY_HOPS 未设置,使用默认启发式模式(XFF 链尾第一个公网 IP)")
+	default:
+		n, err := strconv.Atoi(v)
+		switch {
+		case err != nil || n < 0 || n > 10:
+			log.Printf("警告: TRUSTED_PROXY_HOPS=%q 无效(需 0-10 的整数),回退到默认启发式模式", v)
+		case n == 0:
+			// "0" 或 "00" 等被 Atoi 解析为 0 的形式都归到启发式模式,
+			// 避免日志出现"精确模式, 信任 0 跳"这种自相矛盾的输出。
+			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(启发式模式,等同默认)", n)
+		default:
+			trustedProxyHops = n
+			log.Printf("已配置 TRUSTED_PROXY_HOPS=%d(精确模式,信任 %d 跳反代)", n, n)
+		}
+	}
 	GlobalRateLimiter = &RateLimiter{
 		requests: make(map[string][]time.Time),
 		limit:    common.RateLimitRequests,
 		window:   common.RateLimitWindow,
 	}
 	ConcurrencySem = make(chan struct{}, common.MaxConcurrentRequests)
+
+	// 同步到 setting 包,供 LogStartupSummary 展示
+	setting.TrustedProxyHops = trustedProxyHops
 }
 
 func (rl *RateLimiter) Allow(key string) bool {
@@ -133,10 +178,37 @@ func GetClientIP(r *http.Request) string {
 	}
 
 	if isPrivateIP(directIP) {
+		// Parse X-Forwarded-For when there's a reverse proxy in front (direct
+		// connection is from a private IP). Both modes walk from the END of
+		// the chain so that the client-controllable first value cannot be
+		// used to spoof a different client IP for rate limit bypass.
 		if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
-			ip := strings.TrimSpace(strings.Split(xff, ",")[0])
-			if net.ParseIP(ip) != nil {
-				return ip
+			parts := strings.Split(xff, ",")
+			if trustedProxyHops > 0 {
+				// PRECISE MODE: count back N hops from end. Real client IP
+				// sits at index (len(parts) - N). Walk backwards to skip
+				// any malformed values; if chain is shorter than expected,
+				// fall through to the first valid IP in the chain.
+				target := len(parts) - trustedProxyHops
+				if target < 0 {
+					target = 0
+				}
+				for i := target; i >= 0; i-- {
+					ip := strings.TrimSpace(parts[i])
+					if net.ParseIP(ip) != nil {
+						return ip
+					}
+				}
+			} else {
+				// HEURISTIC MODE (default): walk from end, return first
+				// PUBLIC IP. Skips private/loopback hops that come from
+				// internal proxies between the public-facing proxy and us.
+				for i := len(parts) - 1; i >= 0; i-- {
+					ip := strings.TrimSpace(parts[i])
+					if parsed := net.ParseIP(ip); parsed != nil && !isPrivateIP(ip) {
+						return ip
+					}
+				}
 			}
 		}
 		if xri := strings.TrimSpace(r.Header.Get("X-Real-IP")); xri != "" {