feat(auth): 实现 TOTP 双因素认证功能

新增功能：
- 支持 Google Authenticator 等应用进行 TOTP 二次验证
- 用户可在个人设置中启用/禁用 2FA
- 登录时支持 TOTP 验证流程
- 管理后台可全局开关 TOTP 功能

安全增强：
- TOTP 密钥使用 AES-256-GCM 加密存储
- 添加 TOTP_ENCRYPTION_KEY 配置项，必须手动配置才能启用功能
- 防止服务重启导致加密密钥变更使用户无法登录
- 验证失败次数限制，防止暴力破解

配置说明：
- Docker 部署：在 .env 中设置 TOTP_ENCRYPTION_KEY
- 非 Docker 部署：在 config.yaml 中设置 totp.encryption_key
- 生成密钥命令：openssl rand -hex 32

frontend/src/api/admin/settings.ts

@@ -14,6 +14,8 @@ export interface SystemSettings {
   email_verify_enabled: boolean
   promo_code_enabled: boolean
   password_reset_enabled: boolean
+  totp_enabled: boolean // TOTP 双因素认证
+  totp_encryption_key_configured: boolean // TOTP 加密密钥是否已配置
   // Default settings
   default_balance: number
   default_concurrency: number
@@ -68,6 +70,7 @@ export interface UpdateSettingsRequest {
   email_verify_enabled?: boolean
   promo_code_enabled?: boolean
   password_reset_enabled?: boolean
+  totp_enabled?: boolean // TOTP 双因素认证
   default_balance?: number
   default_concurrency?: number
   site_name?: string

frontend/src/api/auth.ts

@@ -11,9 +11,23 @@ import type {
   CurrentUserResponse,
   SendVerifyCodeRequest,
   SendVerifyCodeResponse,
-  PublicSettings
+  PublicSettings,
+  TotpLoginResponse,
+  TotpLogin2FARequest
 } from '@/types'
 
+/**
+ * Login response type - can be either full auth or 2FA required
+ */
+export type LoginResponse = AuthResponse | TotpLoginResponse
+
+/**
+ * Type guard to check if login response requires 2FA
+ */
+export function isTotp2FARequired(response: LoginResponse): response is TotpLoginResponse {
+  return 'requires_2fa' in response && response.requires_2fa === true
+}
+
 /**
  * Store authentication token in localStorage
  */
@@ -38,11 +52,28 @@ export function clearAuthToken(): void {
 
 /**
  * User login
- * @param credentials - Username and password
+ * @param credentials - Email and password
+ * @returns Authentication response with token and user data, or 2FA required response
+ */
+export async function login(credentials: LoginRequest): Promise<LoginResponse> {
+  const { data } = await apiClient.post<LoginResponse>('/auth/login', credentials)
+
+  // Only store token if 2FA is not required
+  if (!isTotp2FARequired(data)) {
+    setAuthToken(data.access_token)
+    localStorage.setItem('auth_user', JSON.stringify(data.user))
+  }
+
+  return data
+}
+
+/**
+ * Complete login with 2FA code
+ * @param request - Temp token and TOTP code
  * @returns Authentication response with token and user data
  */
-export async function login(credentials: LoginRequest): Promise<AuthResponse> {
-  const { data } = await apiClient.post<AuthResponse>('/auth/login', credentials)
+export async function login2FA(request: TotpLogin2FARequest): Promise<AuthResponse> {
+  const { data } = await apiClient.post<AuthResponse>('/auth/login/2fa', request)
 
   // Store token and user data
   setAuthToken(data.access_token)
@@ -186,6 +217,8 @@ export async function resetPassword(request: ResetPasswordRequest): Promise<Rese
 
 export const authAPI = {
   login,
+  login2FA,
+  isTotp2FARequired,
   register,
   getCurrentUser,
   logout,

frontend/src/api/index.ts

@@ -7,7 +7,7 @@
 export { apiClient } from './client'
 
 // Auth API
-export { authAPI } from './auth'
+export { authAPI, isTotp2FARequired, type LoginResponse } from './auth'
 
 // User APIs
 export { keysAPI } from './keys'
@@ -15,6 +15,7 @@ export { usageAPI } from './usage'
 export { userAPI } from './user'
 export { redeemAPI, type RedeemHistoryItem } from './redeem'
 export { userGroupsAPI } from './groups'
+export { totpAPI } from './totp'
 
 // Admin APIs
 export { adminAPI } from './admin'

frontend/src/api/totp.ts

@@ -0,0 +1,83 @@
+/**
+ * TOTP (2FA) API endpoints
+ * Handles Two-Factor Authentication with Google Authenticator
+ */
+
+import { apiClient } from './client'
+import type {
+  TotpStatus,
+  TotpSetupRequest,
+  TotpSetupResponse,
+  TotpEnableRequest,
+  TotpEnableResponse,
+  TotpDisableRequest,
+  TotpVerificationMethod
+} from '@/types'
+
+/**
+ * Get TOTP status for current user
+ * @returns TOTP status including enabled state and feature availability
+ */
+export async function getStatus(): Promise<TotpStatus> {
+  const { data } = await apiClient.get<TotpStatus>('/user/totp/status')
+  return data
+}
+
+/**
+ * Get verification method for TOTP operations
+ * @returns Method ('email' or 'password') required for setup/disable
+ */
+export async function getVerificationMethod(): Promise<TotpVerificationMethod> {
+  const { data } = await apiClient.get<TotpVerificationMethod>('/user/totp/verification-method')
+  return data
+}
+
+/**
+ * Send email verification code for TOTP operations
+ * @returns Success response
+ */
+export async function sendVerifyCode(): Promise<{ success: boolean }> {
+  const { data } = await apiClient.post<{ success: boolean }>('/user/totp/send-code')
+  return data
+}
+
+/**
+ * Initiate TOTP setup - generates secret and QR code
+ * @param request - Email code or password depending on verification method
+ * @returns Setup response with secret, QR code URL, and setup token
+ */
+export async function initiateSetup(request?: TotpSetupRequest): Promise<TotpSetupResponse> {
+  const { data } = await apiClient.post<TotpSetupResponse>('/user/totp/setup', request || {})
+  return data
+}
+
+/**
+ * Complete TOTP setup by verifying the code
+ * @param request - TOTP code and setup token
+ * @returns Enable response with success status and enabled timestamp
+ */
+export async function enable(request: TotpEnableRequest): Promise<TotpEnableResponse> {
+  const { data } = await apiClient.post<TotpEnableResponse>('/user/totp/enable', request)
+  return data
+}
+
+/**
+ * Disable TOTP for current user
+ * @param request - Email code or password depending on verification method
+ * @returns Success response
+ */
+export async function disable(request: TotpDisableRequest): Promise<{ success: boolean }> {
+  const { data } = await apiClient.post<{ success: boolean }>('/user/totp/disable', request)
+  return data
+}
+
+export const totpAPI = {
+  getStatus,
+  getVerificationMethod,
+  sendVerifyCode,
+  initiateSetup,
+  enable,
+  disable
+}
+
+export default totpAPI