chore: 更新依赖、配置和代码生成

主要更新： - 更新 go.mod/go.sum 依赖 - 重新生成 Ent ORM 代码 - 更新 Wire 依赖注入配置 - 添加 docker-compose.override.yml 到 .gitignore - 更新 README 文档（Simple Mode 说明和已知问题） - 清理调试日志 - 其他代码优化和格式修复
2026-01-03 06:37:08 -08:00
parent b1702de522
commit 112a2d0866
121 changed files with 3058 additions and 2948 deletions
--- a/backend/internal/server/http.go
+++ b/backend/internal/server/http.go
@@ -1,4 +1,3 @@
-// Package server provides HTTP server setup and routing configuration.
 package server

 import (
@@ -26,8 +25,8 @@ func ProvideRouter(
 	handlers *handler.Handlers,
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
-	apiKeyAuth middleware2.APIKeyAuthMiddleware,
-	apiKeyService *service.APIKeyService,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
 	subscriptionService *service.SubscriptionService,
 ) *gin.Engine {
 	if cfg.Server.Mode == "release" {
--- a/backend/internal/server/middleware/admin_auth.go
+++ b/backend/internal/server/middleware/admin_auth.go
@@ -32,7 +32,7 @@ func adminAuth(
 		// 检查 x-api-key header（Admin API Key 认证）
 		apiKey := c.GetHeader("x-api-key")
 		if apiKey != "" {
-			if !validateAdminAPIKey(c, apiKey, settingService, userService) {
+			if !validateAdminApiKey(c, apiKey, settingService, userService) {
 				return
 			}
 			c.Next()
@@ -52,48 +52,19 @@ func adminAuth(
 			}
 		}

-		// WebSocket 请求无法设置自定义 header，允许在 query 中携带凭证
-		if isWebSocketRequest(c) {
-			if token := strings.TrimSpace(c.Query("token")); token != "" {
-				if !validateJWTForAdmin(c, token, authService, userService) {
-					return
-				}
-				c.Next()
-				return
-			}
-			if apiKey := strings.TrimSpace(c.Query("api_key")); apiKey != "" {
-				if !validateAdminAPIKey(c, apiKey, settingService, userService) {
-					return
-				}
-				c.Next()
-				return
-			}
-		}
-
 		// 无有效认证信息
 		AbortWithError(c, 401, "UNAUTHORIZED", "Authorization required")
 	}
 }

-func isWebSocketRequest(c *gin.Context) bool {
-	if c == nil || c.Request == nil {
-		return false
-	}
-	if strings.EqualFold(c.GetHeader("Upgrade"), "websocket") {
-		return true
-	}
-	conn := strings.ToLower(c.GetHeader("Connection"))
-	return strings.Contains(conn, "upgrade") && strings.EqualFold(c.GetHeader("Upgrade"), "websocket")
-}
-
-// validateAdminAPIKey 验证管理员 API Key
-func validateAdminAPIKey(
+// validateAdminApiKey 验证管理员 API Key
+func validateAdminApiKey(
 	c *gin.Context,
 	key string,
 	settingService *service.SettingService,
 	userService *service.UserService,
 ) bool {
-	storedKey, err := settingService.GetAdminAPIKey(c.Request.Context())
+	storedKey, err := settingService.GetAdminApiKey(c.Request.Context())
 	if err != nil {
 		AbortWithError(c, 500, "INTERNAL_ERROR", "Internal server error")
 		return false
--- a/backend/internal/server/middleware/api_key_auth.go
+++ b/backend/internal/server/middleware/api_key_auth.go
@@ -11,13 +11,13 @@ import (
 	"github.com/gin-gonic/gin"
 )

-// NewAPIKeyAuthMiddleware 创建 API Key 认证中间件
-func NewAPIKeyAuthMiddleware(apiKeyService *service.APIKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config, opsService *service.OpsService) APIKeyAuthMiddleware {
-	return APIKeyAuthMiddleware(apiKeyAuthWithSubscription(apiKeyService, subscriptionService, cfg, opsService))
+// NewApiKeyAuthMiddleware 创建 API Key 认证中间件
+func NewApiKeyAuthMiddleware(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) ApiKeyAuthMiddleware {
+	return ApiKeyAuthMiddleware(apiKeyAuthWithSubscription(apiKeyService, subscriptionService, cfg))
 }

 // apiKeyAuthWithSubscription API Key认证中间件（支持订阅验证）
-func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config, opsService *service.OpsService) gin.HandlerFunc {
+func apiKeyAuthWithSubscription(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		// 尝试从Authorization header中提取API key (Bearer scheme)
 		authHeader := c.GetHeader("Authorization")
@@ -53,7 +53,6 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti

 		// 如果所有header都没有API key
 		if apiKeyString == "" {
-			recordOpsAuthError(c, opsService, nil, 401, "API key is required in Authorization header (Bearer scheme), x-api-key header, x-goog-api-key header, or key/api_key query parameter")
 			AbortWithError(c, 401, "API_KEY_REQUIRED", "API key is required in Authorization header (Bearer scheme), x-api-key header, x-goog-api-key header, or key/api_key query parameter")
 			return
 		}
@@ -61,40 +60,35 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 		// 从数据库验证API key
 		apiKey, err := apiKeyService.GetByKey(c.Request.Context(), apiKeyString)
 		if err != nil {
-			if errors.Is(err, service.ErrAPIKeyNotFound) {
-				recordOpsAuthError(c, opsService, nil, 401, "Invalid API key")
+			if errors.Is(err, service.ErrApiKeyNotFound) {
 				AbortWithError(c, 401, "INVALID_API_KEY", "Invalid API key")
 				return
 			}
-			recordOpsAuthError(c, opsService, nil, 500, "Failed to validate API key")
 			AbortWithError(c, 500, "INTERNAL_ERROR", "Failed to validate API key")
 			return
 		}

 		// 检查API key是否激活
 		if !apiKey.IsActive() {
-			recordOpsAuthError(c, opsService, apiKey, 401, "API key is disabled")
 			AbortWithError(c, 401, "API_KEY_DISABLED", "API key is disabled")
 			return
 		}

 		// 检查关联的用户
 		if apiKey.User == nil {
-			recordOpsAuthError(c, opsService, apiKey, 401, "User associated with API key not found")
 			AbortWithError(c, 401, "USER_NOT_FOUND", "User associated with API key not found")
 			return
 		}

 		// 检查用户状态
 		if !apiKey.User.IsActive() {
-			recordOpsAuthError(c, opsService, apiKey, 401, "User account is not active")
 			AbortWithError(c, 401, "USER_INACTIVE", "User account is not active")
 			return
 		}

 		if cfg.RunMode == config.RunModeSimple {
 			// 简易模式：跳过余额和订阅检查，但仍需设置必要的上下文
-			c.Set(string(ContextKeyAPIKey), apiKey)
+			c.Set(string(ContextKeyApiKey), apiKey)
 			c.Set(string(ContextKeyUser), AuthSubject{
 				UserID:      apiKey.User.ID,
 				Concurrency: apiKey.User.Concurrency,
@@ -115,14 +109,12 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 				apiKey.Group.ID,
 			)
 			if err != nil {
-				recordOpsAuthError(c, opsService, apiKey, 403, "No active subscription found for this group")
 				AbortWithError(c, 403, "SUBSCRIPTION_NOT_FOUND", "No active subscription found for this group")
 				return
 			}

 			// 验证订阅状态（是否过期、暂停等）
 			if err := subscriptionService.ValidateSubscription(c.Request.Context(), subscription); err != nil {
-				recordOpsAuthError(c, opsService, apiKey, 403, err.Error())
 				AbortWithError(c, 403, "SUBSCRIPTION_INVALID", err.Error())
 				return
 			}
@@ -139,7 +131,6 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti

 			// 预检查用量限制（使用0作为额外费用进行预检查）
 			if err := subscriptionService.CheckUsageLimits(c.Request.Context(), subscription, apiKey.Group, 0); err != nil {
-				recordOpsAuthError(c, opsService, apiKey, 429, err.Error())
 				AbortWithError(c, 429, "USAGE_LIMIT_EXCEEDED", err.Error())
 				return
 			}
@@ -149,14 +140,13 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 		} else {
 			// 余额模式：检查用户余额
 			if apiKey.User.Balance <= 0 {
-				recordOpsAuthError(c, opsService, apiKey, 403, "Insufficient account balance")
 				AbortWithError(c, 403, "INSUFFICIENT_BALANCE", "Insufficient account balance")
 				return
 			}
 		}

 		// 将API key和用户信息存入上下文
-		c.Set(string(ContextKeyAPIKey), apiKey)
+		c.Set(string(ContextKeyApiKey), apiKey)
 		c.Set(string(ContextKeyUser), AuthSubject{
 			UserID:      apiKey.User.ID,
 			Concurrency: apiKey.User.Concurrency,
@@ -167,66 +157,13 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 	}
 }

-func recordOpsAuthError(c *gin.Context, opsService *service.OpsService, apiKey *service.APIKey, status int, message string) {
-	if opsService == nil || c == nil {
-		return
-	}
-
-	errType := "authentication_error"
-	phase := "auth"
-	severity := "P3"
-	switch status {
-	case 403:
-		errType = "billing_error"
-		phase = "billing"
-	case 429:
-		errType = "rate_limit_error"
-		phase = "billing"
-		severity = "P2"
-	case 500:
-		errType = "api_error"
-		phase = "internal"
-		severity = "P1"
-	}
-
-	logEntry := &service.OpsErrorLog{
-		Phase:      phase,
-		Type:       errType,
-		Severity:   severity,
-		StatusCode: status,
-		Message:    message,
-		ClientIP:   c.ClientIP(),
-		RequestPath: func() string {
-			if c.Request != nil && c.Request.URL != nil {
-				return c.Request.URL.Path
-			}
-			return ""
-		}(),
-	}
-
-	if apiKey != nil {
-		logEntry.APIKeyID = &apiKey.ID
-		if apiKey.User != nil {
-			logEntry.UserID = &apiKey.User.ID
-		}
-		if apiKey.GroupID != nil {
-			logEntry.GroupID = apiKey.GroupID
-		}
-		if apiKey.Group != nil {
-			logEntry.Platform = apiKey.Group.Platform
-		}
-	}
-
-	enqueueOpsAuthErrorLog(opsService, logEntry)
-}
-
-// GetAPIKeyFromContext 从上下文中获取API key
-func GetAPIKeyFromContext(c *gin.Context) (*service.APIKey, bool) {
-	value, exists := c.Get(string(ContextKeyAPIKey))
+// GetApiKeyFromContext 从上下文中获取API key
+func GetApiKeyFromContext(c *gin.Context) (*service.ApiKey, bool) {
+	value, exists := c.Get(string(ContextKeyApiKey))
 	if !exists {
 		return nil, false
 	}
-	apiKey, ok := value.(*service.APIKey)
+	apiKey, ok := value.(*service.ApiKey)
 	return apiKey, ok
 }

--- a/backend/internal/server/middleware/api_key_auth_google.go
+++ b/backend/internal/server/middleware/api_key_auth_google.go
@@ -11,16 +11,16 @@ import (
 	"github.com/gin-gonic/gin"
 )

-// APIKeyAuthGoogle is a Google-style error wrapper for API key auth.
-func APIKeyAuthGoogle(apiKeyService *service.APIKeyService, cfg *config.Config) gin.HandlerFunc {
-	return APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, cfg)
+// ApiKeyAuthGoogle is a Google-style error wrapper for API key auth.
+func ApiKeyAuthGoogle(apiKeyService *service.ApiKeyService, cfg *config.Config) gin.HandlerFunc {
+	return ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, cfg)
 }

-// APIKeyAuthWithSubscriptionGoogle behaves like APIKeyAuthWithSubscription but returns Google-style errors:
+// ApiKeyAuthWithSubscriptionGoogle behaves like ApiKeyAuthWithSubscription but returns Google-style errors:
 // {"error":{"code":401,"message":"...","status":"UNAUTHENTICATED"}}
 //
 // It is intended for Gemini native endpoints (/v1beta) to match Gemini SDK expectations.
-func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) gin.HandlerFunc {
+func ApiKeyAuthWithSubscriptionGoogle(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		apiKeyString := extractAPIKeyFromRequest(c)
 		if apiKeyString == "" {
@@ -30,7 +30,7 @@ func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subs

 		apiKey, err := apiKeyService.GetByKey(c.Request.Context(), apiKeyString)
 		if err != nil {
-			if errors.Is(err, service.ErrAPIKeyNotFound) {
+			if errors.Is(err, service.ErrApiKeyNotFound) {
 				abortWithGoogleError(c, 401, "Invalid API key")
 				return
 			}
@@ -53,7 +53,7 @@ func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subs

 		// 简易模式：跳过余额和订阅检查
 		if cfg.RunMode == config.RunModeSimple {
-			c.Set(string(ContextKeyAPIKey), apiKey)
+			c.Set(string(ContextKeyApiKey), apiKey)
 			c.Set(string(ContextKeyUser), AuthSubject{
 				UserID:      apiKey.User.ID,
 				Concurrency: apiKey.User.Concurrency,
@@ -92,7 +92,7 @@ func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subs
 			}
 		}

-		c.Set(string(ContextKeyAPIKey), apiKey)
+		c.Set(string(ContextKeyApiKey), apiKey)
 		c.Set(string(ContextKeyUser), AuthSubject{
 			UserID:      apiKey.User.ID,
 			Concurrency: apiKey.User.Concurrency,
--- a/backend/internal/server/middleware/api_key_auth_google_test.go
+++ b/backend/internal/server/middleware/api_key_auth_google_test.go
@@ -16,53 +16,53 @@ import (
 	"github.com/stretchr/testify/require"
 )

-type fakeAPIKeyRepo struct {
-	getByKey func(ctx context.Context, key string) (*service.APIKey, error)
+type fakeApiKeyRepo struct {
+	getByKey func(ctx context.Context, key string) (*service.ApiKey, error)
 }

-func (f fakeAPIKeyRepo) Create(ctx context.Context, key *service.APIKey) error {
+func (f fakeApiKeyRepo) Create(ctx context.Context, key *service.ApiKey) error {
 	return errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) GetByID(ctx context.Context, id int64) (*service.APIKey, error) {
+func (f fakeApiKeyRepo) GetByID(ctx context.Context, id int64) (*service.ApiKey, error) {
 	return nil, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) GetOwnerID(ctx context.Context, id int64) (int64, error) {
+func (f fakeApiKeyRepo) GetOwnerID(ctx context.Context, id int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) GetByKey(ctx context.Context, key string) (*service.APIKey, error) {
+func (f fakeApiKeyRepo) GetByKey(ctx context.Context, key string) (*service.ApiKey, error) {
 	if f.getByKey == nil {
 		return nil, errors.New("unexpected call")
 	}
 	return f.getByKey(ctx, key)
 }
-func (f fakeAPIKeyRepo) Update(ctx context.Context, key *service.APIKey) error {
+func (f fakeApiKeyRepo) Update(ctx context.Context, key *service.ApiKey) error {
 	return errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) Delete(ctx context.Context, id int64) error {
+func (f fakeApiKeyRepo) Delete(ctx context.Context, id int64) error {
 	return errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]service.APIKey, *pagination.PaginationResult, error) {
+func (f fakeApiKeyRepo) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]service.ApiKey, *pagination.PaginationResult, error) {
 	return nil, nil, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) VerifyOwnership(ctx context.Context, userID int64, apiKeyIDs []int64) ([]int64, error) {
+func (f fakeApiKeyRepo) VerifyOwnership(ctx context.Context, userID int64, apiKeyIDs []int64) ([]int64, error) {
 	return nil, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) CountByUserID(ctx context.Context, userID int64) (int64, error) {
+func (f fakeApiKeyRepo) CountByUserID(ctx context.Context, userID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) ExistsByKey(ctx context.Context, key string) (bool, error) {
+func (f fakeApiKeyRepo) ExistsByKey(ctx context.Context, key string) (bool, error) {
 	return false, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]service.APIKey, *pagination.PaginationResult, error) {
+func (f fakeApiKeyRepo) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]service.ApiKey, *pagination.PaginationResult, error) {
 	return nil, nil, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) SearchAPIKeys(ctx context.Context, userID int64, keyword string, limit int) ([]service.APIKey, error) {
+func (f fakeApiKeyRepo) SearchApiKeys(ctx context.Context, userID int64, keyword string, limit int) ([]service.ApiKey, error) {
 	return nil, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (f fakeApiKeyRepo) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }
-func (f fakeAPIKeyRepo) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (f fakeApiKeyRepo) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }

@@ -74,8 +74,8 @@ type googleErrorResponse struct {
 	} `json:"error"`
 }

-func newTestAPIKeyService(repo service.APIKeyRepository) *service.APIKeyService {
-	return service.NewAPIKeyService(
+func newTestApiKeyService(repo service.ApiKeyRepository) *service.ApiKeyService {
+	return service.NewApiKeyService(
 		repo,
 		nil, // userRepo (unused in GetByKey)
 		nil, // groupRepo
@@ -85,16 +85,16 @@ func newTestAPIKeyService(repo service.APIKeyRepository) *service.APIKeyService
 	)
 }

-func TestAPIKeyAuthWithSubscriptionGoogle_MissingKey(t *testing.T) {
+func TestApiKeyAuthWithSubscriptionGoogle_MissingKey(t *testing.T) {
 	gin.SetMode(gin.TestMode)

 	r := gin.New()
-	apiKeyService := newTestAPIKeyService(fakeAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
+	apiKeyService := newTestApiKeyService(fakeApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
 			return nil, errors.New("should not be called")
 		},
 	})
-	r.Use(APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
+	r.Use(ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
 	r.GET("/v1beta/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

 	req := httptest.NewRequest(http.MethodGet, "/v1beta/test", nil)
@@ -109,16 +109,16 @@ func TestAPIKeyAuthWithSubscriptionGoogle_MissingKey(t *testing.T) {
 	require.Equal(t, "UNAUTHENTICATED", resp.Error.Status)
 }

-func TestAPIKeyAuthWithSubscriptionGoogle_InvalidKey(t *testing.T) {
+func TestApiKeyAuthWithSubscriptionGoogle_InvalidKey(t *testing.T) {
 	gin.SetMode(gin.TestMode)

 	r := gin.New()
-	apiKeyService := newTestAPIKeyService(fakeAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
-			return nil, service.ErrAPIKeyNotFound
+	apiKeyService := newTestApiKeyService(fakeApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
+			return nil, service.ErrApiKeyNotFound
 		},
 	})
-	r.Use(APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
+	r.Use(ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
 	r.GET("/v1beta/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

 	req := httptest.NewRequest(http.MethodGet, "/v1beta/test", nil)
@@ -134,16 +134,16 @@ func TestAPIKeyAuthWithSubscriptionGoogle_InvalidKey(t *testing.T) {
 	require.Equal(t, "UNAUTHENTICATED", resp.Error.Status)
 }

-func TestAPIKeyAuthWithSubscriptionGoogle_RepoError(t *testing.T) {
+func TestApiKeyAuthWithSubscriptionGoogle_RepoError(t *testing.T) {
 	gin.SetMode(gin.TestMode)

 	r := gin.New()
-	apiKeyService := newTestAPIKeyService(fakeAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
+	apiKeyService := newTestApiKeyService(fakeApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
 			return nil, errors.New("db down")
 		},
 	})
-	r.Use(APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
+	r.Use(ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
 	r.GET("/v1beta/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

 	req := httptest.NewRequest(http.MethodGet, "/v1beta/test", nil)
@@ -159,13 +159,13 @@ func TestAPIKeyAuthWithSubscriptionGoogle_RepoError(t *testing.T) {
 	require.Equal(t, "INTERNAL", resp.Error.Status)
 }

-func TestAPIKeyAuthWithSubscriptionGoogle_DisabledKey(t *testing.T) {
+func TestApiKeyAuthWithSubscriptionGoogle_DisabledKey(t *testing.T) {
 	gin.SetMode(gin.TestMode)

 	r := gin.New()
-	apiKeyService := newTestAPIKeyService(fakeAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
-			return &service.APIKey{
+	apiKeyService := newTestApiKeyService(fakeApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
+			return &service.ApiKey{
 				ID:     1,
 				Key:    key,
 				Status: service.StatusDisabled,
@@ -176,7 +176,7 @@ func TestAPIKeyAuthWithSubscriptionGoogle_DisabledKey(t *testing.T) {
 			}, nil
 		},
 	})
-	r.Use(APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
+	r.Use(ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
 	r.GET("/v1beta/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

 	req := httptest.NewRequest(http.MethodGet, "/v1beta/test", nil)
@@ -192,13 +192,13 @@ func TestAPIKeyAuthWithSubscriptionGoogle_DisabledKey(t *testing.T) {
 	require.Equal(t, "UNAUTHENTICATED", resp.Error.Status)
 }

-func TestAPIKeyAuthWithSubscriptionGoogle_InsufficientBalance(t *testing.T) {
+func TestApiKeyAuthWithSubscriptionGoogle_InsufficientBalance(t *testing.T) {
 	gin.SetMode(gin.TestMode)

 	r := gin.New()
-	apiKeyService := newTestAPIKeyService(fakeAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
-			return &service.APIKey{
+	apiKeyService := newTestApiKeyService(fakeApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
+			return &service.ApiKey{
 				ID:     1,
 				Key:    key,
 				Status: service.StatusActive,
@@ -210,7 +210,7 @@ func TestAPIKeyAuthWithSubscriptionGoogle_InsufficientBalance(t *testing.T) {
 			}, nil
 		},
 	})
-	r.Use(APIKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
+	r.Use(ApiKeyAuthWithSubscriptionGoogle(apiKeyService, nil, &config.Config{}))
 	r.GET("/v1beta/test", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

 	req := httptest.NewRequest(http.MethodGet, "/v1beta/test", nil)
--- a/backend/internal/server/middleware/api_key_auth_test.go
+++ b/backend/internal/server/middleware/api_key_auth_test.go
@@ -35,7 +35,7 @@ func TestSimpleModeBypassesQuotaCheck(t *testing.T) {
 		Balance:     10,
 		Concurrency: 3,
 	}
-	apiKey := &service.APIKey{
+	apiKey := &service.ApiKey{
 		ID:     100,
 		UserID: user.ID,
 		Key:    "test-key",
@@ -45,10 +45,10 @@ func TestSimpleModeBypassesQuotaCheck(t *testing.T) {
 	}
 	apiKey.GroupID = &group.ID

-	apiKeyRepo := &stubAPIKeyRepo{
-		getByKey: func(ctx context.Context, key string) (*service.APIKey, error) {
+	apiKeyRepo := &stubApiKeyRepo{
+		getByKey: func(ctx context.Context, key string) (*service.ApiKey, error) {
 			if key != apiKey.Key {
-				return nil, service.ErrAPIKeyNotFound
+				return nil, service.ErrApiKeyNotFound
 			}
 			clone := *apiKey
 			return &clone, nil
@@ -57,7 +57,7 @@ func TestSimpleModeBypassesQuotaCheck(t *testing.T) {

 	t.Run("simple_mode_bypasses_quota_check", func(t *testing.T) {
 		cfg := &config.Config{RunMode: config.RunModeSimple}
-		apiKeyService := service.NewAPIKeyService(apiKeyRepo, nil, nil, nil, nil, cfg)
+		apiKeyService := service.NewApiKeyService(apiKeyRepo, nil, nil, nil, nil, cfg)
 		subscriptionService := service.NewSubscriptionService(nil, &stubUserSubscriptionRepo{}, nil)
 		router := newAuthTestRouter(apiKeyService, subscriptionService, cfg)

@@ -71,7 +71,7 @@ func TestSimpleModeBypassesQuotaCheck(t *testing.T) {

 	t.Run("standard_mode_enforces_quota_check", func(t *testing.T) {
 		cfg := &config.Config{RunMode: config.RunModeStandard}
-		apiKeyService := service.NewAPIKeyService(apiKeyRepo, nil, nil, nil, nil, cfg)
+		apiKeyService := service.NewApiKeyService(apiKeyRepo, nil, nil, nil, nil, cfg)

 		now := time.Now()
 		sub := &service.UserSubscription{
@@ -110,75 +110,75 @@ func TestSimpleModeBypassesQuotaCheck(t *testing.T) {
 	})
 }

-func newAuthTestRouter(apiKeyService *service.APIKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) *gin.Engine {
+func newAuthTestRouter(apiKeyService *service.ApiKeyService, subscriptionService *service.SubscriptionService, cfg *config.Config) *gin.Engine {
 	router := gin.New()
-	router.Use(gin.HandlerFunc(NewAPIKeyAuthMiddleware(apiKeyService, subscriptionService, cfg, nil)))
+	router.Use(gin.HandlerFunc(NewApiKeyAuthMiddleware(apiKeyService, subscriptionService, cfg)))
 	router.GET("/t", func(c *gin.Context) {
 		c.JSON(http.StatusOK, gin.H{"ok": true})
 	})
 	return router
 }

-type stubAPIKeyRepo struct {
-	getByKey func(ctx context.Context, key string) (*service.APIKey, error)
+type stubApiKeyRepo struct {
+	getByKey func(ctx context.Context, key string) (*service.ApiKey, error)
 }

-func (r *stubAPIKeyRepo) Create(ctx context.Context, key *service.APIKey) error {
+func (r *stubApiKeyRepo) Create(ctx context.Context, key *service.ApiKey) error {
 	return errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) GetByID(ctx context.Context, id int64) (*service.APIKey, error) {
+func (r *stubApiKeyRepo) GetByID(ctx context.Context, id int64) (*service.ApiKey, error) {
 	return nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) GetOwnerID(ctx context.Context, id int64) (int64, error) {
+func (r *stubApiKeyRepo) GetOwnerID(ctx context.Context, id int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) GetByKey(ctx context.Context, key string) (*service.APIKey, error) {
+func (r *stubApiKeyRepo) GetByKey(ctx context.Context, key string) (*service.ApiKey, error) {
 	if r.getByKey != nil {
 		return r.getByKey(ctx, key)
 	}
 	return nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) Update(ctx context.Context, key *service.APIKey) error {
+func (r *stubApiKeyRepo) Update(ctx context.Context, key *service.ApiKey) error {
 	return errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) Delete(ctx context.Context, id int64) error {
+func (r *stubApiKeyRepo) Delete(ctx context.Context, id int64) error {
 	return errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]service.APIKey, *pagination.PaginationResult, error) {
+func (r *stubApiKeyRepo) ListByUserID(ctx context.Context, userID int64, params pagination.PaginationParams) ([]service.ApiKey, *pagination.PaginationResult, error) {
 	return nil, nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) VerifyOwnership(ctx context.Context, userID int64, apiKeyIDs []int64) ([]int64, error) {
+func (r *stubApiKeyRepo) VerifyOwnership(ctx context.Context, userID int64, apiKeyIDs []int64) ([]int64, error) {
 	return nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) CountByUserID(ctx context.Context, userID int64) (int64, error) {
+func (r *stubApiKeyRepo) CountByUserID(ctx context.Context, userID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) ExistsByKey(ctx context.Context, key string) (bool, error) {
+func (r *stubApiKeyRepo) ExistsByKey(ctx context.Context, key string) (bool, error) {
 	return false, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]service.APIKey, *pagination.PaginationResult, error) {
+func (r *stubApiKeyRepo) ListByGroupID(ctx context.Context, groupID int64, params pagination.PaginationParams) ([]service.ApiKey, *pagination.PaginationResult, error) {
 	return nil, nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) SearchAPIKeys(ctx context.Context, userID int64, keyword string, limit int) ([]service.APIKey, error) {
+func (r *stubApiKeyRepo) SearchApiKeys(ctx context.Context, userID int64, keyword string, limit int) ([]service.ApiKey, error) {
 	return nil, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (r *stubApiKeyRepo) ClearGroupIDByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }

-func (r *stubAPIKeyRepo) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
+func (r *stubApiKeyRepo) CountByGroupID(ctx context.Context, groupID int64) (int64, error) {
 	return 0, errors.New("not implemented")
 }

--- a/backend/internal/server/middleware/logger.go
+++ b/backend/internal/server/middleware/logger.go
@@ -2,14 +2,11 @@ package middleware

 import (
 	"log"
-	"regexp"
 	"time"

 	"github.com/gin-gonic/gin"
 )

-var sensitiveQueryParamRE = regexp.MustCompile(`(?i)([?&](?:token|api_key)=)[^&#]*`)
-
 // Logger 请求日志中间件
 func Logger() gin.HandlerFunc {
 	return func(c *gin.Context) {
@@ -29,7 +26,7 @@ func Logger() gin.HandlerFunc {
 		method := c.Request.Method

 		// 请求路径
-		path := sensitiveQueryParamRE.ReplaceAllString(c.Request.URL.RequestURI(), "${1}***")
+		path := c.Request.URL.Path

 		// 状态码
 		statusCode := c.Writer.Status()
--- a/backend/internal/server/middleware/middleware.go
+++ b/backend/internal/server/middleware/middleware.go
@@ -1,5 +1,3 @@
-// Package middleware provides HTTP middleware components for authentication,
-// authorization, logging, error recovery, and request processing.
 package middleware

 import (
@@ -17,8 +15,8 @@ const (
 	ContextKeyUser ContextKey = "user"
 	// ContextKeyUserRole 当前用户角色（string）
 	ContextKeyUserRole ContextKey = "user_role"
-	// ContextKeyAPIKey API密钥上下文键
-	ContextKeyAPIKey ContextKey = "api_key"
+	// ContextKeyApiKey API密钥上下文键
+	ContextKeyApiKey ContextKey = "api_key"
 	// ContextKeySubscription 订阅上下文键
 	ContextKeySubscription ContextKey = "subscription"
 	// ContextKeyForcePlatform 强制平台（用于 /antigravity 路由）
--- a/backend/internal/server/middleware/wire.go
+++ b/backend/internal/server/middleware/wire.go
@@ -11,12 +11,12 @@ type JWTAuthMiddleware gin.HandlerFunc
 // AdminAuthMiddleware 管理员认证中间件类型
 type AdminAuthMiddleware gin.HandlerFunc

-// APIKeyAuthMiddleware API Key 认证中间件类型
-type APIKeyAuthMiddleware gin.HandlerFunc
+// ApiKeyAuthMiddleware API Key 认证中间件类型
+type ApiKeyAuthMiddleware gin.HandlerFunc

 // ProviderSet 中间件层的依赖注入
 var ProviderSet = wire.NewSet(
 	NewJWTAuthMiddleware,
 	NewAdminAuthMiddleware,
-	NewAPIKeyAuthMiddleware,
+	NewApiKeyAuthMiddleware,
 )
--- a/backend/internal/server/router.go
+++ b/backend/internal/server/router.go
@@ -17,8 +17,8 @@ func SetupRouter(
 	handlers *handler.Handlers,
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
-	apiKeyAuth middleware2.APIKeyAuthMiddleware,
-	apiKeyService *service.APIKeyService,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
 	subscriptionService *service.SubscriptionService,
 	cfg *config.Config,
 ) *gin.Engine {
@@ -43,8 +43,8 @@ func registerRoutes(
 	h *handler.Handlers,
 	jwtAuth middleware2.JWTAuthMiddleware,
 	adminAuth middleware2.AdminAuthMiddleware,
-	apiKeyAuth middleware2.APIKeyAuthMiddleware,
-	apiKeyService *service.APIKeyService,
+	apiKeyAuth middleware2.ApiKeyAuthMiddleware,
+	apiKeyService *service.ApiKeyService,
 	subscriptionService *service.SubscriptionService,
 	cfg *config.Config,
 ) {
--- a/backend/internal/server/routes/common.go
+++ b/backend/internal/server/routes/common.go
@@ -1,4 +1,3 @@
-// Package routes 提供 HTTP 路由注册和处理函数
 package routes

 import (
--- a/backend/internal/server/routes/user.go
+++ b/backend/internal/server/routes/user.go
@@ -50,7 +50,7 @@ func RegisterUserRoutes(
 			usage.GET("/dashboard/stats", h.Usage.DashboardStats)
 			usage.GET("/dashboard/trend", h.Usage.DashboardTrend)
 			usage.GET("/dashboard/models", h.Usage.DashboardModels)
-			usage.POST("/dashboard/api-keys-usage", h.Usage.DashboardAPIKeysUsage)
+			usage.POST("/dashboard/api-keys-usage", h.Usage.DashboardApiKeysUsage)
 		}

 		// 卡密兑换