feat(安全): 强化安全策略与配置校验

- 增加 CORS/CSP/安全响应头与代理信任配置

- 引入 URL 白名单与私网开关，校验上游与价格源

- 改善 API Key 处理与网关错误返回

- 管理端设置隐藏敏感字段并优化前端提示

- 增加计费熔断与相关配置示例

测试: go test ./...

backend/internal/handler/admin/setting_handler.go

@@ -1,8 +1,12 @@
 package admin
 
 import (
+	"log"
+	"time"
+
 	"github.com/Wei-Shaw/sub2api/internal/handler/dto"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
@@ -37,13 +41,13 @@ func (h *SettingHandler) GetSettings(c *gin.Context) {
 		SmtpHost:            settings.SmtpHost,
 		SmtpPort:            settings.SmtpPort,
 		SmtpUsername:        settings.SmtpUsername,
-		SmtpPassword:        settings.SmtpPassword,
+		SmtpPasswordConfigured: settings.SmtpPasswordConfigured,
 		SmtpFrom:            settings.SmtpFrom,
 		SmtpFromName:        settings.SmtpFromName,
 		SmtpUseTLS:          settings.SmtpUseTLS,
 		TurnstileEnabled:    settings.TurnstileEnabled,
 		TurnstileSiteKey:    settings.TurnstileSiteKey,
-		TurnstileSecretKey:  settings.TurnstileSecretKey,
+		TurnstileSecretKeyConfigured: settings.TurnstileSecretKeyConfigured,
 		SiteName:            settings.SiteName,
 		SiteLogo:            settings.SiteLogo,
 		SiteSubtitle:        settings.SiteSubtitle,
@@ -97,6 +101,12 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		return
 	}
 
+	previousSettings, err := h.settingService.GetAllSettings(c.Request.Context())
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
 	// 验证参数
 	if req.DefaultConcurrency < 1 {
 		req.DefaultConcurrency = 1
@@ -136,6 +146,8 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		return
 	}
 
+	h.auditSettingsUpdate(c, previousSettings, settings, req)
+
 	// 重新获取设置返回
 	updatedSettings, err := h.settingService.GetAllSettings(c.Request.Context())
 	if err != nil {
@@ -149,13 +161,13 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 		SmtpHost:            updatedSettings.SmtpHost,
 		SmtpPort:            updatedSettings.SmtpPort,
 		SmtpUsername:        updatedSettings.SmtpUsername,
-		SmtpPassword:        updatedSettings.SmtpPassword,
+		SmtpPasswordConfigured: updatedSettings.SmtpPasswordConfigured,
 		SmtpFrom:            updatedSettings.SmtpFrom,
 		SmtpFromName:        updatedSettings.SmtpFromName,
 		SmtpUseTLS:          updatedSettings.SmtpUseTLS,
 		TurnstileEnabled:    updatedSettings.TurnstileEnabled,
 		TurnstileSiteKey:    updatedSettings.TurnstileSiteKey,
-		TurnstileSecretKey:  updatedSettings.TurnstileSecretKey,
+		TurnstileSecretKeyConfigured: updatedSettings.TurnstileSecretKeyConfigured,
 		SiteName:            updatedSettings.SiteName,
 		SiteLogo:            updatedSettings.SiteLogo,
 		SiteSubtitle:        updatedSettings.SiteSubtitle,
@@ -167,6 +179,91 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 	})
 }
 
+func (h *SettingHandler) auditSettingsUpdate(c *gin.Context, before *service.SystemSettings, after *service.SystemSettings, req UpdateSettingsRequest) {
+	if before == nil || after == nil {
+		return
+	}
+
+	changed := diffSettings(before, after, req)
+	if len(changed) == 0 {
+		return
+	}
+
+	subject, _ := middleware.GetAuthSubjectFromContext(c)
+	role, _ := middleware.GetUserRoleFromContext(c)
+	log.Printf("AUDIT: settings updated at=%s user_id=%d role=%s changed=%v",
+		time.Now().UTC().Format(time.RFC3339),
+		subject.UserID,
+		role,
+		changed,
+	)
+}
+
+func diffSettings(before *service.SystemSettings, after *service.SystemSettings, req UpdateSettingsRequest) []string {
+	changed := make([]string, 0, 16)
+	if before.RegistrationEnabled != after.RegistrationEnabled {
+		changed = append(changed, "registration_enabled")
+	}
+	if before.EmailVerifyEnabled != after.EmailVerifyEnabled {
+		changed = append(changed, "email_verify_enabled")
+	}
+	if before.SmtpHost != after.SmtpHost {
+		changed = append(changed, "smtp_host")
+	}
+	if before.SmtpPort != after.SmtpPort {
+		changed = append(changed, "smtp_port")
+	}
+	if before.SmtpUsername != after.SmtpUsername {
+		changed = append(changed, "smtp_username")
+	}
+	if req.SmtpPassword != "" {
+		changed = append(changed, "smtp_password")
+	}
+	if before.SmtpFrom != after.SmtpFrom {
+		changed = append(changed, "smtp_from_email")
+	}
+	if before.SmtpFromName != after.SmtpFromName {
+		changed = append(changed, "smtp_from_name")
+	}
+	if before.SmtpUseTLS != after.SmtpUseTLS {
+		changed = append(changed, "smtp_use_tls")
+	}
+	if before.TurnstileEnabled != after.TurnstileEnabled {
+		changed = append(changed, "turnstile_enabled")
+	}
+	if before.TurnstileSiteKey != after.TurnstileSiteKey {
+		changed = append(changed, "turnstile_site_key")
+	}
+	if req.TurnstileSecretKey != "" {
+		changed = append(changed, "turnstile_secret_key")
+	}
+	if before.SiteName != after.SiteName {
+		changed = append(changed, "site_name")
+	}
+	if before.SiteLogo != after.SiteLogo {
+		changed = append(changed, "site_logo")
+	}
+	if before.SiteSubtitle != after.SiteSubtitle {
+		changed = append(changed, "site_subtitle")
+	}
+	if before.ApiBaseUrl != after.ApiBaseUrl {
+		changed = append(changed, "api_base_url")
+	}
+	if before.ContactInfo != after.ContactInfo {
+		changed = append(changed, "contact_info")
+	}
+	if before.DocUrl != after.DocUrl {
+		changed = append(changed, "doc_url")
+	}
+	if before.DefaultConcurrency != after.DefaultConcurrency {
+		changed = append(changed, "default_concurrency")
+	}
+	if before.DefaultBalance != after.DefaultBalance {
+		changed = append(changed, "default_balance")
+	}
+	return changed
+}
+
 // TestSmtpRequest 测试SMTP连接请求
 type TestSmtpRequest struct {
 	SmtpHost     string `json:"smtp_host" binding:"required"`

backend/internal/handler/dto/settings.go

@@ -8,14 +8,14 @@ type SystemSettings struct {
 	SmtpHost     string `json:"smtp_host"`
 	SmtpPort     int    `json:"smtp_port"`
 	SmtpUsername string `json:"smtp_username"`
-	SmtpPassword string `json:"smtp_password,omitempty"`
+	SmtpPasswordConfigured bool `json:"smtp_password_configured"`
 	SmtpFrom     string `json:"smtp_from_email"`
 	SmtpFromName string `json:"smtp_from_name"`
 	SmtpUseTLS   bool   `json:"smtp_use_tls"`
 
 	TurnstileEnabled   bool   `json:"turnstile_enabled"`
 	TurnstileSiteKey   string `json:"turnstile_site_key"`
-	TurnstileSecretKey string `json:"turnstile_secret_key,omitempty"`
+	TurnstileSecretKeyConfigured bool `json:"turnstile_secret_key_configured"`
 
 	SiteName     string `json:"site_name"`
 	SiteLogo     string `json:"site_logo"`

backend/internal/handler/gateway_handler.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/claude"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
 	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
@@ -127,7 +128,8 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 	// 2. 【新增】Wait后二次检查余额/订阅
 	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
 		log.Printf("Billing eligibility check failed after wait: %v", err)
-		h.handleStreamingAwareError(c, http.StatusForbidden, "billing_error", err.Error(), streamStarted)
+		status, code, message := billingErrorDetails(err)
+		h.handleStreamingAwareError(c, status, code, message, streamStarted)
 		return
 	}
 
@@ -535,7 +537,8 @@ func (h *GatewayHandler) CountTokens(c *gin.Context) {
 	// 校验 billing eligibility（订阅/余额）
 	// 【注意】不计算并发，但需要校验订阅/余额
 	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
-		h.errorResponse(c, http.StatusForbidden, "billing_error", err.Error())
+		status, code, message := billingErrorDetails(err)
+		h.errorResponse(c, status, code, message)
 		return
 	}
 
@@ -642,3 +645,18 @@ func sendMockWarmupResponse(c *gin.Context, model string) {
 		},
 	})
 }
+
+func billingErrorDetails(err error) (status int, code, message string) {
+	if errors.Is(err, service.ErrBillingServiceUnavailable) {
+		msg := infraerrors.Message(err)
+		if msg == "" {
+			msg = "Billing service temporarily unavailable. Please retry later."
+		}
+		return http.StatusServiceUnavailable, "billing_service_error", msg
+	}
+	msg := infraerrors.Message(err)
+	if msg == "" {
+		msg = err.Error()
+	}
+	return http.StatusForbidden, "billing_error", msg
+}

backend/internal/handler/gemini_v1beta_handler.go

@@ -190,7 +190,8 @@ func (h *GatewayHandler) GeminiV1BetaModels(c *gin.Context) {
 
 	// 2) billing eligibility check (after wait)
 	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
-		googleError(c, http.StatusForbidden, err.Error())
+		status, _, message := billingErrorDetails(err)
+		googleError(c, status, message)
 		return
 	}
 
@@ -329,7 +330,7 @@ func writeUpstreamResponse(c *gin.Context, res *service.UpstreamHTTPResult) {
 	}
 	for k, vv := range res.Headers {
 		// Avoid overriding content-length and hop-by-hop headers.
-		if strings.EqualFold(k, "Content-Length") || strings.EqualFold(k, "Transfer-Encoding") || strings.EqualFold(k, "Connection") {
+		if strings.EqualFold(k, "Content-Length") || strings.EqualFold(k, "Transfer-Encoding") || strings.EqualFold(k, "Connection") || strings.EqualFold(k, "Www-Authenticate") {
 			continue
 		}
 		for _, v := range vv {

backend/internal/handler/openai_gateway_handler.go

@@ -131,7 +131,8 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 	// 2. Re-check billing eligibility after wait
 	if err := h.billingCacheService.CheckBillingEligibility(c.Request.Context(), apiKey.User, apiKey, apiKey.Group, subscription); err != nil {
 		log.Printf("Billing eligibility check failed after wait: %v", err)
-		h.handleStreamingAwareError(c, http.StatusForbidden, "billing_error", err.Error(), streamStarted)
+		status, code, message := billingErrorDetails(err)
+		h.handleStreamingAwareError(c, status, code, message, streamStarted)
 		return
 	}