Merge branch 'test' into dev

deploy/.env.example

@@ -69,6 +69,33 @@ JWT_EXPIRE_HOUR=24
 # Leave unset to use default ./config.yaml
 #CONFIG_FILE=./config.yaml
 
+# -----------------------------------------------------------------------------
+# Dashboard Aggregation (Optional)
+# -----------------------------------------------------------------------------
+# Enable aggregation job
+# 启用仪表盘预聚合
+DASHBOARD_AGGREGATION_ENABLED=true
+# Refresh interval (seconds)
+# 刷新间隔（秒）
+DASHBOARD_AGGREGATION_INTERVAL_SECONDS=60
+# Lookback window (seconds)
+# 回看窗口（秒）
+DASHBOARD_AGGREGATION_LOOKBACK_SECONDS=120
+# Allow manual backfill
+# 允许手动回填
+DASHBOARD_AGGREGATION_BACKFILL_ENABLED=false
+# Backfill max range (days)
+# 回填最大跨度（天）
+DASHBOARD_AGGREGATION_BACKFILL_MAX_DAYS=31
+# Recompute recent N days on startup
+# 启动时重算最近 N 天
+DASHBOARD_AGGREGATION_RECOMPUTE_DAYS=2
+# Retention windows (days)
+# 保留窗口（天）
+DASHBOARD_AGGREGATION_RETENTION_USAGE_LOGS_DAYS=90
+DASHBOARD_AGGREGATION_RETENTION_HOURLY_DAYS=180
+DASHBOARD_AGGREGATION_RETENTION_DAILY_DAYS=730
+
 # -----------------------------------------------------------------------------
 # Security Configuration
 # -----------------------------------------------------------------------------

deploy/config.example.yaml

@@ -194,6 +194,63 @@ api_key_auth_cache:
   # 缓存未命中时启用 singleflight 合并回源
   singleflight: true
 
+# =============================================================================
+# Dashboard Cache Configuration
+# 仪表盘缓存配置
+# =============================================================================
+dashboard_cache:
+  # Enable dashboard cache
+  # 启用仪表盘缓存
+  enabled: true
+  # Redis key prefix for multi-environment isolation
+  # Redis key 前缀，用于多环境隔离
+  key_prefix: "sub2api:"
+  # Fresh TTL (seconds); within this window cached stats are considered fresh
+  # 新鲜阈值（秒）；命中后处于该窗口视为新鲜数据
+  stats_fresh_ttl_seconds: 15
+  # Cache TTL (seconds) stored in Redis
+  # Redis 缓存 TTL（秒）
+  stats_ttl_seconds: 30
+  # Async refresh timeout (seconds)
+  # 异步刷新超时（秒）
+  stats_refresh_timeout_seconds: 30
+
+# =============================================================================
+# Dashboard Aggregation Configuration
+# 仪表盘预聚合配置（重启生效）
+# =============================================================================
+dashboard_aggregation:
+  # Enable aggregation job
+  # 启用聚合作业
+  enabled: true
+  # Refresh interval (seconds)
+  # 刷新间隔（秒）
+  interval_seconds: 60
+  # Lookback window (seconds) for late-arriving data
+  # 回看窗口（秒），处理迟到数据
+  lookback_seconds: 120
+  # Allow manual backfill
+  # 允许手动回填
+  backfill_enabled: false
+  # Backfill max range (days)
+  # 回填最大跨度（天）
+  backfill_max_days: 31
+  # Recompute recent N days on startup
+  # 启动时重算最近 N 天
+  recompute_days: 2
+  # Retention windows (days)
+  # 保留窗口（天）
+  retention:
+    # Raw usage_logs retention
+    # 原始 usage_logs 保留天数
+    usage_logs_days: 90
+    # Hourly aggregation retention
+    # 小时聚合保留天数
+    hourly_days: 180
+    # Daily aggregation retention
+    # 日聚合保留天数
+    daily_days: 730
+
 # =============================================================================
 # Concurrency Wait Configuration
 # 并发等待配置

frontend/src/types/index.ts

@@ -652,6 +652,9 @@ export interface DashboardStats {
   total_users: number
   today_new_users: number // 今日新增用户数
   active_users: number // 今日有请求的用户数
+  hourly_active_users: number // 当前小时活跃用户数（UTC）
+  stats_updated_at: string // 统计更新时间（UTC RFC3339）
+  stats_stale: boolean // 统计是否过期
 
   // API Key 统计
   total_api_keys: number