Merge pull request #4462 from Wei-Shaw/fix/unify-security-client-ip

fix(security): unify audit log & session binding client IP with API key ACL trust toggle

backend/internal/handler/admin/audit_log_handler.go

@@ -6,7 +6,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
 	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/service"
@@ -150,7 +149,7 @@ func (h *AuditLogHandler) Clear(c *gin.Context) {
 		CredentialMasked: middleware.MaskedRequestCredential(c),
 		Method:           http.MethodPost,
 		Path:             c.FullPath(),
-		ClientIP:         ip.GetTrustedClientIP(c),
+		ClientIP:         middleware.SecurityClientIP(c),
 		UserAgent:        c.Request.UserAgent(),
 		StatusCode:       http.StatusOK,
 	}

backend/internal/pkg/ip/ip.go

@@ -54,6 +54,17 @@ func GetTrustedClientIP(c *gin.Context) string {
 	return normalizeIP(c.ClientIP())
 }
 
+// GetSecurityClientIP 返回安全敏感场景（API Key IP 限制、审计日志、会话 IP/UA 绑定）
+// 使用的客户端 IP。trustForwarded 对应系统设置「信任反代传递的客户端 IP」：
+// 开启时信任反代转发头（CF-Connecting-IP / X-Real-IP / X-Forwarded-For），
+// 关闭时走 Gin trusted_proxies 解析链。
+func GetSecurityClientIP(c *gin.Context, trustForwarded bool) string {
+	if trustForwarded {
+		return GetClientIP(c)
+	}
+	return GetTrustedClientIP(c)
+}
+
 // normalizeIP 规范化 IP 地址，去除端口号和空格。
 func normalizeIP(ip string) string {
 	ip = strings.TrimSpace(ip)

backend/internal/pkg/ip/ip_test.go

@@ -94,3 +94,33 @@ func TestCheckIPRestrictionWithCompiledRules_InvalidWhitelistStillDenies(t *test
 	require.False(t, allowed)
 	require.Equal(t, "access denied", reason)
 }
+
+func TestGetSecurityClientIPHonorsTrustToggle(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	for _, tc := range []struct {
+		name           string
+		trustForwarded bool
+		want           string
+	}{
+		{name: "trust disabled uses trusted proxy chain", trustForwarded: false, want: "9.9.9.9"},
+		{name: "trust enabled uses forwarded header", trustForwarded: true, want: "1.2.3.4"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			r := gin.New()
+			require.NoError(t, r.SetTrustedProxies(nil))
+			r.GET("/t", func(c *gin.Context) {
+				c.String(200, GetSecurityClientIP(c, tc.trustForwarded))
+			})
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest("GET", "/t", nil)
+			req.RemoteAddr = "9.9.9.9:12345"
+			req.Header.Set("X-Real-IP", "1.2.3.4")
+			r.ServeHTTP(w, req)
+
+			require.Equal(t, 200, w.Code)
+			require.Equal(t, tc.want, w.Body.String())
+		})
+	}
+}

backend/internal/server/middleware/api_key_auth.go

@@ -97,10 +97,7 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 		// 检查 IP 限制（白名单/黑名单）
 		// 注意：错误信息故意模糊，避免暴露具体的 IP 限制机制
 		if len(apiKey.IPWhitelist) > 0 || len(apiKey.IPBlacklist) > 0 {
-			clientIP := ip.GetTrustedClientIP(c)
-			if cfg.TrustForwardedIPForAPIKeyACL() {
-				clientIP = ip.GetClientIP(c)
-			}
+			clientIP := ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL())
 			allowed, _ := ip.CheckIPRestrictionWithCompiledRules(clientIP, apiKey.CompiledIPWhitelist, apiKey.CompiledIPBlacklist)
 			if !allowed {
 				if clientIP == "" {

backend/internal/server/middleware/api_key_auth_google.go

@@ -59,10 +59,7 @@ func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subs
 
 		// 检查 IP 限制（白名单/黑名单）。与主中间件保持一致，避免 Gemini 端点绕过 Key 的 IP ACL。
 		if len(apiKey.IPWhitelist) > 0 || len(apiKey.IPBlacklist) > 0 {
-			clientIP := ip.GetTrustedClientIP(c)
-			if cfg.TrustForwardedIPForAPIKeyACL() {
-				clientIP = ip.GetClientIP(c)
-			}
+			clientIP := ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL())
 			allowed, _ := ip.CheckIPRestrictionWithCompiledRules(clientIP, apiKey.CompiledIPWhitelist, apiKey.CompiledIPBlacklist)
 			if !allowed {
 				if clientIP == "" {

backend/internal/server/middleware/audit_log.go

@@ -7,7 +7,6 @@ import (
 	"time"
 
 	"github.com/Wei-Shaw/sub2api/internal/pkg/ctxkey"
-	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
@@ -147,7 +146,7 @@ func NewAuditLogMiddleware(auditService *service.AuditLogService) AuditLogMiddle
 			Action:      action,
 			Method:      c.Request.Method,
 			Path:        c.FullPath(),
-			ClientIP:    ip.GetTrustedClientIP(c),
+			ClientIP:    SecurityClientIP(c),
 			UserAgent:   c.Request.UserAgent(),
 			RequestBody: bodyRedacted,
 			StatusCode:  status,

backend/internal/server/middleware/session_binding.go

@@ -1,19 +1,25 @@
 package middleware
 
 import (
+	"strings"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
 )
 
-// SessionBindingContext 全局中间件：将请求的可信客户端 IP 与 User-Agent 注入
-// request context，供 token 签发路径（登录 / 刷新 / OAuth 回调）读取并写入会话绑定。
-// 必须使用 GetTrustedClientIP（走 trusted_proxies 链），不可信头会导致绑定被伪造绕过。
-func SessionBindingContext() gin.HandlerFunc {
+// SessionBindingContext 全局中间件：将请求的客户端 IP 与 User-Agent 注入
+// request context，供 token 签发路径（登录 / 刷新 / OAuth 回调）读取并写入会话绑定，
+// 同时作为审计日志、会话绑定校验的统一客户端 IP 来源。
+// IP 取值与 API Key IP 限制共用「信任反代传递的客户端 IP」系统开关：
+// 开启时信任反代转发头（CF-Connecting-IP / X-Real-IP / X-Forwarded-For），
+// 关闭时走 trusted_proxies 解析链，避免不可信头伪造绕过绑定。
+func SessionBindingContext(cfg *config.Config) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		binding := &service.SessionBinding{
-			IP:        ip.GetTrustedClientIP(c),
+			IP:        ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL()),
 			UserAgent: c.Request.UserAgent(),
 		}
 		c.Request = c.Request.WithContext(service.WithSessionBinding(c.Request.Context(), binding))
@@ -21,13 +27,27 @@ func SessionBindingContext() gin.HandlerFunc {
 	}
 }
 
-// currentSessionBindingHash 计算当前请求的会话指纹哈希。
-func currentSessionBindingHash(c *gin.Context) string {
-	binding := &service.SessionBinding{
+// requestSessionBinding 返回当前请求的会话指纹，优先取 SessionBindingContext
+// 注入的解析结果（保证与 token 签发路径取值一致）；注入缺失时按 trusted_proxies
+// 链回退兜底（等价于开关关闭时的行为）。
+func requestSessionBinding(c *gin.Context) *service.SessionBinding {
+	if binding := service.SessionBindingFromContext(c.Request.Context()); binding != nil {
+		return binding
+	}
+	return &service.SessionBinding{
 		IP:        ip.GetTrustedClientIP(c),
 		UserAgent: c.Request.UserAgent(),
 	}
-	return binding.Hash()
+}
+
+// SecurityClientIP 返回当前请求用于安全敏感记录（审计日志等）的客户端 IP。
+// 与会话绑定、API Key IP 限制共用同一套「信任反代传递的客户端 IP」开关语义。
+func SecurityClientIP(c *gin.Context) string {
+	if binding := service.SessionBindingFromContext(c.Request.Context()); binding != nil &&
+		strings.TrimSpace(binding.IP) != "" {
+		return binding.IP
+	}
+	return ip.GetTrustedClientIP(c)
 }
 
 // enforceSessionBinding 校验 access token 的会话指纹（IP/UA 绑定）。
@@ -49,7 +69,8 @@ func enforceSessionBinding(
 	if claims == nil || claims.BindingHash == "" {
 		return true
 	}
-	current := currentSessionBindingHash(c)
+	binding := requestSessionBinding(c)
+	current := binding.Hash()
 	if current == "" || current == claims.BindingHash {
 		return true
 	}
@@ -71,7 +92,7 @@ func enforceSessionBinding(
 			Action:      service.AuditActionSessionBindingMismatch,
 			Method:      c.Request.Method,
 			Path:        path,
-			ClientIP:    ip.GetTrustedClientIP(c),
+			ClientIP:    binding.IP,
 			UserAgent:   c.Request.UserAgent(),
 			StatusCode:  401,
 		})

backend/internal/server/middleware/session_binding_test.go

@@ -0,0 +1,103 @@
+//go:build unit
+
+package middleware
+
+import (
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+// 反代场景：RemoteAddr 为 127.0.0.1，真实客户端 IP 在 X-Real-IP 中。
+// 会话绑定注入与审计 IP 必须与 API Key IP 限制共用「信任反代传递的客户端 IP」开关语义。
+func TestSessionBindingContextHonorsTrustForwardedToggle(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	for _, tc := range []struct {
+		name           string
+		trustForwarded bool
+		wantIP         string
+	}{
+		{name: "trust disabled records proxy address", trustForwarded: false, wantIP: "127.0.0.1"},
+		{name: "trust enabled records forwarded client IP", trustForwarded: true, wantIP: "1.2.3.4"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &config.Config{}
+			cfg.SetTrustForwardedIPForAPIKeyACL(tc.trustForwarded)
+
+			r := gin.New()
+			require.NoError(t, r.SetTrustedProxies(nil))
+			r.Use(SessionBindingContext(cfg))
+			r.GET("/t", func(c *gin.Context) {
+				binding := service.SessionBindingFromContext(c.Request.Context())
+				require.NotNil(t, binding)
+				require.Equal(t, tc.wantIP, binding.IP)
+				require.Equal(t, "test-agent", binding.UserAgent)
+				require.Equal(t, tc.wantIP, SecurityClientIP(c))
+				c.Status(200)
+			})
+
+			w := httptest.NewRecorder()
+			req := httptest.NewRequest("GET", "/t", nil)
+			req.RemoteAddr = "127.0.0.1:54321"
+			req.Header.Set("X-Real-IP", "1.2.3.4")
+			req.Header.Set("User-Agent", "test-agent")
+			r.ServeHTTP(w, req)
+
+			require.Equal(t, 200, w.Code)
+		})
+	}
+}
+
+// 未经过 SessionBindingContext 注入时（异常挂载顺序/单测直调），回退 trusted_proxies 链，
+// 等价于开关关闭时的历史行为。
+func TestSecurityClientIPFallsBackWithoutInjectedBinding(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	require.NoError(t, r.SetTrustedProxies(nil))
+	r.GET("/t", func(c *gin.Context) {
+		c.String(200, SecurityClientIP(c))
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/t", nil)
+	req.RemoteAddr = "9.9.9.9:12345"
+	req.Header.Set("X-Real-IP", "1.2.3.4")
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, 200, w.Code)
+	require.Equal(t, "9.9.9.9", w.Body.String())
+}
+
+// requestSessionBinding 优先取注入值：开关开启时校验哈希必须基于注入的转发 IP 计算，
+// 与 token 签发路径取值一致，否则同一客户端会被误判为指纹变化。
+func TestRequestSessionBindingPrefersInjectedBinding(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	cfg := &config.Config{}
+	cfg.SetTrustForwardedIPForAPIKeyACL(true)
+
+	r := gin.New()
+	require.NoError(t, r.SetTrustedProxies(nil))
+	r.Use(SessionBindingContext(cfg))
+	r.GET("/t", func(c *gin.Context) {
+		issued := &service.SessionBinding{IP: "1.2.3.4", UserAgent: "test-agent"}
+		require.Equal(t, issued.Hash(), requestSessionBinding(c).Hash())
+		c.Status(200)
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/t", nil)
+	req.RemoteAddr = "127.0.0.1:54321"
+	req.Header.Set("X-Real-IP", "1.2.3.4")
+	req.Header.Set("User-Agent", "test-agent")
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, 200, w.Code)
+}

backend/internal/server/router.go

@@ -54,8 +54,9 @@ func SetupRouter(
 
 	// 应用中间件
 	r.Use(middleware2.RequestLogger())
-	// 将可信客户端 IP + UA 注入 request context，供 token 签发路径写入会话绑定
-	r.Use(middleware2.SessionBindingContext())
+	// 将客户端 IP + UA 注入 request context，供 token 签发/会话绑定/审计日志统一读取。
+	// IP 取值与 API Key IP 限制共用「信任反代传递的客户端 IP」系统开关。
+	r.Use(middleware2.SessionBindingContext(cfg))
 	r.Use(middleware2.Logger())
 	r.Use(middleware2.CORS(cfg.CORS))
 	r.Use(middleware2.SecurityHeaders(cfg.Security.CSP, func() []string {

frontend/src/i18n/locales/en/admin/settings.ts

@@ -146,10 +146,11 @@ export default {
       },
       apiKeyAcl: {
         title: 'API Key IP Access Control',
-        description: 'Choose which client IP is used by API Key allowlists and denylists',
+        description:
+          'Choose which client IP is used by API Key allowlists/denylists, admin audit logs, and session IP/UA binding',
         trustForwardedIp: 'Trust forwarded client IP',
         trustForwardedIpHint:
-          'Disabled by default. Enable only when the origin is reachable only through Cloudflare or Nginx reverse proxy. When enabled, API Key IP allowlists and denylists use CF-Connecting-IP, X-Real-IP, or X-Forwarded-For, matching the request IP shown in usage records.'
+          'Disabled by default. Enable only when the origin is reachable only through Cloudflare or Nginx reverse proxy. When enabled, API Key IP allowlists/denylists, admin audit logs, and session IP/UA binding use CF-Connecting-IP, X-Real-IP, or X-Forwarded-For, matching the request IP shown in usage records. Toggling this switch changes the IP fingerprint of existing sessions; with session binding enabled they must sign in again.'
       },
       linuxdo: {
         title: 'LinuxDo Connect Login',

frontend/src/i18n/locales/zh/admin/settings.ts

@@ -146,10 +146,10 @@ export default {
       },
       apiKeyAcl: {
         title: 'API Key IP 访问控制',
-        description: '控制 API Key 白名单和黑名单使用哪个客户端 IP 判断',
+        description: '控制 API Key 白/黑名单、操作审计日志与会话 IP/UA 绑定使用哪个客户端 IP 判断',
         trustForwardedIp: '信任反代传递的客户端 IP',
         trustForwardedIpHint:
-          '默认关闭。仅在源站只允许 Cloudflare 或 Nginx 反代访问时开启；开启后 API Key IP 白/黑名单会使用 CF-Connecting-IP、X-Real-IP 或 X-Forwarded-For，与使用记录中的请求 IP 保持一致。'
+          '默认关闭。仅在源站只允许 Cloudflare 或 Nginx 反代访问时开启；开启后 API Key IP 白/黑名单、操作审计日志与会话 IP/UA 绑定会使用 CF-Connecting-IP、X-Real-IP 或 X-Forwarded-For，与使用记录中的请求 IP 保持一致。切换本开关会改变已登录会话的 IP 指纹，开启会话绑定时现有会话需重新登录。'
       },
       linuxdo: {
         title: 'LinuxDo Connect 登录',