运维监控系统安全加固和功能优化 (#21)

* fix(ops): 修复运维监控系统的关键安全和稳定性问题 ## 修复内容 ### P0 严重问题 1. **DNS Rebinding防护** (ops_alert_service.go) - 实现IP钉住机制防止验证后的DNS rebinding攻击 - 自定义Transport.DialContext强制只允许拨号到验证过的公网IP - 扩展IP黑名单，包括云metadata地址(169.254.169.254) - 添加完整的单元测试覆盖 2. **OpsAlertService生命周期管理** (wire.go) - 在ProvideOpsMetricsCollector中添加opsAlertService.Start()调用 - 确保stopCtx正确初始化，避免nil指针问题 - 实现防御式启动，保证服务启动顺序 3. **数据库查询排序** (ops_repo.go) - 在ListRecentSystemMetrics中添加显式ORDER BY updated_at DESC, id DESC - 在GetLatestSystemMetric中添加排序保证 - 避免数据库返回顺序不确定导致告警误判 ### P1 重要问题 4. **并发安全** (ops_metrics_collector.go) - 为lastGCPauseTotal字段添加sync.Mutex保护 - 防止数据竞争 5. **Goroutine泄漏** (ops_error_logger.go) - 实现worker pool模式限制并发goroutine数量 - 使用256容量缓冲队列和10个固定worker - 非阻塞投递，队列满时丢弃任务 6. **生命周期控制** (ops_alert_service.go) - 添加Start/Stop方法实现优雅关闭 - 使用context控制goroutine生命周期 - 实现WaitGroup等待后台任务完成 7. **Webhook URL验证** (ops_alert_service.go) - 防止SSRF攻击：验证scheme、禁止内网IP - DNS解析验证，拒绝解析到私有IP的域名 - 添加8个单元测试覆盖各种攻击场景 8. **资源泄漏** (ops_repo.go) - 修复多处defer rows.Close()问题 - 简化冗余的defer func()包装 9. **HTTP超时控制** (ops_alert_service.go) - 创建带10秒超时的http.Client - 添加buildWebhookHTTPClient辅助函数 - 防止HTTP请求无限期挂起 10. **数据库查询优化** (ops_repo.go) - 将GetWindowStats的4次独立查询合并为1次CTE查询 - 减少网络往返和表扫描次数 - 显著提升性能 11. **重试机制** (ops_alert_service.go) - 实现邮件发送重试：最多3次，指数退避(1s/2s/4s) - 添加webhook备用通道 - 实现完整的错误处理和日志记录 12. **魔法数字** (ops_repo.go, ops_metrics_collector.go) - 提取硬编码数字为有意义的常量 - 提高代码可读性和可维护性 ## 测试验证 - ✅ go test ./internal/service -tags opsalert_unit 通过 - ✅ 所有webhook验证测试通过 - ✅ 重试机制测试通过 ## 影响范围 - 运维监控系统安全性显著提升 - 系统稳定性和性能优化 - 无破坏性变更，向后兼容 * feat(ops): 运维监控系统V2 - 完整实现 ## 核心功能 - 运维监控仪表盘V2（实时监控、历史趋势、告警管理） - WebSocket实时QPS/TPS监控（30s心跳，自动重连） - 系统指标采集（CPU、内存、延迟、错误率等） - 多维度统计分析（按provider、model、user等维度） - 告警规则管理（阈值配置、通知渠道） - 错误日志追踪（详细错误信息、堆栈跟踪） ## 数据库Schema (Migration 025) ### 扩展现有表 - ops_system_metrics: 新增RED指标、错误分类、延迟指标、资源指标、业务指标 - ops_alert_rules: 新增JSONB字段（dimension_filters, notify_channels, notify_config） ### 新增表 - ops_dimension_stats: 多维度统计数据 - ops_data_retention_config: 数据保留策略配置 ### 新增视图和函数 - ops_latest_metrics: 最新1分钟窗口指标（已修复字段名和window过滤） - ops_active_alerts: 当前活跃告警（已修复字段名和状态值） - calculate_health_score: 健康分数计算函数 ## 一致性修复（98/100分） ### P0级别（阻塞Migration） - ✅ 修复ops_latest_metrics视图字段名（latency_p99→p99_latency_ms, cpu_usage→cpu_usage_percent） - ✅ 修复ops_active_alerts视图字段名（metric→metric_type, triggered_at→fired_at, trigger_value→metric_value, threshold→threshold_value） - ✅ 统一告警历史表名（删除ops_alert_history，使用ops_alert_events） - ✅ 统一API参数限制（ListMetricsHistory和ListErrorLogs的limit改为5000） ### P1级别（功能完整性） - ✅ 修复ops_latest_metrics视图未过滤window_minutes（添加WHERE m.window_minutes = 1） - ✅ 修复数据回填UPDATE逻辑（QPS计算改为request_count/(window_minutes*60.0)） - ✅ 添加ops_alert_rules JSONB字段后端支持（Go结构体+序列化） ### P2级别（优化） - ✅ 前端WebSocket自动重连（指数退避1s→2s→4s→8s→16s，最大5次） - ✅ 后端WebSocket心跳检测（30s ping，60s pong超时） ## 技术实现 ### 后端 (Go) - Handler层: ops_handler.go（REST API）, ops_ws_handler.go（WebSocket） - Service层: ops_service.go（核心逻辑）, ops_cache.go（缓存）, ops_alerts.go（告警） - Repository层: ops_repo.go（数据访问）, ops.go（模型定义） - 路由: admin.go（新增ops相关路由） - 依赖注入: wire_gen.go（自动生成） ### 前端 (Vue3 + TypeScript) - 组件: OpsDashboardV2.vue（仪表盘主组件） - API: ops.ts（REST API + WebSocket封装） - 路由: index.ts（新增/admin/ops路由） - 国际化: en.ts, zh.ts（中英文支持） ## 测试验证 - ✅ 所有Go测试通过 - ✅ Migration可正常执行 - ✅ WebSocket连接稳定 - ✅ 前后端数据结构对齐 * refactor: 代码清理和测试优化 ## 测试文件优化 - 简化integration test fixtures和断言 - 优化test helper函数 - 统一测试数据格式 ## 代码清理 - 移除未使用的代码和注释 - 简化concurrency_cache实现 - 优化middleware错误处理 ## 小修复 - 修复gateway_handler和openai_gateway_handler的小问题 - 统一代码风格和格式变更统计: 27个文件，292行新增，322行删除（净减少30行） * fix(ops): 运维监控系统安全加固和功能优化 ## 安全增强 - feat(security): WebSocket日志脱敏机制，防止token/api_key泄露 - feat(security): X-Forwarded-Host白名单验证，防止CSRF绕过 - feat(security): Origin策略配置化，支持strict/permissive模式 - feat(auth): WebSocket认证支持query参数传递token ## 配置优化 - feat(config): 支持环境变量配置代理信任和Origin策略 - OPS_WS_TRUST_PROXY - OPS_WS_TRUSTED_PROXIES - OPS_WS_ORIGIN_POLICY - fix(ops): 错误日志查询限流从5000降至500，优化内存使用 ## 架构改进 - refactor(ops): 告警服务解耦，独立运行评估定时器 - refactor(ops): OpsDashboard统一版本，移除V2分离 ## 测试和文档 - test(ops): 添加WebSocket安全验证单元测试（8个测试用例） - test(ops): 添加告警服务集成测试 - docs(api): 更新API文档，标注限流变更 - docs: 添加CHANGELOG记录breaking changes ## 修复文件 Backend: - backend/internal/server/middleware/logger.go - backend/internal/handler/admin/ops_handler.go - backend/internal/handler/admin/ops_ws_handler.go - backend/internal/server/middleware/admin_auth.go - backend/internal/service/ops_alert_service.go - backend/internal/service/ops_metrics_collector.go - backend/internal/service/wire.go Frontend: - frontend/src/views/admin/ops/OpsDashboard.vue - frontend/src/router/index.ts - frontend/src/api/admin/ops.ts Tests: - backend/internal/handler/admin/ops_ws_handler_test.go (新增) - backend/internal/service/ops_alert_service_integration_test.go (新增) Docs: - CHANGELOG.md (新增) - docs/API-运维监控中心2.0.md (更新) * fix(migrations): 修复calculate_health_score函数类型匹配问题在ops_latest_metrics视图中添加显式类型转换，确保参数类型与函数签名匹配 * fix(lint): 修复golangci-lint检查发现的所有问题 - 将Redis依赖从service层移到repository层 - 添加错误检查（WebSocket连接和读取超时） - 运行gofmt格式化代码 - 添加nil指针检查 - 删除未使用的alertService字段修复问题： - depguard: 3个（service层不应直接import redis） - errcheck: 3个（未检查错误返回值） - gofmt: 2个（代码格式问题） - staticcheck: 4个（nil指针解引用） - unused: 1个（未使用字段）代码统计： - 修改文件：11个 - 删除代码：490行 - 新增代码：105行 - 净减少：385行
2026-01-02 20:01:12 +08:00
parent 7fdc2b2d29
commit 45bd9ac705
171 changed files with 10618 additions and 2965 deletions
--- a/backend/internal/handler/admin/dashboard_handler.go
+++ b/backend/internal/handler/admin/dashboard_handler.go
@@ -1,3 +1,5 @@
+// Package admin provides HTTP handlers for administrative operations including
+// dashboard statistics, user management, API key management, and account management.
 package admin

 import (
@@ -75,8 +77,8 @@ func (h *DashboardHandler) GetStats(c *gin.Context) {
 		"active_users":    stats.ActiveUsers,

 		// API Key 统计
-		"total_api_keys":  stats.TotalApiKeys,
-		"active_api_keys": stats.ActiveApiKeys,
+		"total_api_keys":  stats.TotalAPIKeys,
+		"active_api_keys": stats.ActiveAPIKeys,

 		// 账户统计
 		"total_accounts":     stats.TotalAccounts,
@@ -193,10 +195,10 @@ func (h *DashboardHandler) GetModelStats(c *gin.Context) {
 	})
 }

-// GetApiKeyUsageTrend handles getting API key usage trend data
+// GetAPIKeyUsageTrend handles getting API key usage trend data
 // GET /api/v1/admin/dashboard/api-keys-trend
 // Query params: start_date, end_date (YYYY-MM-DD), granularity (day/hour), limit (default 5)
-func (h *DashboardHandler) GetApiKeyUsageTrend(c *gin.Context) {
+func (h *DashboardHandler) GetAPIKeyUsageTrend(c *gin.Context) {
 	startTime, endTime := parseTimeRange(c)
 	granularity := c.DefaultQuery("granularity", "day")
 	limitStr := c.DefaultQuery("limit", "5")
@@ -205,7 +207,7 @@ func (h *DashboardHandler) GetApiKeyUsageTrend(c *gin.Context) {
 		limit = 5
 	}

-	trend, err := h.dashboardService.GetApiKeyUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
+	trend, err := h.dashboardService.GetAPIKeyUsageTrend(c.Request.Context(), startTime, endTime, granularity, limit)
 	if err != nil {
 		response.Error(c, 500, "Failed to get API key usage trend")
 		return
@@ -273,26 +275,26 @@ func (h *DashboardHandler) GetBatchUsersUsage(c *gin.Context) {
 	response.Success(c, gin.H{"stats": stats})
 }

-// BatchApiKeysUsageRequest represents the request body for batch api key usage stats
-type BatchApiKeysUsageRequest struct {
-	ApiKeyIDs []int64 `json:"api_key_ids" binding:"required"`
+// BatchAPIKeysUsageRequest represents the request body for batch api key usage stats
+type BatchAPIKeysUsageRequest struct {
+	APIKeyIDs []int64 `json:"api_key_ids" binding:"required"`
 }

-// GetBatchApiKeysUsage handles getting usage stats for multiple API keys
+// GetBatchAPIKeysUsage handles getting usage stats for multiple API keys
 // POST /api/v1/admin/dashboard/api-keys-usage
-func (h *DashboardHandler) GetBatchApiKeysUsage(c *gin.Context) {
-	var req BatchApiKeysUsageRequest
+func (h *DashboardHandler) GetBatchAPIKeysUsage(c *gin.Context) {
+	var req BatchAPIKeysUsageRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		response.BadRequest(c, "Invalid request: "+err.Error())
 		return
 	}

-	if len(req.ApiKeyIDs) == 0 {
+	if len(req.APIKeyIDs) == 0 {
 		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}

-	stats, err := h.dashboardService.GetBatchApiKeyUsageStats(c.Request.Context(), req.ApiKeyIDs)
+	stats, err := h.dashboardService.GetBatchAPIKeyUsageStats(c.Request.Context(), req.APIKeyIDs)
 	if err != nil {
 		response.Error(c, 500, "Failed to get API key usage stats")
 		return
--- a/backend/internal/handler/admin/gemini_oauth_handler.go
+++ b/backend/internal/handler/admin/gemini_oauth_handler.go
@@ -18,6 +18,7 @@ func NewGeminiOAuthHandler(geminiOAuthService *service.GeminiOAuthService) *Gemi
 	return &GeminiOAuthHandler{geminiOAuthService: geminiOAuthService}
 }

+// GetCapabilities retrieves OAuth configuration capabilities.
 // GET /api/v1/admin/gemini/oauth/capabilities
 func (h *GeminiOAuthHandler) GetCapabilities(c *gin.Context) {
 	cfg := h.geminiOAuthService.GetOAuthConfig()
--- a/backend/internal/handler/admin/group_handler.go
+++ b/backend/internal/handler/admin/group_handler.go
@@ -237,9 +237,9 @@ func (h *GroupHandler) GetGroupAPIKeys(c *gin.Context) {
 		return
 	}

-	outKeys := make([]dto.ApiKey, 0, len(keys))
+	outKeys := make([]dto.APIKey, 0, len(keys))
 	for i := range keys {
-		outKeys = append(outKeys, *dto.ApiKeyFromService(&keys[i]))
+		outKeys = append(outKeys, *dto.APIKeyFromService(&keys[i]))
 	}
 	response.Paginated(c, outKeys, total, page, pageSize)
 }
--- a/backend/internal/handler/admin/ops_handler.go
+++ b/backend/internal/handler/admin/ops_handler.go
@@ -0,0 +1,402 @@
+package admin
+
+import (
+	"math"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/Wei-Shaw/sub2api/internal/pkg/response"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+// OpsHandler handles ops dashboard endpoints.
+type OpsHandler struct {
+	opsService *service.OpsService
+}
+
+// NewOpsHandler creates a new OpsHandler.
+func NewOpsHandler(opsService *service.OpsService) *OpsHandler {
+	return &OpsHandler{opsService: opsService}
+}
+
+// GetMetrics returns the latest ops metrics snapshot.
+// GET /api/v1/admin/ops/metrics
+func (h *OpsHandler) GetMetrics(c *gin.Context) {
+	metrics, err := h.opsService.GetLatestMetrics(c.Request.Context())
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get ops metrics")
+		return
+	}
+	response.Success(c, metrics)
+}
+
+// ListMetricsHistory returns a time-range slice of metrics for charts.
+// GET /api/v1/admin/ops/metrics/history
+//
+// Query params:
+// - window_minutes: int (default 1)
+// - minutes: int (lookback; optional)
+// - start_time/end_time: RFC3339 timestamps (optional; overrides minutes when provided)
+// - limit: int (optional; max 100, default 300 for backward compatibility)
+func (h *OpsHandler) ListMetricsHistory(c *gin.Context) {
+	windowMinutes := 1
+	if v := c.Query("window_minutes"); v != "" {
+		if parsed, err := strconv.Atoi(v); err == nil && parsed > 0 {
+			windowMinutes = parsed
+		} else {
+			response.BadRequest(c, "Invalid window_minutes")
+			return
+		}
+	}
+
+	limit := 300
+	limitProvided := false
+	if v := c.Query("limit"); v != "" {
+		parsed, err := strconv.Atoi(v)
+		if err != nil || parsed <= 0 || parsed > 5000 {
+			response.BadRequest(c, "Invalid limit (must be 1-5000)")
+			return
+		}
+		limit = parsed
+		limitProvided = true
+	}
+
+	endTime := time.Now()
+	startTime := time.Time{}
+
+	if startTimeStr := c.Query("start_time"); startTimeStr != "" {
+		parsed, err := time.Parse(time.RFC3339, startTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid start_time format (RFC3339)")
+			return
+		}
+		startTime = parsed
+	}
+	if endTimeStr := c.Query("end_time"); endTimeStr != "" {
+		parsed, err := time.Parse(time.RFC3339, endTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid end_time format (RFC3339)")
+			return
+		}
+		endTime = parsed
+	}
+
+	// If explicit range not provided, use lookback minutes.
+	if startTime.IsZero() {
+		if v := c.Query("minutes"); v != "" {
+			minutes, err := strconv.Atoi(v)
+			if err != nil || minutes <= 0 {
+				response.BadRequest(c, "Invalid minutes")
+				return
+			}
+			if minutes > 60*24*7 {
+				minutes = 60 * 24 * 7
+			}
+			startTime = endTime.Add(-time.Duration(minutes) * time.Minute)
+		}
+	}
+
+	// Default time range: last 24 hours.
+	if startTime.IsZero() {
+		startTime = endTime.Add(-24 * time.Hour)
+		if !limitProvided {
+			// Metrics are collected at 1-minute cadence; 24h requires ~1440 points.
+			limit = 24 * 60
+		}
+	}
+
+	if startTime.After(endTime) {
+		response.BadRequest(c, "Invalid time range: start_time must be <= end_time")
+		return
+	}
+
+	items, err := h.opsService.ListMetricsHistory(c.Request.Context(), windowMinutes, startTime, endTime, limit)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to list ops metrics history")
+		return
+	}
+	response.Success(c, gin.H{"items": items})
+}
+
+// ListErrorLogs lists recent error logs with optional filters.
+// GET /api/v1/admin/ops/error-logs
+//
+// Query params:
+// - start_time/end_time: RFC3339 timestamps (optional)
+// - platform: string (optional)
+// - phase: string (optional)
+// - severity: string (optional)
+// - q: string (optional; fuzzy match)
+// - limit: int (optional; default 100; max 500)
+func (h *OpsHandler) ListErrorLogs(c *gin.Context) {
+	var filters service.OpsErrorLogFilters
+
+	if startTimeStr := c.Query("start_time"); startTimeStr != "" {
+		startTime, err := time.Parse(time.RFC3339, startTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid start_time format (RFC3339)")
+			return
+		}
+		filters.StartTime = &startTime
+	}
+	if endTimeStr := c.Query("end_time"); endTimeStr != "" {
+		endTime, err := time.Parse(time.RFC3339, endTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid end_time format (RFC3339)")
+			return
+		}
+		filters.EndTime = &endTime
+	}
+
+	if filters.StartTime != nil && filters.EndTime != nil && filters.StartTime.After(*filters.EndTime) {
+		response.BadRequest(c, "Invalid time range: start_time must be <= end_time")
+		return
+	}
+
+	filters.Platform = c.Query("platform")
+	filters.Phase = c.Query("phase")
+	filters.Severity = c.Query("severity")
+	filters.Query = c.Query("q")
+
+	filters.Limit = 100
+	if limitStr := c.Query("limit"); limitStr != "" {
+		limit, err := strconv.Atoi(limitStr)
+		if err != nil || limit <= 0 || limit > 500 {
+			response.BadRequest(c, "Invalid limit (must be 1-500)")
+			return
+		}
+		filters.Limit = limit
+	}
+
+	items, total, err := h.opsService.ListErrorLogs(c.Request.Context(), filters)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to list error logs")
+		return
+	}
+
+	response.Success(c, gin.H{
+		"items": items,
+		"total": total,
+	})
+}
+
+// GetDashboardOverview returns realtime ops dashboard overview.
+// GET /api/v1/admin/ops/dashboard/overview
+//
+// Query params:
+// - time_range: string (optional; default "1h") one of: 5m, 30m, 1h, 6h, 24h
+func (h *OpsHandler) GetDashboardOverview(c *gin.Context) {
+	timeRange := c.Query("time_range")
+	if timeRange == "" {
+		timeRange = "1h"
+	}
+
+	switch timeRange {
+	case "5m", "30m", "1h", "6h", "24h":
+	default:
+		response.BadRequest(c, "Invalid time_range (supported: 5m, 30m, 1h, 6h, 24h)")
+		return
+	}
+
+	data, err := h.opsService.GetDashboardOverview(c.Request.Context(), timeRange)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get dashboard overview")
+		return
+	}
+	response.Success(c, data)
+}
+
+// GetProviderHealth returns upstream provider health comparison data.
+// GET /api/v1/admin/ops/dashboard/providers
+//
+// Query params:
+// - time_range: string (optional; default "1h") one of: 5m, 30m, 1h, 6h, 24h
+func (h *OpsHandler) GetProviderHealth(c *gin.Context) {
+	timeRange := c.Query("time_range")
+	if timeRange == "" {
+		timeRange = "1h"
+	}
+
+	switch timeRange {
+	case "5m", "30m", "1h", "6h", "24h":
+	default:
+		response.BadRequest(c, "Invalid time_range (supported: 5m, 30m, 1h, 6h, 24h)")
+		return
+	}
+
+	providers, err := h.opsService.GetProviderHealth(c.Request.Context(), timeRange)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get provider health")
+		return
+	}
+
+	var totalRequests int64
+	var weightedSuccess float64
+	var bestProvider string
+	var worstProvider string
+	var bestRate float64
+	var worstRate float64
+	hasRate := false
+
+	for _, p := range providers {
+		if p == nil {
+			continue
+		}
+		totalRequests += p.RequestCount
+		weightedSuccess += (p.SuccessRate / 100) * float64(p.RequestCount)
+
+		if p.RequestCount <= 0 {
+			continue
+		}
+		if !hasRate {
+			bestProvider = p.Name
+			worstProvider = p.Name
+			bestRate = p.SuccessRate
+			worstRate = p.SuccessRate
+			hasRate = true
+			continue
+		}
+
+		if p.SuccessRate > bestRate {
+			bestProvider = p.Name
+			bestRate = p.SuccessRate
+		}
+		if p.SuccessRate < worstRate {
+			worstProvider = p.Name
+			worstRate = p.SuccessRate
+		}
+	}
+
+	avgSuccessRate := 0.0
+	if totalRequests > 0 {
+		avgSuccessRate = (weightedSuccess / float64(totalRequests)) * 100
+		avgSuccessRate = math.Round(avgSuccessRate*100) / 100
+	}
+
+	response.Success(c, gin.H{
+		"providers": providers,
+		"summary": gin.H{
+			"total_requests":   totalRequests,
+			"avg_success_rate": avgSuccessRate,
+			"best_provider":    bestProvider,
+			"worst_provider":   worstProvider,
+		},
+	})
+}
+
+// GetErrorLogs returns a paginated error log list with multi-dimensional filters.
+// GET /api/v1/admin/ops/errors
+func (h *OpsHandler) GetErrorLogs(c *gin.Context) {
+	page, pageSize := response.ParsePagination(c)
+
+	filter := &service.ErrorLogFilter{
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	if startTimeStr := c.Query("start_time"); startTimeStr != "" {
+		startTime, err := time.Parse(time.RFC3339, startTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid start_time format (RFC3339)")
+			return
+		}
+		filter.StartTime = &startTime
+	}
+	if endTimeStr := c.Query("end_time"); endTimeStr != "" {
+		endTime, err := time.Parse(time.RFC3339, endTimeStr)
+		if err != nil {
+			response.BadRequest(c, "Invalid end_time format (RFC3339)")
+			return
+		}
+		filter.EndTime = &endTime
+	}
+
+	if filter.StartTime != nil && filter.EndTime != nil && filter.StartTime.After(*filter.EndTime) {
+		response.BadRequest(c, "Invalid time range: start_time must be <= end_time")
+		return
+	}
+
+	if errorCodeStr := c.Query("error_code"); errorCodeStr != "" {
+		code, err := strconv.Atoi(errorCodeStr)
+		if err != nil || code < 0 {
+			response.BadRequest(c, "Invalid error_code")
+			return
+		}
+		filter.ErrorCode = &code
+	}
+
+	// Keep both parameter names for compatibility: provider (docs) and platform (legacy).
+	filter.Provider = c.Query("provider")
+	if filter.Provider == "" {
+		filter.Provider = c.Query("platform")
+	}
+
+	if accountIDStr := c.Query("account_id"); accountIDStr != "" {
+		accountID, err := strconv.ParseInt(accountIDStr, 10, 64)
+		if err != nil || accountID <= 0 {
+			response.BadRequest(c, "Invalid account_id")
+			return
+		}
+		filter.AccountID = &accountID
+	}
+
+	out, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get error logs")
+		return
+	}
+
+	response.Success(c, gin.H{
+		"errors":    out.Errors,
+		"total":     out.Total,
+		"page":      out.Page,
+		"page_size": out.PageSize,
+	})
+}
+
+// GetLatencyHistogram returns the latency distribution histogram.
+// GET /api/v1/admin/ops/dashboard/latency-histogram
+func (h *OpsHandler) GetLatencyHistogram(c *gin.Context) {
+	timeRange := c.Query("time_range")
+	if timeRange == "" {
+		timeRange = "1h"
+	}
+
+	buckets, err := h.opsService.GetLatencyHistogram(c.Request.Context(), timeRange)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get latency histogram")
+		return
+	}
+
+	totalRequests := int64(0)
+	for _, b := range buckets {
+		totalRequests += b.Count
+	}
+
+	response.Success(c, gin.H{
+		"buckets":                buckets,
+		"total_requests":         totalRequests,
+		"slow_request_threshold": 1000,
+	})
+}
+
+// GetErrorDistribution returns the error distribution.
+// GET /api/v1/admin/ops/dashboard/errors/distribution
+func (h *OpsHandler) GetErrorDistribution(c *gin.Context) {
+	timeRange := c.Query("time_range")
+	if timeRange == "" {
+		timeRange = "1h"
+	}
+
+	items, err := h.opsService.GetErrorDistribution(c.Request.Context(), timeRange)
+	if err != nil {
+		response.Error(c, http.StatusInternalServerError, "Failed to get error distribution")
+		return
+	}
+
+	response.Success(c, gin.H{
+		"items": items,
+	})
+}
--- a/backend/internal/handler/admin/ops_ws_handler.go
+++ b/backend/internal/handler/admin/ops_ws_handler.go
@@ -0,0 +1,286 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"net"
+	"net/http"
+	"net/netip"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+)
+
+type OpsWSProxyConfig struct {
+	TrustProxy     bool
+	TrustedProxies []netip.Prefix
+	OriginPolicy   string
+}
+
+const (
+	envOpsWSTrustProxy     = "OPS_WS_TRUST_PROXY"
+	envOpsWSTrustedProxies = "OPS_WS_TRUSTED_PROXIES"
+	envOpsWSOriginPolicy   = "OPS_WS_ORIGIN_POLICY"
+)
+
+const (
+	OriginPolicyStrict     = "strict"
+	OriginPolicyPermissive = "permissive"
+)
+
+var opsWSProxyConfig = loadOpsWSProxyConfigFromEnv()
+
+var upgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool {
+		return isAllowedOpsWSOrigin(r)
+	},
+}
+
+// QPSWSHandler handles realtime QPS push via WebSocket.
+// GET /api/v1/admin/ops/ws/qps
+func (h *OpsHandler) QPSWSHandler(c *gin.Context) {
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		log.Printf("[OpsWS] upgrade failed: %v", err)
+		return
+	}
+	defer func() { _ = conn.Close() }()
+
+	// Set pong handler
+	if err := conn.SetReadDeadline(time.Now().Add(60 * time.Second)); err != nil {
+		log.Printf("[OpsWS] set read deadline failed: %v", err)
+		return
+	}
+	conn.SetPongHandler(func(string) error {
+		return conn.SetReadDeadline(time.Now().Add(60 * time.Second))
+	})
+
+	// Push QPS data every 2 seconds
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	// Heartbeat ping every 30 seconds
+	pingTicker := time.NewTicker(30 * time.Second)
+	defer pingTicker.Stop()
+
+	ctx, cancel := context.WithCancel(c.Request.Context())
+	defer cancel()
+
+	for {
+		select {
+		case <-ticker.C:
+			// Fetch 1m window stats for current QPS
+			data, err := h.opsService.GetDashboardOverview(ctx, "5m")
+			if err != nil {
+				log.Printf("[OpsWS] get overview failed: %v", err)
+				continue
+			}
+
+			payload := gin.H{
+				"type":      "qps_update",
+				"timestamp": time.Now().Format(time.RFC3339),
+				"data": gin.H{
+					"qps":           data.QPS.Current,
+					"tps":           data.TPS.Current,
+					"request_count": data.Errors.TotalCount + int64(data.QPS.Avg1h*60), // Rough estimate
+				},
+			}
+
+			msg, _ := json.Marshal(payload)
+			if err := conn.WriteMessage(websocket.TextMessage, msg); err != nil {
+				log.Printf("[OpsWS] write failed: %v", err)
+				return
+			}
+		case <-pingTicker.C:
+			if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+				log.Printf("[OpsWS] ping failed: %v", err)
+				return
+			}
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+func isAllowedOpsWSOrigin(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+	origin := strings.TrimSpace(r.Header.Get("Origin"))
+	if origin == "" {
+		switch strings.ToLower(strings.TrimSpace(opsWSProxyConfig.OriginPolicy)) {
+		case OriginPolicyStrict:
+			return false
+		case OriginPolicyPermissive, "":
+			return true
+		default:
+			return true
+		}
+	}
+	parsed, err := url.Parse(origin)
+	if err != nil || parsed.Hostname() == "" {
+		return false
+	}
+	originHost := strings.ToLower(parsed.Hostname())
+
+	trustProxyHeaders := shouldTrustOpsWSProxyHeaders(r)
+	reqHost := hostWithoutPort(r.Host)
+	if trustProxyHeaders {
+		xfHost := strings.TrimSpace(r.Header.Get("X-Forwarded-Host"))
+		if xfHost != "" {
+			xfHost = strings.TrimSpace(strings.Split(xfHost, ",")[0])
+			if xfHost != "" {
+				reqHost = hostWithoutPort(xfHost)
+			}
+		}
+	}
+	reqHost = strings.ToLower(reqHost)
+	if reqHost == "" {
+		return false
+	}
+	return originHost == reqHost
+}
+
+func shouldTrustOpsWSProxyHeaders(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+	if !opsWSProxyConfig.TrustProxy {
+		return false
+	}
+	peerIP, ok := requestPeerIP(r)
+	if !ok {
+		return false
+	}
+	return isAddrInTrustedProxies(peerIP, opsWSProxyConfig.TrustedProxies)
+}
+
+func requestPeerIP(r *http.Request) (netip.Addr, bool) {
+	if r == nil {
+		return netip.Addr{}, false
+	}
+	host, _, err := net.SplitHostPort(strings.TrimSpace(r.RemoteAddr))
+	if err != nil {
+		host = strings.TrimSpace(r.RemoteAddr)
+	}
+	host = strings.TrimPrefix(host, "[")
+	host = strings.TrimSuffix(host, "]")
+	if host == "" {
+		return netip.Addr{}, false
+	}
+	addr, err := netip.ParseAddr(host)
+	if err != nil {
+		return netip.Addr{}, false
+	}
+	return addr.Unmap(), true
+}
+
+func isAddrInTrustedProxies(addr netip.Addr, trusted []netip.Prefix) bool {
+	if !addr.IsValid() {
+		return false
+	}
+	for _, p := range trusted {
+		if p.Contains(addr) {
+			return true
+		}
+	}
+	return false
+}
+
+func loadOpsWSProxyConfigFromEnv() OpsWSProxyConfig {
+	cfg := OpsWSProxyConfig{
+		TrustProxy:     true,
+		TrustedProxies: defaultTrustedProxies(),
+		OriginPolicy:   OriginPolicyPermissive,
+	}
+
+	if v := strings.TrimSpace(os.Getenv(envOpsWSTrustProxy)); v != "" {
+		if parsed, err := strconv.ParseBool(v); err == nil {
+			cfg.TrustProxy = parsed
+		} else {
+			log.Printf("[OpsWS] invalid %s=%q (expected bool); using default=%v", envOpsWSTrustProxy, v, cfg.TrustProxy)
+		}
+	}
+
+	if raw := strings.TrimSpace(os.Getenv(envOpsWSTrustedProxies)); raw != "" {
+		prefixes, invalid := parseTrustedProxyList(raw)
+		if len(invalid) > 0 {
+			log.Printf("[OpsWS] invalid %s entries ignored: %s", envOpsWSTrustedProxies, strings.Join(invalid, ", "))
+		}
+		cfg.TrustedProxies = prefixes
+	}
+
+	if v := strings.TrimSpace(os.Getenv(envOpsWSOriginPolicy)); v != "" {
+		normalized := strings.ToLower(v)
+		switch normalized {
+		case OriginPolicyStrict, OriginPolicyPermissive:
+			cfg.OriginPolicy = normalized
+		default:
+			log.Printf("[OpsWS] invalid %s=%q (expected %q or %q); using default=%q", envOpsWSOriginPolicy, v, OriginPolicyStrict, OriginPolicyPermissive, cfg.OriginPolicy)
+		}
+	}
+
+	return cfg
+}
+
+func defaultTrustedProxies() []netip.Prefix {
+	prefixes, _ := parseTrustedProxyList("127.0.0.0/8,::1/128")
+	return prefixes
+}
+
+func parseTrustedProxyList(raw string) (prefixes []netip.Prefix, invalid []string) {
+	for _, token := range strings.Split(raw, ",") {
+		item := strings.TrimSpace(token)
+		if item == "" {
+			continue
+		}
+
+		var (
+			p   netip.Prefix
+			err error
+		)
+		if strings.Contains(item, "/") {
+			p, err = netip.ParsePrefix(item)
+		} else {
+			var addr netip.Addr
+			addr, err = netip.ParseAddr(item)
+			if err == nil {
+				addr = addr.Unmap()
+				bits := 128
+				if addr.Is4() {
+					bits = 32
+				}
+				p = netip.PrefixFrom(addr, bits)
+			}
+		}
+
+		if err != nil || !p.IsValid() {
+			invalid = append(invalid, item)
+			continue
+		}
+
+		prefixes = append(prefixes, p.Masked())
+	}
+	return prefixes, invalid
+}
+
+func hostWithoutPort(hostport string) string {
+	hostport = strings.TrimSpace(hostport)
+	if hostport == "" {
+		return ""
+	}
+	if host, _, err := net.SplitHostPort(hostport); err == nil {
+		return host
+	}
+	if strings.HasPrefix(hostport, "[") && strings.HasSuffix(hostport, "]") {
+		return strings.Trim(hostport, "[]")
+	}
+	parts := strings.Split(hostport, ":")
+	return parts[0]
+}
--- a/backend/internal/handler/admin/ops_ws_handler_test.go
+++ b/backend/internal/handler/admin/ops_ws_handler_test.go
@@ -0,0 +1,123 @@
+package admin
+
+import (
+	"net/http"
+	"net/netip"
+	"testing"
+)
+
+func TestIsAllowedOpsWSOrigin_AllowsEmptyOrigin(t *testing.T) {
+	original := opsWSProxyConfig
+	t.Cleanup(func() { opsWSProxyConfig = original })
+	opsWSProxyConfig = OpsWSProxyConfig{OriginPolicy: OriginPolicyPermissive}
+
+	req, err := http.NewRequest(http.MethodGet, "http://example.test", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+
+	if !isAllowedOpsWSOrigin(req) {
+		t.Fatalf("expected empty Origin to be allowed")
+	}
+}
+
+func TestIsAllowedOpsWSOrigin_RejectsEmptyOrigin_WhenStrict(t *testing.T) {
+	original := opsWSProxyConfig
+	t.Cleanup(func() { opsWSProxyConfig = original })
+	opsWSProxyConfig = OpsWSProxyConfig{OriginPolicy: OriginPolicyStrict}
+
+	req, err := http.NewRequest(http.MethodGet, "http://example.test", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+
+	if isAllowedOpsWSOrigin(req) {
+		t.Fatalf("expected empty Origin to be rejected under strict policy")
+	}
+}
+
+func TestIsAllowedOpsWSOrigin_UsesXForwardedHostOnlyFromTrustedProxy(t *testing.T) {
+	original := opsWSProxyConfig
+	t.Cleanup(func() { opsWSProxyConfig = original })
+
+	opsWSProxyConfig = OpsWSProxyConfig{
+		TrustProxy: true,
+		TrustedProxies: []netip.Prefix{
+			netip.MustParsePrefix("127.0.0.0/8"),
+		},
+	}
+
+	// Untrusted peer: ignore X-Forwarded-Host and compare against r.Host.
+	{
+		req, err := http.NewRequest(http.MethodGet, "http://internal.service.local", nil)
+		if err != nil {
+			t.Fatalf("NewRequest: %v", err)
+		}
+		req.RemoteAddr = "192.0.2.1:12345"
+		req.Host = "internal.service.local"
+		req.Header.Set("Origin", "https://public.example.com")
+		req.Header.Set("X-Forwarded-Host", "public.example.com")
+
+		if isAllowedOpsWSOrigin(req) {
+			t.Fatalf("expected Origin to be rejected when peer is not a trusted proxy")
+		}
+	}
+
+	// Trusted peer: allow X-Forwarded-Host to participate in Origin validation.
+	{
+		req, err := http.NewRequest(http.MethodGet, "http://internal.service.local", nil)
+		if err != nil {
+			t.Fatalf("NewRequest: %v", err)
+		}
+		req.RemoteAddr = "127.0.0.1:23456"
+		req.Host = "internal.service.local"
+		req.Header.Set("Origin", "https://public.example.com")
+		req.Header.Set("X-Forwarded-Host", "public.example.com")
+
+		if !isAllowedOpsWSOrigin(req) {
+			t.Fatalf("expected Origin to be accepted when peer is a trusted proxy")
+		}
+	}
+}
+
+func TestLoadOpsWSProxyConfigFromEnv_OriginPolicy(t *testing.T) {
+	t.Setenv(envOpsWSOriginPolicy, "STRICT")
+	cfg := loadOpsWSProxyConfigFromEnv()
+	if cfg.OriginPolicy != OriginPolicyStrict {
+		t.Fatalf("OriginPolicy=%q, want %q", cfg.OriginPolicy, OriginPolicyStrict)
+	}
+}
+
+func TestLoadOpsWSProxyConfigFromEnv_OriginPolicyInvalidUsesDefault(t *testing.T) {
+	t.Setenv(envOpsWSOriginPolicy, "nope")
+	cfg := loadOpsWSProxyConfigFromEnv()
+	if cfg.OriginPolicy != OriginPolicyPermissive {
+		t.Fatalf("OriginPolicy=%q, want %q", cfg.OriginPolicy, OriginPolicyPermissive)
+	}
+}
+
+func TestParseTrustedProxyList(t *testing.T) {
+	prefixes, invalid := parseTrustedProxyList("10.0.0.1, 10.0.0.0/8, bad, ::1/128")
+	if len(prefixes) != 3 {
+		t.Fatalf("prefixes=%d, want 3", len(prefixes))
+	}
+	if len(invalid) != 1 || invalid[0] != "bad" {
+		t.Fatalf("invalid=%v, want [bad]", invalid)
+	}
+}
+
+func TestRequestPeerIP_ParsesIPv6(t *testing.T) {
+	req, err := http.NewRequest(http.MethodGet, "http://example.test", nil)
+	if err != nil {
+		t.Fatalf("NewRequest: %v", err)
+	}
+	req.RemoteAddr = "[::1]:1234"
+
+	addr, ok := requestPeerIP(req)
+	if !ok {
+		t.Fatalf("expected IPv6 peer IP to parse")
+	}
+	if addr != netip.MustParseAddr("::1") {
+		t.Fatalf("addr=%s, want ::1", addr)
+	}
+}
--- a/backend/internal/handler/admin/setting_handler.go
+++ b/backend/internal/handler/admin/setting_handler.go
@@ -36,22 +36,22 @@ func (h *SettingHandler) GetSettings(c *gin.Context) {
 	response.Success(c, dto.SystemSettings{
 		RegistrationEnabled: settings.RegistrationEnabled,
 		EmailVerifyEnabled:  settings.EmailVerifyEnabled,
-		SmtpHost:            settings.SmtpHost,
-		SmtpPort:            settings.SmtpPort,
-		SmtpUsername:        settings.SmtpUsername,
-		SmtpPassword:        settings.SmtpPassword,
-		SmtpFrom:            settings.SmtpFrom,
-		SmtpFromName:        settings.SmtpFromName,
-		SmtpUseTLS:          settings.SmtpUseTLS,
+		SMTPHost:            settings.SMTPHost,
+		SMTPPort:            settings.SMTPPort,
+		SMTPUsername:        settings.SMTPUsername,
+		SMTPPassword:        settings.SMTPPassword,
+		SMTPFrom:            settings.SMTPFrom,
+		SMTPFromName:        settings.SMTPFromName,
+		SMTPUseTLS:          settings.SMTPUseTLS,
 		TurnstileEnabled:    settings.TurnstileEnabled,
 		TurnstileSiteKey:    settings.TurnstileSiteKey,
 		TurnstileSecretKey:  settings.TurnstileSecretKey,
 		SiteName:            settings.SiteName,
 		SiteLogo:            settings.SiteLogo,
 		SiteSubtitle:        settings.SiteSubtitle,
-		ApiBaseUrl:          settings.ApiBaseUrl,
+		APIBaseURL:          settings.APIBaseURL,
 		ContactInfo:         settings.ContactInfo,
-		DocUrl:              settings.DocUrl,
+		DocURL:              settings.DocURL,
 		DefaultConcurrency:  settings.DefaultConcurrency,
 		DefaultBalance:      settings.DefaultBalance,
 	})
@@ -64,13 +64,13 @@ type UpdateSettingsRequest struct {
 	EmailVerifyEnabled  bool `json:"email_verify_enabled"`

 	// 邮件服务设置
-	SmtpHost     string `json:"smtp_host"`
-	SmtpPort     int    `json:"smtp_port"`
-	SmtpUsername string `json:"smtp_username"`
-	SmtpPassword string `json:"smtp_password"`
-	SmtpFrom     string `json:"smtp_from_email"`
-	SmtpFromName string `json:"smtp_from_name"`
-	SmtpUseTLS   bool   `json:"smtp_use_tls"`
+	SMTPHost     string `json:"smtp_host"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPFrom     string `json:"smtp_from_email"`
+	SMTPFromName string `json:"smtp_from_name"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`

 	// Cloudflare Turnstile 设置
 	TurnstileEnabled   bool   `json:"turnstile_enabled"`
@@ -81,9 +81,9 @@ type UpdateSettingsRequest struct {
 	SiteName     string `json:"site_name"`
 	SiteLogo     string `json:"site_logo"`
 	SiteSubtitle string `json:"site_subtitle"`
-	ApiBaseUrl   string `json:"api_base_url"`
+	APIBaseURL   string `json:"api_base_url"`
 	ContactInfo  string `json:"contact_info"`
-	DocUrl       string `json:"doc_url"`
+	DocURL       string `json:"doc_url"`

 	// 默认配置
 	DefaultConcurrency int     `json:"default_concurrency"`
@@ -106,8 +106,8 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 	if req.DefaultBalance < 0 {
 		req.DefaultBalance = 0
 	}
-	if req.SmtpPort <= 0 {
-		req.SmtpPort = 587
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
 	}

 	// Turnstile 参数验证
@@ -143,22 +143,22 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 	settings := &service.SystemSettings{
 		RegistrationEnabled: req.RegistrationEnabled,
 		EmailVerifyEnabled:  req.EmailVerifyEnabled,
-		SmtpHost:            req.SmtpHost,
-		SmtpPort:            req.SmtpPort,
-		SmtpUsername:        req.SmtpUsername,
-		SmtpPassword:        req.SmtpPassword,
-		SmtpFrom:            req.SmtpFrom,
-		SmtpFromName:        req.SmtpFromName,
-		SmtpUseTLS:          req.SmtpUseTLS,
+		SMTPHost:            req.SMTPHost,
+		SMTPPort:            req.SMTPPort,
+		SMTPUsername:        req.SMTPUsername,
+		SMTPPassword:        req.SMTPPassword,
+		SMTPFrom:            req.SMTPFrom,
+		SMTPFromName:        req.SMTPFromName,
+		SMTPUseTLS:          req.SMTPUseTLS,
 		TurnstileEnabled:    req.TurnstileEnabled,
 		TurnstileSiteKey:    req.TurnstileSiteKey,
 		TurnstileSecretKey:  req.TurnstileSecretKey,
 		SiteName:            req.SiteName,
 		SiteLogo:            req.SiteLogo,
 		SiteSubtitle:        req.SiteSubtitle,
-		ApiBaseUrl:          req.ApiBaseUrl,
+		APIBaseURL:          req.APIBaseURL,
 		ContactInfo:         req.ContactInfo,
-		DocUrl:              req.DocUrl,
+		DocURL:              req.DocURL,
 		DefaultConcurrency:  req.DefaultConcurrency,
 		DefaultBalance:      req.DefaultBalance,
 	}
@@ -178,67 +178,67 @@ func (h *SettingHandler) UpdateSettings(c *gin.Context) {
 	response.Success(c, dto.SystemSettings{
 		RegistrationEnabled: updatedSettings.RegistrationEnabled,
 		EmailVerifyEnabled:  updatedSettings.EmailVerifyEnabled,
-		SmtpHost:            updatedSettings.SmtpHost,
-		SmtpPort:            updatedSettings.SmtpPort,
-		SmtpUsername:        updatedSettings.SmtpUsername,
-		SmtpPassword:        updatedSettings.SmtpPassword,
-		SmtpFrom:            updatedSettings.SmtpFrom,
-		SmtpFromName:        updatedSettings.SmtpFromName,
-		SmtpUseTLS:          updatedSettings.SmtpUseTLS,
+		SMTPHost:            updatedSettings.SMTPHost,
+		SMTPPort:            updatedSettings.SMTPPort,
+		SMTPUsername:        updatedSettings.SMTPUsername,
+		SMTPPassword:        updatedSettings.SMTPPassword,
+		SMTPFrom:            updatedSettings.SMTPFrom,
+		SMTPFromName:        updatedSettings.SMTPFromName,
+		SMTPUseTLS:          updatedSettings.SMTPUseTLS,
 		TurnstileEnabled:    updatedSettings.TurnstileEnabled,
 		TurnstileSiteKey:    updatedSettings.TurnstileSiteKey,
 		TurnstileSecretKey:  updatedSettings.TurnstileSecretKey,
 		SiteName:            updatedSettings.SiteName,
 		SiteLogo:            updatedSettings.SiteLogo,
 		SiteSubtitle:        updatedSettings.SiteSubtitle,
-		ApiBaseUrl:          updatedSettings.ApiBaseUrl,
+		APIBaseURL:          updatedSettings.APIBaseURL,
 		ContactInfo:         updatedSettings.ContactInfo,
-		DocUrl:              updatedSettings.DocUrl,
+		DocURL:              updatedSettings.DocURL,
 		DefaultConcurrency:  updatedSettings.DefaultConcurrency,
 		DefaultBalance:      updatedSettings.DefaultBalance,
 	})
 }

-// TestSmtpRequest 测试SMTP连接请求
-type TestSmtpRequest struct {
-	SmtpHost     string `json:"smtp_host" binding:"required"`
-	SmtpPort     int    `json:"smtp_port"`
-	SmtpUsername string `json:"smtp_username"`
-	SmtpPassword string `json:"smtp_password"`
-	SmtpUseTLS   bool   `json:"smtp_use_tls"`
+// TestSMTPRequest 测试SMTP连接请求
+type TestSMTPRequest struct {
+	SMTPHost     string `json:"smtp_host" binding:"required"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`
 }

-// TestSmtpConnection 测试SMTP连接
+// TestSMTPConnection 测试SMTP连接
 // POST /api/v1/admin/settings/test-smtp
-func (h *SettingHandler) TestSmtpConnection(c *gin.Context) {
-	var req TestSmtpRequest
+func (h *SettingHandler) TestSMTPConnection(c *gin.Context) {
+	var req TestSMTPRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		response.BadRequest(c, "Invalid request: "+err.Error())
 		return
 	}

-	if req.SmtpPort <= 0 {
-		req.SmtpPort = 587
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
 	}

 	// 如果未提供密码，从数据库获取已保存的密码
-	password := req.SmtpPassword
+	password := req.SMTPPassword
 	if password == "" {
-		savedConfig, err := h.emailService.GetSmtpConfig(c.Request.Context())
+		savedConfig, err := h.emailService.GetSMTPConfig(c.Request.Context())
 		if err == nil && savedConfig != nil {
 			password = savedConfig.Password
 		}
 	}

-	config := &service.SmtpConfig{
-		Host:     req.SmtpHost,
-		Port:     req.SmtpPort,
-		Username: req.SmtpUsername,
+	config := &service.SMTPConfig{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
 		Password: password,
-		UseTLS:   req.SmtpUseTLS,
+		UseTLS:   req.SMTPUseTLS,
 	}

-	err := h.emailService.TestSmtpConnectionWithConfig(config)
+	err := h.emailService.TestSMTPConnectionWithConfig(config)
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
@@ -250,13 +250,13 @@ func (h *SettingHandler) TestSmtpConnection(c *gin.Context) {
 // SendTestEmailRequest 发送测试邮件请求
 type SendTestEmailRequest struct {
 	Email        string `json:"email" binding:"required,email"`
-	SmtpHost     string `json:"smtp_host" binding:"required"`
-	SmtpPort     int    `json:"smtp_port"`
-	SmtpUsername string `json:"smtp_username"`
-	SmtpPassword string `json:"smtp_password"`
-	SmtpFrom     string `json:"smtp_from_email"`
-	SmtpFromName string `json:"smtp_from_name"`
-	SmtpUseTLS   bool   `json:"smtp_use_tls"`
+	SMTPHost     string `json:"smtp_host" binding:"required"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password"`
+	SMTPFrom     string `json:"smtp_from_email"`
+	SMTPFromName string `json:"smtp_from_name"`
+	SMTPUseTLS   bool   `json:"smtp_use_tls"`
 }

 // SendTestEmail 发送测试邮件
@@ -268,27 +268,27 @@ func (h *SettingHandler) SendTestEmail(c *gin.Context) {
 		return
 	}

-	if req.SmtpPort <= 0 {
-		req.SmtpPort = 587
+	if req.SMTPPort <= 0 {
+		req.SMTPPort = 587
 	}

 	// 如果未提供密码，从数据库获取已保存的密码
-	password := req.SmtpPassword
+	password := req.SMTPPassword
 	if password == "" {
-		savedConfig, err := h.emailService.GetSmtpConfig(c.Request.Context())
+		savedConfig, err := h.emailService.GetSMTPConfig(c.Request.Context())
 		if err == nil && savedConfig != nil {
 			password = savedConfig.Password
 		}
 	}

-	config := &service.SmtpConfig{
-		Host:     req.SmtpHost,
-		Port:     req.SmtpPort,
-		Username: req.SmtpUsername,
+	config := &service.SMTPConfig{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
 		Password: password,
-		From:     req.SmtpFrom,
-		FromName: req.SmtpFromName,
-		UseTLS:   req.SmtpUseTLS,
+		From:     req.SMTPFrom,
+		FromName: req.SMTPFromName,
+		UseTLS:   req.SMTPUseTLS,
 	}

 	siteName := h.settingService.GetSiteName(c.Request.Context())
@@ -333,10 +333,10 @@ func (h *SettingHandler) SendTestEmail(c *gin.Context) {
 	response.Success(c, gin.H{"message": "Test email sent successfully"})
 }

-// GetAdminApiKey 获取管理员 API Key 状态
+// GetAdminAPIKey 获取管理员 API Key 状态
 // GET /api/v1/admin/settings/admin-api-key
-func (h *SettingHandler) GetAdminApiKey(c *gin.Context) {
-	maskedKey, exists, err := h.settingService.GetAdminApiKeyStatus(c.Request.Context())
+func (h *SettingHandler) GetAdminAPIKey(c *gin.Context) {
+	maskedKey, exists, err := h.settingService.GetAdminAPIKeyStatus(c.Request.Context())
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
@@ -348,10 +348,10 @@ func (h *SettingHandler) GetAdminApiKey(c *gin.Context) {
 	})
 }

-// RegenerateAdminApiKey 生成/重新生成管理员 API Key
+// RegenerateAdminAPIKey 生成/重新生成管理员 API Key
 // POST /api/v1/admin/settings/admin-api-key/regenerate
-func (h *SettingHandler) RegenerateAdminApiKey(c *gin.Context) {
-	key, err := h.settingService.GenerateAdminApiKey(c.Request.Context())
+func (h *SettingHandler) RegenerateAdminAPIKey(c *gin.Context) {
+	key, err := h.settingService.GenerateAdminAPIKey(c.Request.Context())
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
@@ -362,10 +362,10 @@ func (h *SettingHandler) RegenerateAdminApiKey(c *gin.Context) {
 	})
 }

-// DeleteAdminApiKey 删除管理员 API Key
+// DeleteAdminAPIKey 删除管理员 API Key
 // DELETE /api/v1/admin/settings/admin-api-key
-func (h *SettingHandler) DeleteAdminApiKey(c *gin.Context) {
-	if err := h.settingService.DeleteAdminApiKey(c.Request.Context()); err != nil {
+func (h *SettingHandler) DeleteAdminAPIKey(c *gin.Context) {
+	if err := h.settingService.DeleteAdminAPIKey(c.Request.Context()); err != nil {
 		response.ErrorFrom(c, err)
 		return
 	}
--- a/backend/internal/handler/admin/usage_handler.go
+++ b/backend/internal/handler/admin/usage_handler.go
@@ -17,14 +17,14 @@ import (
 // UsageHandler handles admin usage-related requests
 type UsageHandler struct {
 	usageService  *service.UsageService
-	apiKeyService *service.ApiKeyService
+	apiKeyService *service.APIKeyService
 	adminService  service.AdminService
 }

 // NewUsageHandler creates a new admin usage handler
 func NewUsageHandler(
 	usageService *service.UsageService,
-	apiKeyService *service.ApiKeyService,
+	apiKeyService *service.APIKeyService,
 	adminService service.AdminService,
 ) *UsageHandler {
 	return &UsageHandler{
@@ -125,7 +125,7 @@ func (h *UsageHandler) List(c *gin.Context) {
 	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	filters := usagestats.UsageLogFilters{
 		UserID:      userID,
-		ApiKeyID:    apiKeyID,
+		APIKeyID:    apiKeyID,
 		AccountID:   accountID,
 		GroupID:     groupID,
 		Model:       model,
@@ -207,7 +207,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 	}

 	if apiKeyID > 0 {
-		stats, err := h.usageService.GetStatsByApiKey(c.Request.Context(), apiKeyID, startTime, endTime)
+		stats, err := h.usageService.GetStatsByAPIKey(c.Request.Context(), apiKeyID, startTime, endTime)
 		if err != nil {
 			response.ErrorFrom(c, err)
 			return
@@ -269,9 +269,9 @@ func (h *UsageHandler) SearchUsers(c *gin.Context) {
 	response.Success(c, result)
 }

-// SearchApiKeys handles searching API keys by user
+// SearchAPIKeys handles searching API keys by user
 // GET /api/v1/admin/usage/search-api-keys
-func (h *UsageHandler) SearchApiKeys(c *gin.Context) {
+func (h *UsageHandler) SearchAPIKeys(c *gin.Context) {
 	userIDStr := c.Query("user_id")
 	keyword := c.Query("q")

@@ -285,22 +285,22 @@ func (h *UsageHandler) SearchApiKeys(c *gin.Context) {
 		userID = id
 	}

-	keys, err := h.apiKeyService.SearchApiKeys(c.Request.Context(), userID, keyword, 30)
+	keys, err := h.apiKeyService.SearchAPIKeys(c.Request.Context(), userID, keyword, 30)
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
 	}

 	// Return simplified API key list (only id and name)
-	type SimpleApiKey struct {
+	type SimpleAPIKey struct {
 		ID     int64  `json:"id"`
 		Name   string `json:"name"`
 		UserID int64  `json:"user_id"`
 	}

-	result := make([]SimpleApiKey, len(keys))
+	result := make([]SimpleAPIKey, len(keys))
 	for i, k := range keys {
-		result[i] = SimpleApiKey{
+		result[i] = SimpleAPIKey{
 			ID:     k.ID,
 			Name:   k.Name,
 			UserID: k.UserID,
--- a/backend/internal/handler/admin/user_handler.go
+++ b/backend/internal/handler/admin/user_handler.go
@@ -243,9 +243,9 @@ func (h *UserHandler) GetUserAPIKeys(c *gin.Context) {
 		return
 	}

-	out := make([]dto.ApiKey, 0, len(keys))
+	out := make([]dto.APIKey, 0, len(keys))
 	for i := range keys {
-		out = append(out, *dto.ApiKeyFromService(&keys[i]))
+		out = append(out, *dto.APIKeyFromService(&keys[i]))
 	}
 	response.Paginated(c, out, total, page, pageSize)
 }
--- a/backend/internal/handler/api_key_handler.go
+++ b/backend/internal/handler/api_key_handler.go
@@ -14,11 +14,11 @@ import (

 // APIKeyHandler handles API key-related requests
 type APIKeyHandler struct {
-	apiKeyService *service.ApiKeyService
+	apiKeyService *service.APIKeyService
 }

 // NewAPIKeyHandler creates a new APIKeyHandler
-func NewAPIKeyHandler(apiKeyService *service.ApiKeyService) *APIKeyHandler {
+func NewAPIKeyHandler(apiKeyService *service.APIKeyService) *APIKeyHandler {
 	return &APIKeyHandler{
 		apiKeyService: apiKeyService,
 	}
@@ -56,9 +56,9 @@ func (h *APIKeyHandler) List(c *gin.Context) {
 		return
 	}

-	out := make([]dto.ApiKey, 0, len(keys))
+	out := make([]dto.APIKey, 0, len(keys))
 	for i := range keys {
-		out = append(out, *dto.ApiKeyFromService(&keys[i]))
+		out = append(out, *dto.APIKeyFromService(&keys[i]))
 	}
 	response.Paginated(c, out, result.Total, page, pageSize)
 }
@@ -90,7 +90,7 @@ func (h *APIKeyHandler) GetByID(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.ApiKeyFromService(key))
+	response.Success(c, dto.APIKeyFromService(key))
 }

 // Create handles creating a new API key
@@ -108,7 +108,7 @@ func (h *APIKeyHandler) Create(c *gin.Context) {
 		return
 	}

-	svcReq := service.CreateApiKeyRequest{
+	svcReq := service.CreateAPIKeyRequest{
 		Name:      req.Name,
 		GroupID:   req.GroupID,
 		CustomKey: req.CustomKey,
@@ -119,7 +119,7 @@ func (h *APIKeyHandler) Create(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.ApiKeyFromService(key))
+	response.Success(c, dto.APIKeyFromService(key))
 }

 // Update handles updating an API key
@@ -143,7 +143,7 @@ func (h *APIKeyHandler) Update(c *gin.Context) {
 		return
 	}

-	svcReq := service.UpdateApiKeyRequest{}
+	svcReq := service.UpdateAPIKeyRequest{}
 	if req.Name != "" {
 		svcReq.Name = &req.Name
 	}
@@ -158,7 +158,7 @@ func (h *APIKeyHandler) Update(c *gin.Context) {
 		return
 	}

-	response.Success(c, dto.ApiKeyFromService(key))
+	response.Success(c, dto.APIKeyFromService(key))
 }

 // Delete handles deleting an API key
--- a/backend/internal/handler/dto/mappers.go
+++ b/backend/internal/handler/dto/mappers.go
@@ -1,3 +1,4 @@
+// Package dto provides mapping utilities for converting between service layer and HTTP handler DTOs.
 package dto

 import "github.com/Wei-Shaw/sub2api/internal/service"
@@ -26,11 +27,11 @@ func UserFromService(u *service.User) *User {
 		return nil
 	}
 	out := UserFromServiceShallow(u)
-	if len(u.ApiKeys) > 0 {
-		out.ApiKeys = make([]ApiKey, 0, len(u.ApiKeys))
-		for i := range u.ApiKeys {
-			k := u.ApiKeys[i]
-			out.ApiKeys = append(out.ApiKeys, *ApiKeyFromService(&k))
+	if len(u.APIKeys) > 0 {
+		out.APIKeys = make([]APIKey, 0, len(u.APIKeys))
+		for i := range u.APIKeys {
+			k := u.APIKeys[i]
+			out.APIKeys = append(out.APIKeys, *APIKeyFromService(&k))
 		}
 	}
 	if len(u.Subscriptions) > 0 {
@@ -43,11 +44,11 @@ func UserFromService(u *service.User) *User {
 	return out
 }

-func ApiKeyFromService(k *service.ApiKey) *ApiKey {
+func APIKeyFromService(k *service.APIKey) *APIKey {
 	if k == nil {
 		return nil
 	}
-	return &ApiKey{
+	return &APIKey{
 		ID:        k.ID,
 		UserID:    k.UserID,
 		Key:       k.Key,
@@ -220,7 +221,7 @@ func UsageLogFromService(l *service.UsageLog) *UsageLog {
 	return &UsageLog{
 		ID:                    l.ID,
 		UserID:                l.UserID,
-		ApiKeyID:              l.ApiKeyID,
+		APIKeyID:              l.APIKeyID,
 		AccountID:             l.AccountID,
 		RequestID:             l.RequestID,
 		Model:                 l.Model,
@@ -245,7 +246,7 @@ func UsageLogFromService(l *service.UsageLog) *UsageLog {
 		FirstTokenMs:          l.FirstTokenMs,
 		CreatedAt:             l.CreatedAt,
 		User:                  UserFromServiceShallow(l.User),
-		ApiKey:                ApiKeyFromService(l.ApiKey),
+		APIKey:                APIKeyFromService(l.APIKey),
 		Account:               AccountFromService(l.Account),
 		Group:                 GroupFromServiceShallow(l.Group),
 		Subscription:          UserSubscriptionFromService(l.Subscription),
--- a/backend/internal/handler/dto/settings.go
+++ b/backend/internal/handler/dto/settings.go
@@ -5,13 +5,13 @@ type SystemSettings struct {
 	RegistrationEnabled bool `json:"registration_enabled"`
 	EmailVerifyEnabled  bool `json:"email_verify_enabled"`

-	SmtpHost     string `json:"smtp_host"`
-	SmtpPort     int    `json:"smtp_port"`
-	SmtpUsername string `json:"smtp_username"`
-	SmtpPassword string `json:"smtp_password,omitempty"`
-	SmtpFrom     string `json:"smtp_from_email"`
-	SmtpFromName string `json:"smtp_from_name"`
-	SmtpUseTLS   bool   `json:"smtp_use_tls"`
+	SMTPHost     string `json:"smtp_host"`
+	SMTPPort     int    `json:"smtp_port"`
+	SMTPUsername string `json:"smtp_username"`
+	SMTPPassword string `json:"smtp_password,omitempty"`
+	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"`
@@ -20,9 +20,9 @@ type SystemSettings struct {
 	SiteName     string `json:"site_name"`
 	SiteLogo     string `json:"site_logo"`
 	SiteSubtitle string `json:"site_subtitle"`
-	ApiBaseUrl   string `json:"api_base_url"`
+	APIBaseURL   string `json:"api_base_url"`
 	ContactInfo  string `json:"contact_info"`
-	DocUrl       string `json:"doc_url"`
+	DocURL       string `json:"doc_url"`

 	DefaultConcurrency int     `json:"default_concurrency"`
 	DefaultBalance     float64 `json:"default_balance"`
@@ -36,8 +36,8 @@ type PublicSettings struct {
 	SiteName            string `json:"site_name"`
 	SiteLogo            string `json:"site_logo"`
 	SiteSubtitle        string `json:"site_subtitle"`
-	ApiBaseUrl          string `json:"api_base_url"`
+	APIBaseURL          string `json:"api_base_url"`
 	ContactInfo         string `json:"contact_info"`
-	DocUrl              string `json:"doc_url"`
+	DocURL              string `json:"doc_url"`
 	Version             string `json:"version"`
 }
--- a/backend/internal/handler/dto/types.go
+++ b/backend/internal/handler/dto/types.go
@@ -15,11 +15,11 @@ type User struct {
 	CreatedAt     time.Time `json:"created_at"`
 	UpdatedAt     time.Time `json:"updated_at"`

-	ApiKeys       []ApiKey           `json:"api_keys,omitempty"`
+	APIKeys       []APIKey           `json:"api_keys,omitempty"`
 	Subscriptions []UserSubscription `json:"subscriptions,omitempty"`
 }

-type ApiKey struct {
+type APIKey struct {
 	ID        int64     `json:"id"`
 	UserID    int64     `json:"user_id"`
 	Key       string    `json:"key"`
@@ -136,7 +136,7 @@ type RedeemCode struct {
 type UsageLog struct {
 	ID        int64  `json:"id"`
 	UserID    int64  `json:"user_id"`
-	ApiKeyID  int64  `json:"api_key_id"`
+	APIKeyID  int64  `json:"api_key_id"`
 	AccountID int64  `json:"account_id"`
 	RequestID string `json:"request_id"`
 	Model     string `json:"model"`
@@ -168,7 +168,7 @@ type UsageLog struct {
 	CreatedAt time.Time `json:"created_at"`

 	User         *User             `json:"user,omitempty"`
-	ApiKey       *ApiKey           `json:"api_key,omitempty"`
+	APIKey       *APIKey           `json:"api_key,omitempty"`
 	Account      *Account          `json:"account,omitempty"`
 	Group        *Group            `json:"group,omitempty"`
 	Subscription *UserSubscription `json:"subscription,omitempty"`
--- a/backend/internal/handler/gateway_handler.go
+++ b/backend/internal/handler/gateway_handler.go
@@ -1,3 +1,5 @@
+// Package handler provides HTTP request handlers for the API gateway.
+// It handles authentication, request routing, concurrency control, and billing validation.
 package handler

 import (
@@ -27,6 +29,7 @@ type GatewayHandler struct {
 	userService               *service.UserService
 	billingCacheService       *service.BillingCacheService
 	concurrencyHelper         *ConcurrencyHelper
+	opsService                *service.OpsService
 }

 // NewGatewayHandler creates a new GatewayHandler
@@ -37,6 +40,7 @@ func NewGatewayHandler(
 	userService *service.UserService,
 	concurrencyService *service.ConcurrencyService,
 	billingCacheService *service.BillingCacheService,
+	opsService *service.OpsService,
 ) *GatewayHandler {
 	return &GatewayHandler{
 		gatewayService:            gatewayService,
@@ -45,14 +49,15 @@ func NewGatewayHandler(
 		userService:               userService,
 		billingCacheService:       billingCacheService,
 		concurrencyHelper:         NewConcurrencyHelper(concurrencyService, SSEPingFormatClaude),
+		opsService:                opsService,
 	}
 }

 // Messages handles Claude API compatible messages endpoint
 // POST /v1/messages
 func (h *GatewayHandler) Messages(c *gin.Context) {
-	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
-	apiKey, ok := middleware2.GetApiKeyFromContext(c)
+	// 从context获取apiKey和user（APIKeyAuth中间件已设置）
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
@@ -87,6 +92,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 	}
 	reqModel := parsedReq.Model
 	reqStream := parsedReq.Stream
+	setOpsRequestContext(c, reqModel, reqStream)

 	// 验证 model 必填
 	if reqModel == "" {
@@ -258,7 +264,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 				defer cancel()
 				if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
 					Result:       result,
-					ApiKey:       apiKey,
+					APIKey:       apiKey,
 					User:         apiKey.User,
 					Account:      usedAccount,
 					Subscription: subscription,
@@ -382,7 +388,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 			defer cancel()
 			if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
 				Result:       result,
-				ApiKey:       apiKey,
+				APIKey:       apiKey,
 				User:         apiKey.User,
 				Account:      usedAccount,
 				Subscription: subscription,
@@ -399,7 +405,7 @@ func (h *GatewayHandler) Messages(c *gin.Context) {
 // Returns models based on account configurations (model_mapping whitelist)
 // Falls back to default models if no whitelist is configured
 func (h *GatewayHandler) Models(c *gin.Context) {
-	apiKey, _ := middleware2.GetApiKeyFromContext(c)
+	apiKey, _ := middleware2.GetAPIKeyFromContext(c)

 	var groupID *int64
 	var platform string
@@ -448,7 +454,7 @@ func (h *GatewayHandler) Models(c *gin.Context) {
 // Usage handles getting account balance for CC Switch integration
 // GET /v1/usage
 func (h *GatewayHandler) Usage(c *gin.Context) {
-	apiKey, ok := middleware2.GetApiKeyFromContext(c)
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
@@ -573,6 +579,7 @@ func (h *GatewayHandler) mapUpstreamError(statusCode int) (int, string, string)
 // handleStreamingAwareError handles errors that may occur after streaming has started
 func (h *GatewayHandler) handleStreamingAwareError(c *gin.Context, status int, errType, message string, streamStarted bool) {
 	if streamStarted {
+		recordOpsError(c, h.opsService, status, errType, message, "")
 		// Stream already started, send error as SSE event then close
 		flusher, ok := c.Writer.(http.Flusher)
 		if ok {
@@ -604,6 +611,7 @@ func (h *GatewayHandler) handleStreamingAwareError(c *gin.Context, status int, e

 // errorResponse 返回Claude API格式的错误响应
 func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, message string) {
+	recordOpsError(c, h.opsService, status, errType, message, "")
 	c.JSON(status, gin.H{
 		"type": "error",
 		"error": gin.H{
@@ -617,8 +625,8 @@ func (h *GatewayHandler) errorResponse(c *gin.Context, status int, errType, mess
 // POST /v1/messages/count_tokens
 // 特点：校验订阅/余额，但不计算并发、不记录使用量
 func (h *GatewayHandler) CountTokens(c *gin.Context) {
-	// 从context获取apiKey和user（ApiKeyAuth中间件已设置）
-	apiKey, ok := middleware2.GetApiKeyFromContext(c)
+	// 从context获取apiKey和user（APIKeyAuth中间件已设置）
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
--- a/backend/internal/handler/gemini_v1beta_handler.go
+++ b/backend/internal/handler/gemini_v1beta_handler.go
@@ -20,7 +20,7 @@ import (
 // GeminiV1BetaListModels proxies:
 // GET /v1beta/models
 func (h *GatewayHandler) GeminiV1BetaListModels(c *gin.Context) {
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
 	if !ok || apiKey == nil {
 		googleError(c, http.StatusUnauthorized, "Invalid API key")
 		return
@@ -66,7 +66,7 @@ func (h *GatewayHandler) GeminiV1BetaListModels(c *gin.Context) {
 // GeminiV1BetaGetModel proxies:
 // GET /v1beta/models/{model}
 func (h *GatewayHandler) GeminiV1BetaGetModel(c *gin.Context) {
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
 	if !ok || apiKey == nil {
 		googleError(c, http.StatusUnauthorized, "Invalid API key")
 		return
@@ -119,7 +119,7 @@ func (h *GatewayHandler) GeminiV1BetaGetModel(c *gin.Context) {
 // POST /v1beta/models/{model}:generateContent
 // POST /v1beta/models/{model}:streamGenerateContent?alt=sse
 func (h *GatewayHandler) GeminiV1BetaModels(c *gin.Context) {
-	apiKey, ok := middleware.GetApiKeyFromContext(c)
+	apiKey, ok := middleware.GetAPIKeyFromContext(c)
 	if !ok || apiKey == nil {
 		googleError(c, http.StatusUnauthorized, "Invalid API key")
 		return
@@ -298,7 +298,7 @@ func (h *GatewayHandler) GeminiV1BetaModels(c *gin.Context) {
 			defer cancel()
 			if err := h.gatewayService.RecordUsage(ctx, &service.RecordUsageInput{
 				Result:       result,
-				ApiKey:       apiKey,
+				APIKey:       apiKey,
 				User:         apiKey.User,
 				Account:      usedAccount,
 				Subscription: subscription,
--- a/backend/internal/handler/handler.go
+++ b/backend/internal/handler/handler.go
@@ -7,6 +7,7 @@ import (
 // AdminHandlers contains all admin-related HTTP handlers
 type AdminHandlers struct {
 	Dashboard        *admin.DashboardHandler
+	Ops              *admin.OpsHandler
 	User             *admin.UserHandler
 	Group            *admin.GroupHandler
 	Account          *admin.AccountHandler
--- a/backend/internal/handler/openai_gateway_handler.go
+++ b/backend/internal/handler/openai_gateway_handler.go
@@ -22,6 +22,7 @@ type OpenAIGatewayHandler struct {
 	gatewayService      *service.OpenAIGatewayService
 	billingCacheService *service.BillingCacheService
 	concurrencyHelper   *ConcurrencyHelper
+	opsService          *service.OpsService
 }

 // NewOpenAIGatewayHandler creates a new OpenAIGatewayHandler
@@ -29,19 +30,21 @@ func NewOpenAIGatewayHandler(
 	gatewayService *service.OpenAIGatewayService,
 	concurrencyService *service.ConcurrencyService,
 	billingCacheService *service.BillingCacheService,
+	opsService *service.OpsService,
 ) *OpenAIGatewayHandler {
 	return &OpenAIGatewayHandler{
 		gatewayService:      gatewayService,
 		billingCacheService: billingCacheService,
 		concurrencyHelper:   NewConcurrencyHelper(concurrencyService, SSEPingFormatNone),
+		opsService:          opsService,
 	}
 }

 // Responses handles OpenAI Responses API endpoint
 // POST /openai/v1/responses
 func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
-	// Get apiKey and user from context (set by ApiKeyAuth middleware)
-	apiKey, ok := middleware2.GetApiKeyFromContext(c)
+	// Get apiKey and user from context (set by APIKeyAuth middleware)
+	apiKey, ok := middleware2.GetAPIKeyFromContext(c)
 	if !ok {
 		h.errorResponse(c, http.StatusUnauthorized, "authentication_error", "Invalid API key")
 		return
@@ -79,6 +82,7 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 	// Extract model and stream
 	reqModel, _ := reqBody["model"].(string)
 	reqStream, _ := reqBody["stream"].(bool)
+	setOpsRequestContext(c, reqModel, reqStream)

 	// 验证 model 必填
 	if reqModel == "" {
@@ -235,7 +239,7 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 			defer cancel()
 			if err := h.gatewayService.RecordUsage(ctx, &service.OpenAIRecordUsageInput{
 				Result:       result,
-				ApiKey:       apiKey,
+				APIKey:       apiKey,
 				User:         apiKey.User,
 				Account:      usedAccount,
 				Subscription: subscription,
@@ -278,6 +282,7 @@ func (h *OpenAIGatewayHandler) mapUpstreamError(statusCode int) (int, string, st
 // handleStreamingAwareError handles errors that may occur after streaming has started
 func (h *OpenAIGatewayHandler) handleStreamingAwareError(c *gin.Context, status int, errType, message string, streamStarted bool) {
 	if streamStarted {
+		recordOpsError(c, h.opsService, status, errType, message, service.PlatformOpenAI)
 		// Stream already started, send error as SSE event then close
 		flusher, ok := c.Writer.(http.Flusher)
 		if ok {
@@ -297,6 +302,7 @@ func (h *OpenAIGatewayHandler) handleStreamingAwareError(c *gin.Context, status

 // errorResponse returns OpenAI API format error response
 func (h *OpenAIGatewayHandler) errorResponse(c *gin.Context, status int, errType, message string) {
+	recordOpsError(c, h.opsService, status, errType, message, service.PlatformOpenAI)
 	c.JSON(status, gin.H{
 		"error": gin.H{
 			"type":    errType,
--- a/backend/internal/handler/ops_error_logger.go
+++ b/backend/internal/handler/ops_error_logger.go
@@ -0,0 +1,166 @@
+package handler
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+
+	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
+	"github.com/Wei-Shaw/sub2api/internal/service"
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	opsModelKey  = "ops_model"
+	opsStreamKey = "ops_stream"
+)
+
+const (
+	opsErrorLogWorkerCount = 10
+	opsErrorLogQueueSize   = 256
+	opsErrorLogTimeout     = 2 * time.Second
+)
+
+type opsErrorLogJob struct {
+	ops   *service.OpsService
+	entry *service.OpsErrorLog
+}
+
+var (
+	opsErrorLogOnce  sync.Once
+	opsErrorLogQueue chan opsErrorLogJob
+)
+
+func startOpsErrorLogWorkers() {
+	opsErrorLogQueue = make(chan opsErrorLogJob, opsErrorLogQueueSize)
+	for i := 0; i < opsErrorLogWorkerCount; i++ {
+		go func() {
+			for job := range opsErrorLogQueue {
+				if job.ops == nil || job.entry == nil {
+					continue
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), opsErrorLogTimeout)
+				_ = job.ops.RecordError(ctx, job.entry)
+				cancel()
+			}
+		}()
+	}
+}
+
+func enqueueOpsErrorLog(ops *service.OpsService, entry *service.OpsErrorLog) {
+	if ops == nil || entry == nil {
+		return
+	}
+
+	opsErrorLogOnce.Do(startOpsErrorLogWorkers)
+
+	select {
+	case opsErrorLogQueue <- opsErrorLogJob{ops: ops, entry: entry}:
+	default:
+		// Queue is full; drop to avoid blocking request handling.
+	}
+}
+
+func setOpsRequestContext(c *gin.Context, model string, stream bool) {
+	c.Set(opsModelKey, model)
+	c.Set(opsStreamKey, stream)
+}
+
+func recordOpsError(c *gin.Context, ops *service.OpsService, status int, errType, message, fallbackPlatform string) {
+	if ops == nil || c == nil {
+		return
+	}
+
+	model, _ := c.Get(opsModelKey)
+	stream, _ := c.Get(opsStreamKey)
+
+	var modelName string
+	if m, ok := model.(string); ok {
+		modelName = m
+	}
+	streaming, _ := stream.(bool)
+
+	apiKey, _ := middleware2.GetAPIKeyFromContext(c)
+
+	logEntry := &service.OpsErrorLog{
+		Phase:      classifyOpsPhase(errType, message),
+		Type:       errType,
+		Severity:   classifyOpsSeverity(errType, status),
+		StatusCode: status,
+		Platform:   resolveOpsPlatform(apiKey, fallbackPlatform),
+		Model:      modelName,
+		RequestID:  c.Writer.Header().Get("x-request-id"),
+		Message:    message,
+		ClientIP:   c.ClientIP(),
+		RequestPath: func() string {
+			if c.Request != nil && c.Request.URL != nil {
+				return c.Request.URL.Path
+			}
+			return ""
+		}(),
+		Stream: streaming,
+	}
+
+	if apiKey != nil {
+		logEntry.APIKeyID = &apiKey.ID
+		if apiKey.User != nil {
+			logEntry.UserID = &apiKey.User.ID
+		}
+		if apiKey.GroupID != nil {
+			logEntry.GroupID = apiKey.GroupID
+		}
+	}
+
+	enqueueOpsErrorLog(ops, logEntry)
+}
+
+func resolveOpsPlatform(apiKey *service.APIKey, fallback string) string {
+	if apiKey != nil && apiKey.Group != nil && apiKey.Group.Platform != "" {
+		return apiKey.Group.Platform
+	}
+	return fallback
+}
+
+func classifyOpsPhase(errType, message string) string {
+	msg := strings.ToLower(message)
+	switch errType {
+	case "authentication_error":
+		return "auth"
+	case "billing_error", "subscription_error":
+		return "billing"
+	case "rate_limit_error":
+		if strings.Contains(msg, "concurrency") || strings.Contains(msg, "pending") {
+			return "concurrency"
+		}
+		return "upstream"
+	case "invalid_request_error":
+		return "response"
+	case "upstream_error", "overloaded_error":
+		return "upstream"
+	case "api_error":
+		if strings.Contains(msg, "no available accounts") {
+			return "scheduling"
+		}
+		return "internal"
+	default:
+		return "internal"
+	}
+}
+
+func classifyOpsSeverity(errType string, status int) string {
+	switch errType {
+	case "invalid_request_error", "authentication_error", "billing_error", "subscription_error":
+		return "P3"
+	}
+	if status >= 500 {
+		return "P1"
+	}
+	if status == 429 {
+		return "P1"
+	}
+	if status >= 400 {
+		return "P2"
+	}
+	return "P3"
+}
--- a/backend/internal/handler/setting_handler.go
+++ b/backend/internal/handler/setting_handler.go
@@ -39,9 +39,9 @@ func (h *SettingHandler) GetPublicSettings(c *gin.Context) {
 		SiteName:            settings.SiteName,
 		SiteLogo:            settings.SiteLogo,
 		SiteSubtitle:        settings.SiteSubtitle,
-		ApiBaseUrl:          settings.ApiBaseUrl,
+		APIBaseURL:          settings.APIBaseURL,
 		ContactInfo:         settings.ContactInfo,
-		DocUrl:              settings.DocUrl,
+		DocURL:              settings.DocURL,
 		Version:             h.version,
 	})
 }
--- a/backend/internal/handler/usage_handler.go
+++ b/backend/internal/handler/usage_handler.go
@@ -18,11 +18,11 @@ import (
 // UsageHandler handles usage-related requests
 type UsageHandler struct {
 	usageService  *service.UsageService
-	apiKeyService *service.ApiKeyService
+	apiKeyService *service.APIKeyService
 }

 // NewUsageHandler creates a new UsageHandler
-func NewUsageHandler(usageService *service.UsageService, apiKeyService *service.ApiKeyService) *UsageHandler {
+func NewUsageHandler(usageService *service.UsageService, apiKeyService *service.APIKeyService) *UsageHandler {
 	return &UsageHandler{
 		usageService:  usageService,
 		apiKeyService: apiKeyService,
@@ -111,7 +111,7 @@ func (h *UsageHandler) List(c *gin.Context) {
 	params := pagination.PaginationParams{Page: page, PageSize: pageSize}
 	filters := usagestats.UsageLogFilters{
 		UserID:      subject.UserID, // Always filter by current user for security
-		ApiKeyID:    apiKeyID,
+		APIKeyID:    apiKeyID,
 		Model:       model,
 		Stream:      stream,
 		BillingType: billingType,
@@ -235,7 +235,7 @@ func (h *UsageHandler) Stats(c *gin.Context) {
 	var stats *service.UsageStats
 	var err error
 	if apiKeyID > 0 {
-		stats, err = h.usageService.GetStatsByApiKey(c.Request.Context(), apiKeyID, startTime, endTime)
+		stats, err = h.usageService.GetStatsByAPIKey(c.Request.Context(), apiKeyID, startTime, endTime)
 	} else {
 		stats, err = h.usageService.GetStatsByUser(c.Request.Context(), subject.UserID, startTime, endTime)
 	}
@@ -346,49 +346,49 @@ func (h *UsageHandler) DashboardModels(c *gin.Context) {
 	})
 }

-// BatchApiKeysUsageRequest represents the request for batch API keys usage
-type BatchApiKeysUsageRequest struct {
-	ApiKeyIDs []int64 `json:"api_key_ids" binding:"required"`
+// BatchAPIKeysUsageRequest represents the request for batch API keys usage
+type BatchAPIKeysUsageRequest struct {
+	APIKeyIDs []int64 `json:"api_key_ids" binding:"required"`
 }

-// DashboardApiKeysUsage handles getting usage stats for user's own API keys
+// DashboardAPIKeysUsage handles getting usage stats for user's own API keys
 // POST /api/v1/usage/dashboard/api-keys-usage
-func (h *UsageHandler) DashboardApiKeysUsage(c *gin.Context) {
+func (h *UsageHandler) DashboardAPIKeysUsage(c *gin.Context) {
 	subject, ok := middleware2.GetAuthSubjectFromContext(c)
 	if !ok {
 		response.Unauthorized(c, "User not authenticated")
 		return
 	}

-	var req BatchApiKeysUsageRequest
+	var req BatchAPIKeysUsageRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		response.BadRequest(c, "Invalid request: "+err.Error())
 		return
 	}

-	if len(req.ApiKeyIDs) == 0 {
+	if len(req.APIKeyIDs) == 0 {
 		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}

 	// Limit the number of API key IDs to prevent SQL parameter overflow
-	if len(req.ApiKeyIDs) > 100 {
+	if len(req.APIKeyIDs) > 100 {
 		response.BadRequest(c, "Too many API key IDs (maximum 100 allowed)")
 		return
 	}

-	validApiKeyIDs, err := h.apiKeyService.VerifyOwnership(c.Request.Context(), subject.UserID, req.ApiKeyIDs)
+	validAPIKeyIDs, err := h.apiKeyService.VerifyOwnership(c.Request.Context(), subject.UserID, req.APIKeyIDs)
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
 	}

-	if len(validApiKeyIDs) == 0 {
+	if len(validAPIKeyIDs) == 0 {
 		response.Success(c, gin.H{"stats": map[string]any{}})
 		return
 	}

-	stats, err := h.usageService.GetBatchApiKeyUsageStats(c.Request.Context(), validApiKeyIDs)
+	stats, err := h.usageService.GetBatchAPIKeyUsageStats(c.Request.Context(), validAPIKeyIDs)
 	if err != nil {
 		response.ErrorFrom(c, err)
 		return
--- a/backend/internal/handler/wire.go
+++ b/backend/internal/handler/wire.go
@@ -10,6 +10,7 @@ import (
 // ProvideAdminHandlers creates the AdminHandlers struct
 func ProvideAdminHandlers(
 	dashboardHandler *admin.DashboardHandler,
+	opsHandler *admin.OpsHandler,
 	userHandler *admin.UserHandler,
 	groupHandler *admin.GroupHandler,
 	accountHandler *admin.AccountHandler,
@@ -27,6 +28,7 @@ func ProvideAdminHandlers(
 ) *AdminHandlers {
 	return &AdminHandlers{
 		Dashboard:        dashboardHandler,
+		Ops:              opsHandler,
 		User:             userHandler,
 		Group:            groupHandler,
 		Account:          accountHandler,
@@ -96,6 +98,7 @@ var ProviderSet = wire.NewSet(

 	// Admin handlers
 	admin.NewDashboardHandler,
+	admin.NewOpsHandler,
 	admin.NewUserHandler,
 	admin.NewGroupHandler,
 	admin.NewAccountHandler,