feat(auth): 密码重置邮件队列化与限流优化

- 邮件发送改为异步队列处理，避免并发导致发送失败 - 新增 Email 维度限流（30秒冷却期），防止邮件轰炸 - Token 验证使用常量时间比较，防止时序攻击 - 重构代码消除冗余，提取公共验证逻辑
2026-01-24 22:33:45 +08:00
parent 43a1031e38
commit 9cc8352593
25 changed files with 1497 additions and 114 deletions
--- a/backend/internal/service/auth_service.go
+++ b/backend/internal/service/auth_service.go
@@ -580,3 +580,149 @@ func (s *AuthService) RefreshToken(ctx context.Context, oldTokenString string) (
 	// 生成新token
 	return s.GenerateToken(user)
 }
+
+// IsPasswordResetEnabled 检查是否启用密码重置功能
+// 要求：必须同时开启邮件验证且 SMTP 配置正确
+func (s *AuthService) IsPasswordResetEnabled(ctx context.Context) bool {
+	if s.settingService == nil {
+		return false
+	}
+	// Must have email verification enabled and SMTP configured
+	if !s.settingService.IsEmailVerifyEnabled(ctx) {
+		return false
+	}
+	return s.settingService.IsPasswordResetEnabled(ctx)
+}
+
+// preparePasswordReset validates the password reset request and returns necessary data
+// Returns (siteName, resetURL, shouldProceed)
+// shouldProceed is false when we should silently return success (to prevent enumeration)
+func (s *AuthService) preparePasswordReset(ctx context.Context, email, frontendBaseURL string) (string, string, bool) {
+	// Check if user exists (but don't reveal this to the caller)
+	user, err := s.userRepo.GetByEmail(ctx, email)
+	if err != nil {
+		if errors.Is(err, ErrUserNotFound) {
+			// Security: Log but don't reveal that user doesn't exist
+			log.Printf("[Auth] Password reset requested for non-existent email: %s", email)
+			return "", "", false
+		}
+		log.Printf("[Auth] Database error checking email for password reset: %v", err)
+		return "", "", false
+	}
+
+	// Check if user is active
+	if !user.IsActive() {
+		log.Printf("[Auth] Password reset requested for inactive user: %s", email)
+		return "", "", false
+	}
+
+	// Get site name
+	siteName := "Sub2API"
+	if s.settingService != nil {
+		siteName = s.settingService.GetSiteName(ctx)
+	}
+
+	// Build reset URL base
+	resetURL := fmt.Sprintf("%s/reset-password", strings.TrimSuffix(frontendBaseURL, "/"))
+
+	return siteName, resetURL, true
+}
+
+// RequestPasswordReset 请求密码重置（同步发送）
+// Security: Returns the same response regardless of whether the email exists (prevent user enumeration)
+func (s *AuthService) RequestPasswordReset(ctx context.Context, email, frontendBaseURL string) error {
+	if !s.IsPasswordResetEnabled(ctx) {
+		return infraerrors.Forbidden("PASSWORD_RESET_DISABLED", "password reset is not enabled")
+	}
+	if s.emailService == nil {
+		return ErrServiceUnavailable
+	}
+
+	siteName, resetURL, shouldProceed := s.preparePasswordReset(ctx, email, frontendBaseURL)
+	if !shouldProceed {
+		return nil // Silent success to prevent enumeration
+	}
+
+	if err := s.emailService.SendPasswordResetEmail(ctx, email, siteName, resetURL); err != nil {
+		log.Printf("[Auth] Failed to send password reset email to %s: %v", email, err)
+		return nil // Silent success to prevent enumeration
+	}
+
+	log.Printf("[Auth] Password reset email sent to: %s", email)
+	return nil
+}
+
+// RequestPasswordResetAsync 异步请求密码重置（队列发送）
+// Security: Returns the same response regardless of whether the email exists (prevent user enumeration)
+func (s *AuthService) RequestPasswordResetAsync(ctx context.Context, email, frontendBaseURL string) error {
+	if !s.IsPasswordResetEnabled(ctx) {
+		return infraerrors.Forbidden("PASSWORD_RESET_DISABLED", "password reset is not enabled")
+	}
+	if s.emailQueueService == nil {
+		return ErrServiceUnavailable
+	}
+
+	siteName, resetURL, shouldProceed := s.preparePasswordReset(ctx, email, frontendBaseURL)
+	if !shouldProceed {
+		return nil // Silent success to prevent enumeration
+	}
+
+	if err := s.emailQueueService.EnqueuePasswordReset(email, siteName, resetURL); err != nil {
+		log.Printf("[Auth] Failed to enqueue password reset email for %s: %v", email, err)
+		return nil // Silent success to prevent enumeration
+	}
+
+	log.Printf("[Auth] Password reset email enqueued for: %s", email)
+	return nil
+}
+
+// ResetPassword 重置密码
+// Security: Increments TokenVersion to invalidate all existing JWT tokens
+func (s *AuthService) ResetPassword(ctx context.Context, email, token, newPassword string) error {
+	// Check if password reset is enabled
+	if !s.IsPasswordResetEnabled(ctx) {
+		return infraerrors.Forbidden("PASSWORD_RESET_DISABLED", "password reset is not enabled")
+	}
+
+	if s.emailService == nil {
+		return ErrServiceUnavailable
+	}
+
+	// Verify and consume the reset token (one-time use)
+	if err := s.emailService.ConsumePasswordResetToken(ctx, email, token); err != nil {
+		return err
+	}
+
+	// Get user
+	user, err := s.userRepo.GetByEmail(ctx, email)
+	if err != nil {
+		if errors.Is(err, ErrUserNotFound) {
+			return ErrInvalidResetToken // Token was valid but user was deleted
+		}
+		log.Printf("[Auth] Database error getting user for password reset: %v", err)
+		return ErrServiceUnavailable
+	}
+
+	// Check if user is active
+	if !user.IsActive() {
+		return ErrUserNotActive
+	}
+
+	// Hash new password
+	hashedPassword, err := s.HashPassword(newPassword)
+	if err != nil {
+		return fmt.Errorf("hash password: %w", err)
+	}
+
+	// Update password and increment TokenVersion
+	user.PasswordHash = hashedPassword
+	user.TokenVersion++ // Invalidate all existing tokens
+
+	if err := s.userRepo.Update(ctx, user); err != nil {
+		log.Printf("[Auth] Database error updating password for user %d: %v", user.ID, err)
+		return ErrServiceUnavailable
+	}
+
+	log.Printf("[Auth] Password reset successful for user: %s", email)
+	return nil
+}
--- a/backend/internal/service/auth_service_register_test.go
+++ b/backend/internal/service/auth_service_register_test.go
@@ -71,6 +71,26 @@ func (s *emailCacheStub) DeleteVerificationCode(ctx context.Context, email strin
 	return nil
 }

+func (s *emailCacheStub) GetPasswordResetToken(ctx context.Context, email string) (*PasswordResetTokenData, error) {
+	return nil, nil
+}
+
+func (s *emailCacheStub) SetPasswordResetToken(ctx context.Context, email string, data *PasswordResetTokenData, ttl time.Duration) error {
+	return nil
+}
+
+func (s *emailCacheStub) DeletePasswordResetToken(ctx context.Context, email string) error {
+	return nil
+}
+
+func (s *emailCacheStub) IsPasswordResetEmailInCooldown(ctx context.Context, email string) bool {
+	return false
+}
+
+func (s *emailCacheStub) SetPasswordResetEmailCooldown(ctx context.Context, email string, ttl time.Duration) error {
+	return nil
+}
+
 func newAuthService(repo *userRepoStub, settings map[string]string, emailCache EmailCache) *AuthService {
 	cfg := &config.Config{
 		JWT: config.JWTConfig{
--- a/backend/internal/service/domain_constants.go
+++ b/backend/internal/service/domain_constants.go
@@ -69,9 +69,10 @@ const LinuxDoConnectSyntheticEmailDomain = "@linuxdo-connect.invalid"
 // Setting keys
 const (
 	// 注册设置
-	SettingKeyRegistrationEnabled = "registration_enabled" // 是否开放注册
-	SettingKeyEmailVerifyEnabled  = "email_verify_enabled" // 是否开启邮件验证
-	SettingKeyPromoCodeEnabled    = "promo_code_enabled"   // 是否启用优惠码功能
+	SettingKeyRegistrationEnabled  = "registration_enabled"   // 是否开放注册
+	SettingKeyEmailVerifyEnabled   = "email_verify_enabled"   // 是否开启邮件验证
+	SettingKeyPromoCodeEnabled     = "promo_code_enabled"     // 是否启用优惠码功能
+	SettingKeyPasswordResetEnabled = "password_reset_enabled" // 是否启用忘记密码功能（需要先开启邮件验证）

 	// 邮件服务设置
 	SettingKeySMTPHost     = "smtp_host"      // SMTP服务器地址
--- a/backend/internal/service/email_queue_service.go
+++ b/backend/internal/service/email_queue_service.go
@@ -8,11 +8,18 @@ import (
 	"time"
 )

+// Task type constants
+const (
+	TaskTypeVerifyCode    = "verify_code"
+	TaskTypePasswordReset = "password_reset"
+)
+
 // EmailTask 邮件发送任务
 type EmailTask struct {
 	Email    string
 	SiteName string
-	TaskType string // "verify_code"
+	TaskType string // "verify_code" or "password_reset"
+	ResetURL string // Only used for password_reset task type
 }

 // EmailQueueService 异步邮件队列服务
@@ -73,12 +80,18 @@ func (s *EmailQueueService) processTask(workerID int, task EmailTask) {
 	defer cancel()

 	switch task.TaskType {
-	case "verify_code":
+	case TaskTypeVerifyCode:
 		if err := s.emailService.SendVerifyCode(ctx, task.Email, task.SiteName); err != nil {
 			log.Printf("[EmailQueue] Worker %d failed to send verify code to %s: %v", workerID, task.Email, err)
 		} else {
 			log.Printf("[EmailQueue] Worker %d sent verify code to %s", workerID, task.Email)
 		}
+	case TaskTypePasswordReset:
+		if err := s.emailService.SendPasswordResetEmailWithCooldown(ctx, task.Email, task.SiteName, task.ResetURL); err != nil {
+			log.Printf("[EmailQueue] Worker %d failed to send password reset to %s: %v", workerID, task.Email, err)
+		} else {
+			log.Printf("[EmailQueue] Worker %d sent password reset to %s", workerID, task.Email)
+		}
 	default:
 		log.Printf("[EmailQueue] Worker %d unknown task type: %s", workerID, task.TaskType)
 	}
@@ -89,7 +102,7 @@ func (s *EmailQueueService) EnqueueVerifyCode(email, siteName string) error {
 	task := EmailTask{
 		Email:    email,
 		SiteName: siteName,
-		TaskType: "verify_code",
+		TaskType: TaskTypeVerifyCode,
 	}

 	select {
@@ -101,6 +114,24 @@ func (s *EmailQueueService) EnqueueVerifyCode(email, siteName string) error {
 	}
 }

+// EnqueuePasswordReset 将密码重置邮件任务加入队列
+func (s *EmailQueueService) EnqueuePasswordReset(email, siteName, resetURL string) error {
+	task := EmailTask{
+		Email:    email,
+		SiteName: siteName,
+		TaskType: TaskTypePasswordReset,
+		ResetURL: resetURL,
+	}
+
+	select {
+	case s.taskChan <- task:
+		log.Printf("[EmailQueue] Enqueued password reset task for %s", email)
+		return nil
+	default:
+		return fmt.Errorf("email queue is full")
+	}
+}
+
 // Stop 停止队列服务
 func (s *EmailQueueService) Stop() {
 	close(s.stopChan)
--- a/backend/internal/service/email_service.go
+++ b/backend/internal/service/email_service.go
@@ -3,11 +3,14 @@ package service
 import (
 	"context"
 	"crypto/rand"
+	"crypto/subtle"
 	"crypto/tls"
+	"encoding/hex"
 	"fmt"
 	"log"
 	"math/big"
 	"net/smtp"
+	"net/url"
 	"strconv"
 	"time"

@@ -19,6 +22,9 @@ var (
 	ErrInvalidVerifyCode     = infraerrors.BadRequest("INVALID_VERIFY_CODE", "invalid or expired verification code")
 	ErrVerifyCodeTooFrequent = infraerrors.TooManyRequests("VERIFY_CODE_TOO_FREQUENT", "please wait before requesting a new code")
 	ErrVerifyCodeMaxAttempts = infraerrors.TooManyRequests("VERIFY_CODE_MAX_ATTEMPTS", "too many failed attempts, please request a new code")
+
+	// Password reset errors
+	ErrInvalidResetToken = infraerrors.BadRequest("INVALID_RESET_TOKEN", "invalid or expired password reset token")
 )

 // EmailCache defines cache operations for email service
@@ -26,6 +32,16 @@ type EmailCache interface {
 	GetVerificationCode(ctx context.Context, email string) (*VerificationCodeData, error)
 	SetVerificationCode(ctx context.Context, email string, data *VerificationCodeData, ttl time.Duration) error
 	DeleteVerificationCode(ctx context.Context, email string) error
+
+	// Password reset token methods
+	GetPasswordResetToken(ctx context.Context, email string) (*PasswordResetTokenData, error)
+	SetPasswordResetToken(ctx context.Context, email string, data *PasswordResetTokenData, ttl time.Duration) error
+	DeletePasswordResetToken(ctx context.Context, email string) error
+
+	// Password reset email cooldown methods
+	// Returns true if in cooldown period (email was sent recently)
+	IsPasswordResetEmailInCooldown(ctx context.Context, email string) bool
+	SetPasswordResetEmailCooldown(ctx context.Context, email string, ttl time.Duration) error
 }

 // VerificationCodeData represents verification code data
@@ -35,10 +51,22 @@ type VerificationCodeData struct {
 	CreatedAt time.Time
 }

+// PasswordResetTokenData represents password reset token data
+type PasswordResetTokenData struct {
+	Token     string
+	CreatedAt time.Time
+}
+
 const (
 	verifyCodeTTL         = 15 * time.Minute
 	verifyCodeCooldown    = 1 * time.Minute
 	maxVerifyCodeAttempts = 5
+
+	// Password reset token settings
+	passwordResetTokenTTL = 30 * time.Minute
+
+	// Password reset email cooldown (prevent email bombing)
+	passwordResetEmailCooldown = 30 * time.Second
 )

 // SMTPConfig SMTP配置
@@ -357,3 +385,157 @@ func (s *EmailService) TestSMTPConnectionWithConfig(config *SMTPConfig) error {

 	return client.Quit()
 }
+
+// GeneratePasswordResetToken generates a secure 32-byte random token (64 hex characters)
+func (s *EmailService) GeneratePasswordResetToken() (string, error) {
+	bytes := make([]byte, 32)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(bytes), nil
+}
+
+// SendPasswordResetEmail sends a password reset email with a reset link
+func (s *EmailService) SendPasswordResetEmail(ctx context.Context, email, siteName, resetURL string) error {
+	var token string
+	var needSaveToken bool
+
+	// Check if token already exists
+	existing, err := s.cache.GetPasswordResetToken(ctx, email)
+	if err == nil && existing != nil {
+		// Token exists, reuse it (allows resending email without generating new token)
+		token = existing.Token
+		needSaveToken = false
+	} else {
+		// Generate new token
+		token, err = s.GeneratePasswordResetToken()
+		if err != nil {
+			return fmt.Errorf("generate token: %w", err)
+		}
+		needSaveToken = true
+	}
+
+	// Save token to Redis (only if new token generated)
+	if needSaveToken {
+		data := &PasswordResetTokenData{
+			Token:     token,
+			CreatedAt: time.Now(),
+		}
+		if err := s.cache.SetPasswordResetToken(ctx, email, data, passwordResetTokenTTL); err != nil {
+			return fmt.Errorf("save reset token: %w", err)
+		}
+	}
+
+	// Build full reset URL with URL-encoded token and email
+	fullResetURL := fmt.Sprintf("%s?email=%s&token=%s", resetURL, url.QueryEscape(email), url.QueryEscape(token))
+
+	// Build email content
+	subject := fmt.Sprintf("[%s] 密码重置请求", siteName)
+	body := s.buildPasswordResetEmailBody(fullResetURL, siteName)
+
+	// Send email
+	if err := s.SendEmail(ctx, email, subject, body); err != nil {
+		return fmt.Errorf("send email: %w", err)
+	}
+
+	return nil
+}
+
+// SendPasswordResetEmailWithCooldown sends password reset email with cooldown check (called by queue worker)
+// This method wraps SendPasswordResetEmail with email cooldown to prevent email bombing
+func (s *EmailService) SendPasswordResetEmailWithCooldown(ctx context.Context, email, siteName, resetURL string) error {
+	// Check email cooldown to prevent email bombing
+	if s.cache.IsPasswordResetEmailInCooldown(ctx, email) {
+		log.Printf("[Email] Password reset email skipped (cooldown): %s", email)
+		return nil // Silent success to prevent revealing cooldown to attackers
+	}
+
+	// Send email using core method
+	if err := s.SendPasswordResetEmail(ctx, email, siteName, resetURL); err != nil {
+		return err
+	}
+
+	// Set cooldown marker (Redis TTL handles expiration)
+	if err := s.cache.SetPasswordResetEmailCooldown(ctx, email, passwordResetEmailCooldown); err != nil {
+		log.Printf("[Email] Failed to set password reset cooldown for %s: %v", email, err)
+	}
+
+	return nil
+}
+
+// VerifyPasswordResetToken verifies the password reset token without consuming it
+func (s *EmailService) VerifyPasswordResetToken(ctx context.Context, email, token string) error {
+	data, err := s.cache.GetPasswordResetToken(ctx, email)
+	if err != nil || data == nil {
+		return ErrInvalidResetToken
+	}
+
+	// Use constant-time comparison to prevent timing attacks
+	if subtle.ConstantTimeCompare([]byte(data.Token), []byte(token)) != 1 {
+		return ErrInvalidResetToken
+	}
+
+	return nil
+}
+
+// ConsumePasswordResetToken verifies and deletes the token (one-time use)
+func (s *EmailService) ConsumePasswordResetToken(ctx context.Context, email, token string) error {
+	// Verify first
+	if err := s.VerifyPasswordResetToken(ctx, email, token); err != nil {
+		return err
+	}
+
+	// Delete after verification (one-time use)
+	if err := s.cache.DeletePasswordResetToken(ctx, email); err != nil {
+		log.Printf("[Email] Failed to delete password reset token after consumption: %v", err)
+	}
+	return nil
+}
+
+// buildPasswordResetEmailBody builds the HTML content for password reset email
+func (s *EmailService) buildPasswordResetEmailBody(resetURL, siteName string) string {
+	return fmt.Sprintf(`
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif; background-color: #f5f5f5; margin: 0; padding: 20px; }
+        .container { max-width: 600px; margin: 0 auto; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+        .header { background: linear-gradient(135deg, #667eea 0%%, #764ba2 100%%); color: white; padding: 30px; text-align: center; }
+        .header h1 { margin: 0; font-size: 24px; }
+        .content { padding: 40px 30px; text-align: center; }
+        .button { display: inline-block; background: linear-gradient(135deg, #667eea 0%%, #764ba2 100%%); color: white; padding: 14px 32px; text-decoration: none; border-radius: 8px; font-size: 16px; font-weight: 600; margin: 20px 0; }
+        .button:hover { opacity: 0.9; }
+        .info { color: #666; font-size: 14px; line-height: 1.6; margin-top: 20px; }
+        .link-fallback { color: #666; font-size: 12px; word-break: break-all; margin-top: 20px; padding: 15px; background-color: #f8f9fa; border-radius: 4px; }
+        .footer { background-color: #f8f9fa; padding: 20px; text-align: center; color: #999; font-size: 12px; }
+        .warning { color: #e74c3c; font-weight: 500; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>%s</h1>
+        </div>
+        <div class="content">
+            <p style="font-size: 18px; color: #333;">密码重置请求</p>
+            <p style="color: #666;">您已请求重置密码。请点击下方按钮设置新密码：</p>
+            <a href="%s" class="button">重置密码</a>
+            <div class="info">
+                <p>此链接将在 <strong>30 分钟</strong>后失效。</p>
+                <p class="warning">如果您没有请求重置密码，请忽略此邮件。您的密码将保持不变。</p>
+            </div>
+            <div class="link-fallback">
+                <p>如果按钮无法点击，请复制以下链接到浏览器中打开：</p>
+                <p>%s</p>
+            </div>
+        </div>
+        <div class="footer">
+            <p>这是一封自动发送的邮件，请勿回复。</p>
+        </div>
+    </div>
+</body>
+</html>
+`, siteName, resetURL, resetURL)
+}
--- a/backend/internal/service/setting_service.go
+++ b/backend/internal/service/setting_service.go
@@ -61,6 +61,7 @@ func (s *SettingService) GetPublicSettings(ctx context.Context) (*PublicSettings
 		SettingKeyRegistrationEnabled,
 		SettingKeyEmailVerifyEnabled,
 		SettingKeyPromoCodeEnabled,
+		SettingKeyPasswordResetEnabled,
 		SettingKeyTurnstileEnabled,
 		SettingKeyTurnstileSiteKey,
 		SettingKeySiteName,
@@ -86,21 +87,26 @@ func (s *SettingService) GetPublicSettings(ctx context.Context) (*PublicSettings
 		linuxDoEnabled = s.cfg != nil && s.cfg.LinuxDo.Enabled
 	}

+	// Password reset requires email verification to be enabled
+	emailVerifyEnabled := settings[SettingKeyEmailVerifyEnabled] == "true"
+	passwordResetEnabled := emailVerifyEnabled && settings[SettingKeyPasswordResetEnabled] == "true"
+
 	return &PublicSettings{
-		RegistrationEnabled: settings[SettingKeyRegistrationEnabled] == "true",
-		EmailVerifyEnabled:  settings[SettingKeyEmailVerifyEnabled] == "true",
-		PromoCodeEnabled:    settings[SettingKeyPromoCodeEnabled] != "false", // 默认启用
-		TurnstileEnabled:    settings[SettingKeyTurnstileEnabled] == "true",
-		TurnstileSiteKey:    settings[SettingKeyTurnstileSiteKey],
-		SiteName:            s.getStringOrDefault(settings, SettingKeySiteName, "Sub2API"),
-		SiteLogo:            settings[SettingKeySiteLogo],
-		SiteSubtitle:        s.getStringOrDefault(settings, SettingKeySiteSubtitle, "Subscription to API Conversion Platform"),
-		APIBaseURL:          settings[SettingKeyAPIBaseURL],
-		ContactInfo:         settings[SettingKeyContactInfo],
-		DocURL:              settings[SettingKeyDocURL],
-		HomeContent:         settings[SettingKeyHomeContent],
-		HideCcsImportButton: settings[SettingKeyHideCcsImportButton] == "true",
-		LinuxDoOAuthEnabled: linuxDoEnabled,
+		RegistrationEnabled:  settings[SettingKeyRegistrationEnabled] == "true",
+		EmailVerifyEnabled:   emailVerifyEnabled,
+		PromoCodeEnabled:     settings[SettingKeyPromoCodeEnabled] != "false", // 默认启用
+		PasswordResetEnabled: passwordResetEnabled,
+		TurnstileEnabled:     settings[SettingKeyTurnstileEnabled] == "true",
+		TurnstileSiteKey:     settings[SettingKeyTurnstileSiteKey],
+		SiteName:             s.getStringOrDefault(settings, SettingKeySiteName, "Sub2API"),
+		SiteLogo:             settings[SettingKeySiteLogo],
+		SiteSubtitle:         s.getStringOrDefault(settings, SettingKeySiteSubtitle, "Subscription to API Conversion Platform"),
+		APIBaseURL:           settings[SettingKeyAPIBaseURL],
+		ContactInfo:          settings[SettingKeyContactInfo],
+		DocURL:               settings[SettingKeyDocURL],
+		HomeContent:          settings[SettingKeyHomeContent],
+		HideCcsImportButton:  settings[SettingKeyHideCcsImportButton] == "true",
+		LinuxDoOAuthEnabled:  linuxDoEnabled,
 	}, nil
 }

@@ -125,37 +131,39 @@ func (s *SettingService) GetPublicSettingsForInjection(ctx context.Context) (any

 	// Return a struct that matches the frontend's expected format
 	return &struct {
-		RegistrationEnabled bool   `json:"registration_enabled"`
-		EmailVerifyEnabled  bool   `json:"email_verify_enabled"`
-		PromoCodeEnabled    bool   `json:"promo_code_enabled"`
-		TurnstileEnabled    bool   `json:"turnstile_enabled"`
-		TurnstileSiteKey    string `json:"turnstile_site_key,omitempty"`
-		SiteName            string `json:"site_name"`
-		SiteLogo            string `json:"site_logo,omitempty"`
-		SiteSubtitle        string `json:"site_subtitle,omitempty"`
-		APIBaseURL          string `json:"api_base_url,omitempty"`
-		ContactInfo         string `json:"contact_info,omitempty"`
-		DocURL              string `json:"doc_url,omitempty"`
-		HomeContent         string `json:"home_content,omitempty"`
-		HideCcsImportButton bool   `json:"hide_ccs_import_button"`
-		LinuxDoOAuthEnabled bool   `json:"linuxdo_oauth_enabled"`
-		Version             string `json:"version,omitempty"`
+		RegistrationEnabled  bool   `json:"registration_enabled"`
+		EmailVerifyEnabled   bool   `json:"email_verify_enabled"`
+		PromoCodeEnabled     bool   `json:"promo_code_enabled"`
+		PasswordResetEnabled bool   `json:"password_reset_enabled"`
+		TurnstileEnabled     bool   `json:"turnstile_enabled"`
+		TurnstileSiteKey     string `json:"turnstile_site_key,omitempty"`
+		SiteName             string `json:"site_name"`
+		SiteLogo             string `json:"site_logo,omitempty"`
+		SiteSubtitle         string `json:"site_subtitle,omitempty"`
+		APIBaseURL           string `json:"api_base_url,omitempty"`
+		ContactInfo          string `json:"contact_info,omitempty"`
+		DocURL               string `json:"doc_url,omitempty"`
+		HomeContent          string `json:"home_content,omitempty"`
+		HideCcsImportButton  bool   `json:"hide_ccs_import_button"`
+		LinuxDoOAuthEnabled  bool   `json:"linuxdo_oauth_enabled"`
+		Version              string `json:"version,omitempty"`
 	}{
-		RegistrationEnabled: settings.RegistrationEnabled,
-		EmailVerifyEnabled:  settings.EmailVerifyEnabled,
-		PromoCodeEnabled:    settings.PromoCodeEnabled,
-		TurnstileEnabled:    settings.TurnstileEnabled,
-		TurnstileSiteKey:    settings.TurnstileSiteKey,
-		SiteName:            settings.SiteName,
-		SiteLogo:            settings.SiteLogo,
-		SiteSubtitle:        settings.SiteSubtitle,
-		APIBaseURL:          settings.APIBaseURL,
-		ContactInfo:         settings.ContactInfo,
-		DocURL:              settings.DocURL,
-		HomeContent:         settings.HomeContent,
-		HideCcsImportButton: settings.HideCcsImportButton,
-		LinuxDoOAuthEnabled: settings.LinuxDoOAuthEnabled,
-		Version:             s.version,
+		RegistrationEnabled:  settings.RegistrationEnabled,
+		EmailVerifyEnabled:   settings.EmailVerifyEnabled,
+		PromoCodeEnabled:     settings.PromoCodeEnabled,
+		PasswordResetEnabled: settings.PasswordResetEnabled,
+		TurnstileEnabled:     settings.TurnstileEnabled,
+		TurnstileSiteKey:     settings.TurnstileSiteKey,
+		SiteName:             settings.SiteName,
+		SiteLogo:             settings.SiteLogo,
+		SiteSubtitle:         settings.SiteSubtitle,
+		APIBaseURL:           settings.APIBaseURL,
+		ContactInfo:          settings.ContactInfo,
+		DocURL:               settings.DocURL,
+		HomeContent:          settings.HomeContent,
+		HideCcsImportButton:  settings.HideCcsImportButton,
+		LinuxDoOAuthEnabled:  settings.LinuxDoOAuthEnabled,
+		Version:              s.version,
 	}, nil
 }

@@ -167,6 +175,7 @@ func (s *SettingService) UpdateSettings(ctx context.Context, settings *SystemSet
 	updates[SettingKeyRegistrationEnabled] = strconv.FormatBool(settings.RegistrationEnabled)
 	updates[SettingKeyEmailVerifyEnabled] = strconv.FormatBool(settings.EmailVerifyEnabled)
 	updates[SettingKeyPromoCodeEnabled] = strconv.FormatBool(settings.PromoCodeEnabled)
+	updates[SettingKeyPasswordResetEnabled] = strconv.FormatBool(settings.PasswordResetEnabled)

 	// 邮件服务设置（只有非空才更新密码）
 	updates[SettingKeySMTPHost] = settings.SMTPHost
@@ -262,6 +271,20 @@ func (s *SettingService) IsPromoCodeEnabled(ctx context.Context) bool {
 	return value != "false"
 }

+// IsPasswordResetEnabled 检查是否启用密码重置功能
+// 要求：必须同时开启邮件验证
+func (s *SettingService) IsPasswordResetEnabled(ctx context.Context) bool {
+	// Password reset requires email verification to be enabled
+	if !s.IsEmailVerifyEnabled(ctx) {
+		return false
+	}
+	value, err := s.settingRepo.GetValue(ctx, SettingKeyPasswordResetEnabled)
+	if err != nil {
+		return false // 默认关闭
+	}
+	return value == "true"
+}
+
 // GetSiteName 获取网站名称
 func (s *SettingService) GetSiteName(ctx context.Context) string {
 	value, err := s.settingRepo.GetValue(ctx, SettingKeySiteName)
@@ -340,10 +363,12 @@ func (s *SettingService) InitializeDefaultSettings(ctx context.Context) error {

 // parseSettings 解析设置到结构体
 func (s *SettingService) parseSettings(settings map[string]string) *SystemSettings {
+	emailVerifyEnabled := settings[SettingKeyEmailVerifyEnabled] == "true"
 	result := &SystemSettings{
 		RegistrationEnabled:          settings[SettingKeyRegistrationEnabled] == "true",
-		EmailVerifyEnabled:           settings[SettingKeyEmailVerifyEnabled] == "true",
+		EmailVerifyEnabled:           emailVerifyEnabled,
 		PromoCodeEnabled:             settings[SettingKeyPromoCodeEnabled] != "false", // 默认启用
+		PasswordResetEnabled:         emailVerifyEnabled && settings[SettingKeyPasswordResetEnabled] == "true",
 		SMTPHost:                     settings[SettingKeySMTPHost],
 		SMTPUsername:                 settings[SettingKeySMTPUsername],
 		SMTPFrom:                     settings[SettingKeySMTPFrom],
--- a/backend/internal/service/settings_view.go
+++ b/backend/internal/service/settings_view.go
@@ -1,9 +1,10 @@
 package service

 type SystemSettings struct {
-	RegistrationEnabled bool
-	EmailVerifyEnabled  bool
-	PromoCodeEnabled    bool
+	RegistrationEnabled  bool
+	EmailVerifyEnabled   bool
+	PromoCodeEnabled     bool
+	PasswordResetEnabled bool

 	SMTPHost               string
 	SMTPPort               int
@@ -57,21 +58,22 @@ type SystemSettings struct {
 }

 type PublicSettings struct {
-	RegistrationEnabled bool
-	EmailVerifyEnabled  bool
-	PromoCodeEnabled    bool
-	TurnstileEnabled    bool
-	TurnstileSiteKey    string
-	SiteName            string
-	SiteLogo            string
-	SiteSubtitle        string
-	APIBaseURL          string
-	ContactInfo         string
-	DocURL              string
-	HomeContent         string
-	HideCcsImportButton bool
-	LinuxDoOAuthEnabled bool
-	Version             string
+	RegistrationEnabled  bool
+	EmailVerifyEnabled   bool
+	PromoCodeEnabled     bool
+	PasswordResetEnabled bool
+	TurnstileEnabled     bool
+	TurnstileSiteKey     string
+	SiteName             string
+	SiteLogo             string
+	SiteSubtitle         string
+	APIBaseURL           string
+	ContactInfo          string
+	DocURL               string
+	HomeContent          string
+	HideCcsImportButton  bool
+	LinuxDoOAuthEnabled  bool
+	Version              string
 }

 // StreamTimeoutSettings 流超时处理配置（仅控制超时后的处理方式，超时判定由网关配置控制）