feat(gateway): 添加 Claude Code 客户端最低版本检查功能

- 通过 User-Agent 识别 Claude Code 客户端并提取版本号
- 在网关层验证客户端版本是否满足管理员配置的最低要求
- 在管理后台提供版本要求配置选项（英文/中文双语）
- 实现原子缓存 + singleflight 防止并发问题和 thundering herd
- 使用 context.WithoutCancel 隔离 DB 查询，避免客户端断连影响缓存
- 双 TTL 策略：60s 正常、5s 错误恢复，保证性能与可用性
- 仅检查 Claude Code 客户端，其他客户端不受影响
- 添加完整单元测试覆盖版本提取、比对、上下文操作

Author: QTom

backend/cmd/server/wire_gen.go

@@ -3,6 +3,8 @@ package admin
 import (
 	"fmt"
 	"log"
+	"net/http"
+	"regexp"
 	"strings"
 	"time"
 
@@ -15,6 +17,9 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// semverPattern 预编译 semver 格式校验正则
+var semverPattern = regexp.MustCompile(`^\d+\.\d+\.\d+$`)
+
 // SettingHandler 系统设置处理器
 type SettingHandler struct {
 	settingService   *service.SettingService
@@ -93,6 +98,7 @@ func (h *SettingHandler) GetSettings(c *gin.Context) {
 		OpsRealtimeMonitoringEnabled:         settings.OpsRealtimeMonitoringEnabled,
 		OpsQueryModeDefault:                  settings.OpsQueryModeDefault,
 		OpsMetricsIntervalSeconds:            settings.OpsMetricsIntervalSeconds,
+		MinClaudeCodeVersion:                 settings.MinClaudeCodeVersion,
 	})
 }
 
@@ -159,6 +165,8 @@ type UpdateSettingsRequest struct {
 	OpsRealtimeMonitoringEnabled *bool   `json:"ops_realtime_monitoring_enabled"`
 	OpsQueryModeDefault          *string `json:"ops_query_mode_default"`
 	OpsMetricsIntervalSeconds    *int    `json:"ops_metrics_interval_seconds"`
+
+	MinClaudeCodeVersion string `json:"min_claude_code_version"`
 }
 
 // UpdateSettings 更新系统设置
@@ -293,6 +301,14 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		req.OpsMetricsIntervalSeconds = &v
 	}
 
+	// 验证最低版本号格式（空字符串=禁用，或合法 semver）
+	if req.MinClaudeCodeVersion != "" {
+		if !semverPattern.MatchString(req.MinClaudeCodeVersion) {
+			response.Error(c, http.StatusBadRequest, "min_claude_code_version must be empty or a valid semver (e.g. 2.1.63)")
+			return
+		}
+	}
+
 	settings := &service.SystemSettings{
 		RegistrationEnabled:         req.RegistrationEnabled,
 		EmailVerifyEnabled:          req.EmailVerifyEnabled,
@@ -334,6 +350,7 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		FallbackModelAntigravity:    req.FallbackModelAntigravity,
 		EnableIdentityPatch:         req.EnableIdentityPatch,
 		IdentityPatchPrompt:         req.IdentityPatchPrompt,
+		MinClaudeCodeVersion:        req.MinClaudeCodeVersion,
 		OpsMonitoringEnabled: func() bool {
 			if req.OpsMonitoringEnabled != nil {
 				return *req.OpsMonitoringEnabled
@@ -420,6 +437,7 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		OpsRealtimeMonitoringEnabled:         updatedSettings.OpsRealtimeMonitoringEnabled,
 		OpsQueryModeDefault:                  updatedSettings.OpsQueryModeDefault,
 		OpsMetricsIntervalSeconds:            updatedSettings.OpsMetricsIntervalSeconds,
+		MinClaudeCodeVersion:                 updatedSettings.MinClaudeCodeVersion,
 	})
 }
 
@@ -562,6 +580,9 @@ func diffSettings(before *service.SystemSettings, after *service.SystemSettings,
 	if before.OpsMetricsIntervalSeconds != after.OpsMetricsIntervalSeconds {
 		changed = append(changed, "ops_metrics_interval_seconds")
 	}
+	if before.MinClaudeCodeVersion != after.MinClaudeCodeVersion {
+		changed = append(changed, "min_claude_code_version")
+	}
 	return changed
 }
 

backend/internal/handler/admin/setting_handler.go

@@ -58,6 +58,8 @@ type SystemSettings struct {
 	OpsRealtimeMonitoringEnabled bool   `json:"ops_realtime_monitoring_enabled"`
 	OpsQueryModeDefault          string `json:"ops_query_mode_default"`
 	OpsMetricsIntervalSeconds    int    `json:"ops_metrics_interval_seconds"`
+
+	MinClaudeCodeVersion string `json:"min_claude_code_version"`
 }
 
 type PublicSettings struct {

backend/internal/handler/dto/settings.go

@@ -48,6 +48,7 @@ type GatewayHandler struct {
 	maxAccountSwitches        int
 	maxAccountSwitchesGemini  int
 	cfg                       *config.Config
+	settingService            *service.SettingService
 }
 
 // NewGatewayHandler creates a new GatewayHandler
@@ -63,6 +64,7 @@ func NewGatewayHandler(
 	usageRecordWorkerPool *service.UsageRecordWorkerPool,
 	errorPassthroughService *service.ErrorPassthroughService,
 	cfg *config.Config,
+	settingService *service.SettingService,
 ) *GatewayHandler {
 	pingInterval := time.Duration(0)
 	maxAccountSwitches := 10
@@ -90,6 +92,7 @@ func NewGatewayHandler(
 		maxAccountSwitches:        maxAccountSwitches,
 		maxAccountSwitchesGemini:  maxAccountSwitchesGemini,
 		cfg:                       cfg,
+		settingService:            settingService,
 	}
 }
 
@@ -155,6 +158,11 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 	SetClaudeCodeClientContext(c, body, parsedReq)
 	isClaudeCodeClient := service.IsClaudeCodeClient(c.Request.Context())
 
+	// 版本检查：仅对 Claude Code 客户端，拒绝低于最低版本的请求
+	if !h.checkClaudeCodeVersion(c) {
+		return
+	}
+
 	// 在请求上下文中记录 thinking 状态，供 Antigravity 最终模型 key 推导/模型维度限流使用
 	c.Request = c.Request.WithContext(service.WithThinkingEnabled(c.Request.Context(), parsedReq.ThinkingEnabled, h.metadataBridgeEnabled()))
 
@@ -1003,6 +1011,41 @@ func (h *GatewayHandler) ensureForwardErrorResponse(c *gin.Context, streamStarte
 	return true
 }
 
+// checkClaudeCodeVersion 检查 Claude Code 客户端版本是否满足最低要求
+// 仅对已识别的 Claude Code 客户端执行，count_tokens 路径除外
+func (h *GatewayHandler) checkClaudeCodeVersion(c *gin.Context) bool {
+	ctx := c.Request.Context()
+	if !service.IsClaudeCodeClient(ctx) {
+		return true
+	}
+
+	// 排除 count_tokens 子路径
+	if strings.HasSuffix(c.Request.URL.Path, "/count_tokens") {
+		return true
+	}
+
+	minVersion := h.settingService.GetMinClaudeCodeVersion(ctx)
+	if minVersion == "" {
+		return true // 未设置，不检查
+	}
+
+	clientVersion := service.GetClaudeCodeVersion(ctx)
+	if clientVersion == "" {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error",
+			"Unable to determine Claude Code version. Please update Claude Code: npm update -g @anthropic-ai/claude-code")
+		return false
+	}
+
+	if service.CompareVersions(clientVersion, minVersion) < 0 {
+		h.errorResponse(c, http.StatusBadRequest, "invalid_request_error",
+			fmt.Sprintf("Your Claude Code version (%s) is below the minimum required version (%s). Please update: npm update -g @anthropic-ai/claude-code",
+				clientVersion, minVersion))
+		return false
+	}
+
+	return true
+}
+
 // errorResponse 返回Claude API格式的错误响应
 func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, message string) {
 	c.JSON(status, gin.H{

backend/internal/handler/gateway_handler.go

@@ -29,8 +29,10 @@ func SetClaudeCodeClientContext(c *gin.Context, body []byte, parsedReq *service.
 	if parsedReq != nil {
 		c.Set(claudeCodeParsedRequestContextKey, parsedReq)
 	}
+
+	ua := c.GetHeader("User-Agent")
 	// Fast path：非 Claude CLI UA 直接判定 false，避免热路径二次 JSON 反序列化。
-	if !claudeCodeValidator.ValidateUserAgent(c.GetHeader("User-Agent")) {
+	if !claudeCodeValidator.ValidateUserAgent(ua) {
 		ctx := service.SetClaudeCodeClient(c.Request.Context(), false)
 		c.Request = c.Request.WithContext(ctx)
 		return
@@ -54,6 +56,14 @@ func SetClaudeCodeClientContext(c *gin.Context, body []byte, parsedReq *service.
 
 	// 更新 request context
 	ctx := service.SetClaudeCodeClient(c.Request.Context(), isClaudeCode)
+
+	// 仅在确认为 Claude Code 客户端时提取版本号写入 context
+	if isClaudeCode {
+		if version := claudeCodeValidator.ExtractVersion(ua); version != "" {
+			ctx = service.SetClaudeCodeVersion(ctx, version)
+		}
+	}
+
 	c.Request = c.Request.WithContext(ctx)
 }
 

backend/internal/handler/gateway_helper.go

@@ -52,4 +52,7 @@ const (
 	// PrefetchedStickyGroupID 标识上游预取 sticky session 时所使用的分组 ID。
 	// Service 层仅在分组匹配时复用 PrefetchedStickyAccountID，避免分组切换重试误用旧 sticky。
 	PrefetchedStickyGroupID Key = "ctx_prefetched_sticky_group_id"
+
+	// ClaudeCodeVersion stores the extracted Claude Code version from User-Agent (e.g. "2.1.22")
+	ClaudeCodeVersion Key = "ctx_claude_code_version"
 )

backend/internal/pkg/ctxkey/ctxkey.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"net/http"
 	"regexp"
+	"strconv"
 	"strings"
 
 	"github.com/Wei-Shaw/sub2api/internal/pkg/ctxkey"
@@ -17,6 +18,9 @@ var (
 	// User-Agent 匹配: claude-cli/x.x.x (仅支持官方 CLI，大小写不敏感)
 	claudeCodeUAPattern = regexp.MustCompile(`(?i)^claude-cli/\d+\.\d+\.\d+`)
 
+	// 带捕获组的版本提取正则
+	claudeCodeUAVersionPattern = regexp.MustCompile(`(?i)^claude-cli/(\d+\.\d+\.\d+)`)
+
 	// metadata.user_id 格式: user_{64位hex}_account__session_{uuid}
 	userIDPattern = regexp.MustCompile(`^user_[a-fA-F0-9]{64}_account__session_[\w-]+$`)
 
@@ -270,3 +274,55 @@ func IsClaudeCodeClient(ctx context.Context) bool {
 func SetClaudeCodeClient(ctx context.Context, isClaudeCode bool) context.Context {
 	return context.WithValue(ctx, ctxkey.IsClaudeCodeClient, isClaudeCode)
 }
+
+// ExtractVersion 从 User-Agent 中提取 Claude Code 版本号
+// 返回 "2.1.22" 形式的版本号，如果不匹配返回空字符串
+func (v *ClaudeCodeValidator) ExtractVersion(ua string) string {
+	matches := claudeCodeUAVersionPattern.FindStringSubmatch(ua)
+	if len(matches) >= 2 {
+		return matches[1]
+	}
+	return ""
+}
+
+// SetClaudeCodeVersion 将 Claude Code 版本号设置到 context 中
+func SetClaudeCodeVersion(ctx context.Context, version string) context.Context {
+	return context.WithValue(ctx, ctxkey.ClaudeCodeVersion, version)
+}
+
+// GetClaudeCodeVersion 从 context 中获取 Claude Code 版本号
+func GetClaudeCodeVersion(ctx context.Context) string {
+	if v, ok := ctx.Value(ctxkey.ClaudeCodeVersion).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// CompareVersions 比较两个 semver 版本号
+// 返回: -1 (a < b), 0 (a == b), 1 (a > b)
+func CompareVersions(a, b string) int {
+	aParts := parseSemver(a)
+	bParts := parseSemver(b)
+	for i := 0; i < 3; i++ {
+		if aParts[i] < bParts[i] {
+			return -1
+		}
+		if aParts[i] > bParts[i] {
+			return 1
+		}
+	}
+	return 0
+}
+
+// parseSemver 解析 semver 版本号为 [major, minor, patch]
+func parseSemver(v string) [3]int {
+	v = strings.TrimPrefix(v, "v")
+	parts := strings.Split(v, ".")
+	result := [3]int{0, 0, 0}
+	for i := 0; i < len(parts) && i < 3; i++ {
+		if parsed, err := strconv.Atoi(parts[i]); err == nil {
+			result[i] = parsed
+		}
+	}
+	return result
+}

backend/internal/service/claude_code_validator.go

@@ -56,3 +56,51 @@ func TestClaudeCodeValidator_NonMessagesPathUAOnly(t *testing.T) {
 	ok := validator.Validate(req, nil)
 	require.True(t, ok)
 }
+
+func TestExtractVersion(t *testing.T) {
+	v := NewClaudeCodeValidator()
+	tests := []struct {
+		ua   string
+		want string
+	}{
+		{"claude-cli/2.1.22 (darwin; arm64)", "2.1.22"},
+		{"claude-cli/1.0.0", "1.0.0"},
+		{"Claude-CLI/3.10.5 (linux; x86_64)", "3.10.5"},  // 大小写不敏感
+		{"curl/8.0.0", ""},                                 // 非 Claude CLI
+		{"", ""},                                           // 空字符串
+		{"claude-cli/", ""},                                // 无版本号
+		{"claude-cli/2.1.22-beta", "2.1.22"},               // 带后缀仍提取主版本号
+	}
+	for _, tt := range tests {
+		got := v.ExtractVersion(tt.ua)
+		require.Equal(t, tt.want, got, "ExtractVersion(%q)", tt.ua)
+	}
+}
+
+func TestCompareVersions(t *testing.T) {
+	tests := []struct {
+		a, b string
+		want int
+	}{
+		{"2.1.0", "2.1.0", 0},    // 相等
+		{"2.1.1", "2.1.0", 1},    // patch 更大
+		{"2.0.0", "2.1.0", -1},   // minor 更小
+		{"3.0.0", "2.99.99", 1},  // major 更大
+		{"1.0.0", "2.0.0", -1},   // major 更小
+		{"0.0.1", "0.0.0", 1},    // patch 差异
+		{"", "1.0.0", -1},        // 空字符串 vs 正常版本
+		{"v2.1.0", "2.1.0", 0},   // v 前缀处理
+	}
+	for _, tt := range tests {
+		got := CompareVersions(tt.a, tt.b)
+		require.Equal(t, tt.want, got, "CompareVersions(%q, %q)", tt.a, tt.b)
+	}
+}
+
+func TestSetGetClaudeCodeVersion(t *testing.T) {
+	ctx := context.Background()
+	require.Equal(t, "", GetClaudeCodeVersion(ctx), "empty context should return empty string")
+
+	ctx = SetClaudeCodeVersion(ctx, "2.1.63")
+	require.Equal(t, "2.1.63", GetClaudeCodeVersion(ctx))
+}

backend/internal/service/claude_code_validator_test.go

@@ -192,6 +192,13 @@ const (
 	// =========================
 
 	SettingKeySoraDefaultStorageQuotaBytes = "sora_default_storage_quota_bytes" // 新用户默认 Sora 存储配额（字节）
+
+	// =========================
+	// Claude Code Version Check
+	// =========================
+
+	// SettingKeyMinClaudeCodeVersion 最低 Claude Code 版本号要求 (semver, 如 "2.1.0"，空值=不检查)
+	SettingKeyMinClaudeCodeVersion = "min_claude_code_version"
 )
 
 // AdminAPIKeyPrefix is the prefix for admin API keys (distinct from user "sk-" keys).