feat: add usage dashboard and metrics usage rate limiting

.env.example

@@ -83,4 +83,19 @@ NODE_ENV=development
 
 # MEDIA_CLEANUP_INTERVAL_MINUTES: 清理任务执行间隔（分钟，默认 60）
 # MEDIA_CLEANUP_INTERVAL_MINUTES=60
+
+# -----------------------------------------------------------------------------
+# 任务明细与用量统计保留配置（可选）
+# -----------------------------------------------------------------------------
+# JOB_RESULT_RETENTION_HOURS: 任务结果与阶段信息在 Redis 中保留小时数（默认 24）
+# JOB_RESULT_RETENTION_HOURS=24
+
+# USAGE_RETENTION_DAYS: 按天聚合的用量统计保留天数（默认 90）
+# USAGE_RETENTION_DAYS=90
+
+# METRICS_USAGE_RATE_LIMIT_MAX: 用量接口每个 IP 在窗口期内允许的最大请求数（默认 30）
+# METRICS_USAGE_RATE_LIMIT_MAX=30
+
+# METRICS_USAGE_RATE_LIMIT_WINDOW_MS: 用量接口限流窗口时长（毫秒，默认 60000）
+# METRICS_USAGE_RATE_LIMIT_WINDOW_MS=60000
 

README.md

@@ -202,6 +202,10 @@ pinned: false
 | `CODE_RETRY_MAX_RETRIES` | `4` | 代码修复重试次数 |
 | `MEDIA_RETENTION_HOURS` | `72` | 图片/视频文件保留小时数 |
 | `MEDIA_CLEANUP_INTERVAL_MINUTES` | `60` | 媒体清理任务执行间隔（分钟） |
+| `JOB_RESULT_RETENTION_HOURS` | `24` | 任务结果与阶段信息保留小时数 |
+| `USAGE_RETENTION_DAYS` | `90` | 用量统计（按天聚合）保留天数 |
+| `METRICS_USAGE_RATE_LIMIT_MAX` | `30` | 用量接口每个 IP 的窗口最大请求数 |
+| `METRICS_USAGE_RATE_LIMIT_WINDOW_MS` | `60000` | 用量接口限流窗口时长（毫秒） |
 
 **示例 `.env` 文件：**
 

frontend/src/App.tsx

@@ -8,6 +8,7 @@ import { AiModifyModal } from './components/AiModifyModal';
 import { SettingsModal } from './components/SettingsModal';
 import { PromptsManager } from './components/PromptsManager';
 import { DonationModal } from './components/DonationModal';
+import { UsageDashboard } from './components/UsageDashboard';
 import ManimCatLogo from './components/ManimCatLogo';
 import { TopLeftActions } from './components/app/top-left-actions';
 import { TopRightActions } from './components/app/top-right-actions';
@@ -19,6 +20,7 @@ function App() {
   const [settingsOpen, setSettingsOpen] = useState(false);
   const [promptsOpen, setPromptsOpen] = useState(false);
   const [donationOpen, setDonationOpen] = useState(false);
+  const [usageOpen, setUsageOpen] = useState(false);
   const [aiModifyOpen, setAiModifyOpen] = useState(false);
   const [aiModifyInput, setAiModifyInput] = useState('');
   const [currentCode, setCurrentCode] = useState('');
@@ -79,7 +81,11 @@ function App() {
   return (
     <div className="min-h-screen bg-bg-primary transition-colors duration-300 overflow-x-hidden">
       <TopLeftActions onOpenDonation={() => setDonationOpen(true)} />
-      <TopRightActions onOpenPrompts={() => setPromptsOpen(true)} onOpenSettings={() => setSettingsOpen(true)} />
+      <TopRightActions
+        onOpenUsage={() => setUsageOpen(true)}
+        onOpenPrompts={() => setPromptsOpen(true)}
+        onOpenSettings={() => setSettingsOpen(true)}
+      />
 
       <div className="max-w-4xl mx-auto px-4 min-h-screen flex flex-col justify-center" style={{ paddingTop: '18vh', paddingBottom: '12vh' }}>
         <div className="text-center mb-12">
@@ -122,6 +128,7 @@ function App() {
       <SettingsModal isOpen={settingsOpen} onClose={() => setSettingsOpen(false)} onSave={(config) => console.log('保存配置:', config)} />
       <PromptsManager isOpen={promptsOpen} onClose={() => setPromptsOpen(false)} />
       <DonationModal isOpen={donationOpen} onClose={() => setDonationOpen(false)} />
+      <UsageDashboard isOpen={usageOpen} onClose={() => setUsageOpen(false)} />
       <AiModifyModal
         isOpen={aiModifyOpen}
         value={aiModifyInput}

frontend/src/components/UsageDashboard.tsx

@@ -0,0 +1,282 @@
+import { useEffect, useMemo, useState } from 'react';
+import { getUsageMetrics } from '../lib/api';
+import type { UsageDailyPoint, UsageMetricsResponse } from '../types/api';
+
+interface UsageDashboardProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const RANGE_OPTIONS = [7, 14, 30] as const;
+const REFRESH_INTERVAL_MS = 30_000;
+
+function formatNumber(value: number): string {
+  return new Intl.NumberFormat('zh-CN').format(Math.round(value));
+}
+
+function formatPercent(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return '-';
+  }
+  if (ms >= 1000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(ms)}ms`;
+}
+
+function formatDateLabel(date: string): string {
+  const [year, month, day] = date.split('-');
+  if (!year || !month || !day) {
+    return date;
+  }
+  return `${month}/${day}`;
+}
+
+function getMaxDailyValue(daily: UsageDailyPoint[]): number {
+  const maxValue = daily.reduce((max, item) => Math.max(max, item.submittedTotal), 0);
+  return maxValue > 0 ? maxValue : 1;
+}
+
+export function UsageDashboard({ isOpen, onClose }: UsageDashboardProps) {
+  const [shouldRender, setShouldRender] = useState(isOpen);
+  const [isVisible, setIsVisible] = useState(isOpen);
+  const [rangeDays, setRangeDays] = useState<(typeof RANGE_OPTIONS)[number]>(7);
+  const [data, setData] = useState<UsageMetricsResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      setShouldRender(true);
+      setTimeout(() => setIsVisible(true), 50);
+      return;
+    }
+
+    setIsVisible(false);
+    const timeout = setTimeout(() => setShouldRender(false), 250);
+    return () => clearTimeout(timeout);
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    let active = true;
+    const controller = new AbortController();
+
+    const loadData = async () => {
+      if (!active) {
+        return;
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response = await getUsageMetrics(rangeDays, controller.signal);
+        if (active) {
+          setData(response);
+        }
+      } catch (err) {
+        if (!active) {
+          return;
+        }
+        if (err instanceof Error && err.name === 'AbortError') {
+          return;
+        }
+        setError(err instanceof Error ? err.message : '加载统计数据失败');
+      } finally {
+        if (active) {
+          setLoading(false);
+        }
+      }
+    };
+
+    void loadData();
+    const timer = window.setInterval(() => {
+      void loadData();
+    }, REFRESH_INTERVAL_MS);
+
+    return () => {
+      active = false;
+      controller.abort();
+      clearInterval(timer);
+    };
+  }, [isOpen, rangeDays]);
+
+  const chartRows = useMemo(() => data?.daily ?? [], [data]);
+  const maxDailyValue = useMemo(() => getMaxDailyValue(chartRows), [chartRows]);
+  const latestTenRows = useMemo(() => [...chartRows].reverse().slice(0, 10), [chartRows]);
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  return (
+    <div
+      className={`fixed inset-0 z-50 flex flex-col bg-bg-primary transition-all duration-300 ${
+        isVisible ? 'opacity-100' : 'opacity-0 pointer-events-none'
+      }`}
+    >
+      <div className="h-14 bg-bg-secondary/50 border-b border-bg-tertiary/30 flex items-center justify-between px-4">
+        <div className="flex items-center gap-3">
+          <button
+            onClick={onClose}
+            className="p-2 text-text-secondary/70 hover:text-text-primary hover:bg-bg-tertiary/50 rounded-lg transition-colors"
+            aria-label="关闭用量面板"
+          >
+            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+            </svg>
+          </button>
+          <div>
+            <p className="text-sm font-medium text-text-primary">用量面板</p>
+            <p className="text-[11px] text-text-secondary/60">每 30 秒自动刷新</p>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {RANGE_OPTIONS.map((days) => (
+            <button
+              key={days}
+              onClick={() => setRangeDays(days)}
+              className={`px-3 py-1.5 text-xs rounded-lg transition-colors ${
+                rangeDays === days
+                  ? 'bg-accent text-white'
+                  : 'bg-bg-secondary/50 text-text-secondary/80 hover:text-text-primary'
+              }`}
+            >
+              {days} 天
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-4 sm:p-6">
+        {loading && !data ? (
+          <div className="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-4 gap-4 animate-pulse">
+            {Array.from({ length: 8 }).map((_, index) => (
+              <div key={index} className="rounded-2xl bg-bg-secondary/40 h-24" />
+            ))}
+          </div>
+        ) : null}
+
+        {error ? (
+          <div className="rounded-2xl bg-red-50/80 dark:bg-red-900/20 border border-red-200/50 dark:border-red-700/40 p-4 text-sm text-red-600 dark:text-red-300">
+            {error}
+          </div>
+        ) : null}
+
+        {data ? (
+          <div className="space-y-5 animate-fade-in">
+            <div className="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-4 gap-4">
+              <MetricCard title="提交任务" value={formatNumber(data.totals.submittedTotal)} hint={`${data.rangeDays} 天累计`} />
+              <MetricCard title="成功任务" value={formatNumber(data.totals.completedTotal)} hint="渲染完成" />
+              <MetricCard title="成功率" value={formatPercent(data.totals.successRate)} hint="completed / submitted" />
+              <MetricCard title="平均渲染耗时" value={formatDuration(data.totals.avgRenderMs)} hint="仅统计成功任务" />
+              <MetricCard title="失败任务" value={formatNumber(data.totals.failedTotal)} hint={`取消 ${formatNumber(data.totals.cancelledTotal)} 次`} />
+              <MetricCard title="视频完成" value={formatNumber(data.totals.completedVideo)} hint="outputMode=video" />
+              <MetricCard title="图片完成" value={formatNumber(data.totals.completedImage)} hint="outputMode=image" />
+              <MetricCard title="队列积压" value={formatNumber(data.queue.waiting + data.queue.delayed)} hint={`处理中 ${formatNumber(data.queue.active)}`} />
+            </div>
+
+            <div className="rounded-2xl bg-bg-secondary/25 border border-bg-tertiary/30 p-4 sm:p-5">
+              <div className="flex items-center justify-between mb-4">
+                <h3 className="text-sm font-medium text-text-primary">日趋势</h3>
+                <p className="text-xs text-text-secondary/70">提交/成功（最近 {data.rangeDays} 天）</p>
+              </div>
+
+              <div className="h-52 sm:h-60 flex items-end gap-2 sm:gap-3 overflow-x-auto pb-2">
+                {chartRows.map((item) => {
+                  const submittedHeight = Math.max((item.submittedTotal / maxDailyValue) * 100, item.submittedTotal > 0 ? 8 : 0);
+                  const completedHeight = Math.max((item.completedTotal / maxDailyValue) * 100, item.completedTotal > 0 ? 6 : 0);
+                  return (
+                    <div key={item.date} className="relative min-w-[40px] sm:min-w-[48px] flex-1 flex flex-col items-center gap-1.5 group">
+                      <div className="w-full h-40 sm:h-48 rounded-xl bg-bg-tertiary/20 relative overflow-hidden border border-bg-tertiary/30">
+                        <div
+                          className="absolute left-[22%] bottom-0 w-[22%] rounded-t-md bg-text-tertiary/45 transition-all"
+                          style={{ height: `${submittedHeight}%` }}
+                        />
+                        <div
+                          className="absolute right-[22%] bottom-0 w-[22%] rounded-t-md bg-accent/85 transition-all"
+                          style={{ height: `${completedHeight}%` }}
+                        />
+                      </div>
+                      <span className="text-[10px] text-text-secondary/70">{formatDateLabel(item.date)}</span>
+                      <div className="absolute opacity-0 group-hover:opacity-100 pointer-events-none transition-opacity -translate-y-20 bg-bg-secondary border border-bg-tertiary/40 text-[11px] text-text-secondary px-2 py-1 rounded-md shadow-md">
+                        提交 {item.submittedTotal} / 成功 {item.completedTotal}
+                      </div>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+
+            <div className="rounded-2xl bg-bg-secondary/25 border border-bg-tertiary/30 overflow-hidden">
+              <div className="px-4 py-3 border-b border-bg-tertiary/30 flex items-center justify-between">
+                <h3 className="text-sm font-medium text-text-primary">最近 10 天</h3>
+                <p className="text-xs text-text-secondary/60">{new Date(data.timestamp).toLocaleString()}</p>
+              </div>
+
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead className="text-text-secondary/70 text-xs bg-bg-secondary/30">
+                    <tr>
+                      <th className="text-left px-4 py-2.5 font-medium">日期</th>
+                      <th className="text-right px-4 py-2.5 font-medium">提交</th>
+                      <th className="text-right px-4 py-2.5 font-medium">成功</th>
+                      <th className="text-right px-4 py-2.5 font-medium">失败</th>
+                      <th className="text-right px-4 py-2.5 font-medium">成功率</th>
+                      <th className="text-right px-4 py-2.5 font-medium">平均耗时</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {latestTenRows.length === 0 ? (
+                      <tr>
+                        <td colSpan={6} className="px-4 py-6 text-center text-text-secondary/60 text-xs">
+                          暂无数据
+                        </td>
+                      </tr>
+                    ) : (
+                      latestTenRows.map((row) => (
+                        <tr key={row.date} className="border-t border-bg-tertiary/20 hover:bg-bg-secondary/20 transition-colors">
+                          <td className="px-4 py-2.5 text-text-primary">{row.date}</td>
+                          <td className="px-4 py-2.5 text-right text-text-secondary">{formatNumber(row.submittedTotal)}</td>
+                          <td className="px-4 py-2.5 text-right text-text-secondary">{formatNumber(row.completedTotal)}</td>
+                          <td className="px-4 py-2.5 text-right text-text-secondary">{formatNumber(row.failedTotal)}</td>
+                          <td className="px-4 py-2.5 text-right text-text-secondary">{formatPercent(row.successRate)}</td>
+                          <td className="px-4 py-2.5 text-right text-text-secondary">{formatDuration(row.avgRenderMs)}</td>
+                        </tr>
+                      ))
+                    )}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+interface MetricCardProps {
+  title: string;
+  value: string;
+  hint: string;
+}
+
+function MetricCard({ title, value, hint }: MetricCardProps) {
+  return (
+    <div className="rounded-2xl bg-bg-secondary/25 border border-bg-tertiary/30 px-4 py-3.5">
+      <p className="text-xs text-text-secondary/70">{title}</p>
+      <p className="mt-2 text-2xl font-medium text-text-primary tracking-tight">{value}</p>
+      <p className="mt-1 text-[11px] text-text-secondary/55">{hint}</p>
+    </div>
+  );
+}

frontend/src/components/app/top-right-actions.tsx

@@ -3,11 +3,21 @@ import { ThemeToggle } from '../ThemeToggle';
 interface TopRightActionsProps {
   onOpenPrompts: () => void;
   onOpenSettings: () => void;
+  onOpenUsage: () => void;
 }
 
-export function TopRightActions({ onOpenPrompts, onOpenSettings }: TopRightActionsProps) {
+export function TopRightActions({ onOpenPrompts, onOpenSettings, onOpenUsage }: TopRightActionsProps) {
   return (
     <div className="fixed top-4 right-4 z-50 flex items-center gap-2">
+      <button
+        onClick={onOpenUsage}
+        className="p-2.5 text-text-secondary/70 hover:text-text-secondary hover:bg-bg-secondary/50 rounded-full transition-all active:scale-90 active:duration-75"
+        title="用量面板"
+      >
+        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 19h16M6 16V9m6 7V5m6 11v-4" />
+        </svg>
+      </button>
       <button
         onClick={onOpenPrompts}
         className="p-2.5 text-text-secondary/70 hover:text-text-secondary hover:bg-bg-secondary/50 rounded-full transition-all active:scale-90 active:duration-75"

frontend/src/lib/api.ts

@@ -1,4 +1,12 @@
-import type { GenerateRequest, GenerateResponse, JobResult, ApiError, PromptDefaults, ModifyRequest } from '../types/api';
+import type {
+  GenerateRequest,
+  GenerateResponse,
+  JobResult,
+  ApiError,
+  PromptDefaults,
+  ModifyRequest,
+  UsageMetricsResponse
+} from '../types/api';
 import { loadSettings } from './settings';
 
 const API_BASE = '/api';
@@ -94,3 +102,16 @@ export async function cancelJob(jobId: string): Promise<void> {
   }
 }
 
+export async function getUsageMetrics(days = 7, signal?: AbortSignal): Promise<UsageMetricsResponse> {
+  const response = await fetch(`${API_BASE}/metrics/usage?days=${days}`, {
+    headers: getAuthHeaders(),
+    signal,
+  });
+
+  if (!response.ok) {
+    const error: ApiError = await response.json();
+    throw new Error(error.error || '获取用量统计失败');
+  }
+
+  return response.json();
+}

frontend/src/types/api.ts

@@ -132,10 +132,56 @@ export interface JobResult {
 
   error?: string;
   details?: string;
-  cancel_reason?: string;
-}
-
-/** API 错误 */
-export interface ApiError {
-  error: string;
-}
+  cancel_reason?: string;
+}
+
+export interface QueueStats {
+  waiting: number;
+  active: number;
+  completed: number;
+  failed: number;
+  delayed: number;
+  total: number;
+}
+
+export interface UsageDailyPoint {
+  date: string;
+  submittedTotal: number;
+  submittedGenerate: number;
+  submittedModify: number;
+  completedTotal: number;
+  failedTotal: number;
+  cancelledTotal: number;
+  completedVideo: number;
+  completedImage: number;
+  renderMsSum: number;
+  successRate: number;
+  avgRenderMs: number;
+}
+
+export interface UsageTotals {
+  submittedTotal: number;
+  submittedGenerate: number;
+  submittedModify: number;
+  completedTotal: number;
+  failedTotal: number;
+  cancelledTotal: number;
+  completedVideo: number;
+  completedImage: number;
+  renderMsSum: number;
+  successRate: number;
+  avgRenderMs: number;
+}
+
+export interface UsageMetricsResponse {
+  timestamp: string;
+  rangeDays: number;
+  daily: UsageDailyPoint[];
+  totals: UsageTotals;
+  queue: QueueStats;
+}
+
+/** API 错误 */
+export interface ApiError {
+  error: string;
+}

src/middlewares/rate-limit.ts

@@ -0,0 +1,75 @@
+import type { NextFunction, Request, Response } from 'express'
+
+interface RateLimitOptions {
+  windowMs: number
+  maxRequests: number
+  message?: string
+}
+
+interface RateLimitEntry {
+  count: number
+  resetAt: number
+}
+
+function parseClientIp(req: Request): string {
+  const forwardedFor = req.headers['x-forwarded-for']
+  if (typeof forwardedFor === 'string' && forwardedFor.trim().length > 0) {
+    const firstIp = forwardedFor.split(',')[0]?.trim()
+    if (firstIp) {
+      return firstIp
+    }
+  }
+
+  if (Array.isArray(forwardedFor) && forwardedFor.length > 0) {
+    const firstIp = forwardedFor[0]?.trim()
+    if (firstIp) {
+      return firstIp
+    }
+  }
+
+  return req.ip || req.socket.remoteAddress || 'unknown'
+}
+
+export function createIpRateLimiter(options: RateLimitOptions) {
+  const { windowMs, maxRequests, message = 'Too many requests, please try again later.' } = options
+  const counters = new Map<string, RateLimitEntry>()
+  const cleanupIntervalMs = Math.max(1000, Math.min(windowMs, 60_000))
+  let lastCleanupAt = 0
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const now = Date.now()
+
+    if (now - lastCleanupAt >= cleanupIntervalMs) {
+      for (const [key, entry] of counters.entries()) {
+        if (entry.resetAt <= now) {
+          counters.delete(key)
+        }
+      }
+      lastCleanupAt = now
+    }
+
+    const clientIp = parseClientIp(req)
+    const current = counters.get(clientIp)
+
+    if (!current || current.resetAt <= now) {
+      counters.set(clientIp, { count: 1, resetAt: now + windowMs })
+      next()
+      return
+    }
+
+    if (current.count >= maxRequests) {
+      const retryAfterSeconds = Math.max(1, Math.ceil((current.resetAt - now) / 1000))
+      res.setHeader('Retry-After', String(retryAfterSeconds))
+      res.status(429).json({
+        error: 'Rate limit exceeded',
+        message,
+        retryAfterSeconds
+      })
+      return
+    }
+
+    current.count += 1
+    counters.set(clientIp, current)
+    next()
+  }
+}

src/queues/processors/video.processor.ts

@@ -97,7 +97,7 @@ videoQueue.process(async (job) => {
 
     await storeJobResult(jobId, {
       status: 'failed',
-      data: { error: errorMessage, cancelReason }
+      data: { error: errorMessage, cancelReason, outputMode }
     })
     await clearJobCancelled(jobId)
 

src/routes/generate.route.ts

@@ -14,6 +14,7 @@ import express from 'express'
 import { v4 as uuidv4 } from 'uuid'
 import { videoQueue } from '../config/bull'
 import { storeJobStage } from '../services/job-store'
+import { recordUsageSubmission } from '../services/usage-metrics'
 import { createLogger } from '../utils/logger'
 import { ValidationError } from '../utils/errors'
 import { asyncHandler } from '../middlewares/error-handler'
@@ -64,7 +65,7 @@ async function handleGenerateRequest(req: express.Request, res: express.Response
   await storeJobStage(jobId, code ? 'rendering' : 'analyzing')
 
   // 添加任务到 Bull 队列
-  await videoQueue.add(
+  await videoQueue.add(
     {
       jobId,
       concept: sanitizedConcept,
@@ -80,9 +81,11 @@ async function handleGenerateRequest(req: express.Request, res: express.Response
     {
       jobId
     }
-  )
-
-  logger.info('动画请求已加入队列', { jobId })
+  )
+
+  await recordUsageSubmission('generate', outputMode)
+
+  logger.info('动画请求已加入队列', { jobId })
 
   const response: GenerateResponse = {
     success: true,

src/routes/metrics.route.ts

@@ -14,9 +14,27 @@ import {
 } from './metrics/memory-peak'
 import { getCPUInfo, getRuntimeInfo, getSystemMemory } from './metrics/system-metrics'
 import { getDiskUsage, getRedisMemory } from './metrics/storage-metrics'
+import { getUsageSummary, getUsageRetentionDays } from '../services/usage-metrics'
+import { createIpRateLimiter } from '../middlewares/rate-limit'
 
 const router = Router()
 const logger = createLogger('Metrics')
+const DEFAULT_USAGE_RATE_LIMIT_MAX = 30
+const DEFAULT_USAGE_RATE_LIMIT_WINDOW_MS = 60_000
+
+function parsePositiveInteger(input: string | undefined, fallback: number): number {
+  const parsed = Number(input)
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback
+  }
+  return Math.floor(parsed)
+}
+
+const usageRateLimiter = createIpRateLimiter({
+  maxRequests: parsePositiveInteger(process.env.METRICS_USAGE_RATE_LIMIT_MAX, DEFAULT_USAGE_RATE_LIMIT_MAX),
+  windowMs: parsePositiveInteger(process.env.METRICS_USAGE_RATE_LIMIT_WINDOW_MS, DEFAULT_USAGE_RATE_LIMIT_WINDOW_MS),
+  message: '用量接口访问过于频繁，请稍后再试。'
+})
 
 const stopMemorySampler = startMemoryPeakSampler()
 void stopMemorySampler
@@ -71,4 +89,33 @@ router.post('/reset', (req: Request, res: Response) => {
   })
 })
 
+/**
+ * GET /api/metrics/usage?days=7
+ * 获取用量统计（按天聚合）
+ */
+router.get('/usage', usageRateLimiter, async (req: Request, res: Response) => {
+  try {
+    const queryDays = Array.isArray(req.query.days) ? req.query.days[0] : req.query.days
+    const parsedDays = Number.parseInt(String(queryDays || '7'), 10)
+    const retentionDays = getUsageRetentionDays()
+    const days = Number.isFinite(parsedDays)
+      ? Math.min(Math.max(parsedDays, 1), retentionDays)
+      : Math.min(7, retentionDays)
+
+    const [usage, queue] = await Promise.all([getUsageSummary(days), getQueueStats()])
+
+    res.json({
+      timestamp: new Date().toISOString(),
+      ...usage,
+      queue
+    })
+  } catch (error) {
+    logger.error('Failed to get usage metrics', { error })
+    res.status(500).json({
+      error: 'Failed to collect usage metrics',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    })
+  }
+})
+
 export default router

src/routes/modify.route.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 import { v4 as uuidv4 } from 'uuid'
 import { videoQueue } from '../config/bull'
 import { storeJobStage } from '../services/job-store'
+import { recordUsageSubmission } from '../services/usage-metrics'
 import { createLogger } from '../utils/logger'
 import { ValidationError } from '../utils/errors'
 import { asyncHandler } from '../middlewares/error-handler'
@@ -83,6 +84,8 @@ async function handleModifyRequest(req: express.Request, res: express.Response)
     { jobId }
   )
 
+  await recordUsageSubmission('modify', outputMode)
+
   const response: GenerateResponse = {
     success: true,
     jobId,

src/services/job-cancel.ts

@@ -4,11 +4,12 @@
  */
 
 import { videoQueue } from '../config/bull'
-import { createLogger } from '../utils/logger'
-import { JobCancelledError } from '../utils/errors'
-import { clearJobCancelled, getCancelReason, isJobCancelled, markJobCancelled } from './job-cancel-store'
-import { cancelManimProcess } from '../utils/manim-process-registry'
-import { deleteJobStage, getJobResult, storeJobResult } from './job-store'
+import { createLogger } from '../utils/logger'
+import { JobCancelledError } from '../utils/errors'
+import { clearJobCancelled, getCancelReason, isJobCancelled, markJobCancelled } from './job-cancel-store'
+import { cancelManimProcess } from '../utils/manim-process-registry'
+import { deleteJobStage, getJobResult, storeJobResult } from './job-store'
+import type { OutputMode } from '../types'
 
 const logger = createLogger('JobCancel')
 export async function ensureJobNotCancelled(jobId: string, job?: { discard: () => void }): Promise<void> {
@@ -26,20 +27,26 @@ export async function ensureJobNotCancelled(jobId: string, job?: { discard: () =
   throw new JobCancelledError('Job cancelled', reason || undefined)
 }
 
-export async function cancelJob(jobId: string): Promise<{ jobState: string | null }> {
-  const existing = await getJobResult(jobId)
-  if (existing?.status === 'completed') {
-    return { jobState: 'completed' }
-  }
+export async function cancelJob(jobId: string): Promise<{ jobState: string | null }> {
+  const existing = await getJobResult(jobId)
+  if (existing?.status === 'completed') {
+    return { jobState: 'completed' }
+  }
 
   const cancelReason = 'Cancelled by client'
   await markJobCancelled(jobId, cancelReason)
 
-  let jobState: string | null = null
-  const job = await videoQueue.getJob(jobId)
-
-  if (job) {
-    jobState = await job.getState()
+  let jobState: string | null = null
+  let outputMode: OutputMode | undefined =
+    existing?.status === 'failed' ? existing.data.outputMode : undefined
+  const job = await videoQueue.getJob(jobId)
+
+  if (job) {
+    jobState = await job.getState()
+    const queueOutputMode = (job.data as { outputMode?: OutputMode } | undefined)?.outputMode
+    if (queueOutputMode) {
+      outputMode = queueOutputMode
+    }
 
     if (jobState === 'waiting' || jobState === 'delayed') {
       await job.remove()
@@ -55,12 +62,12 @@ export async function cancelJob(jobId: string): Promise<{ jobState: string | nul
     await clearJobCancelled(jobId)
   }
 
-  if (!existing || existing.status != 'failed') {
-    await storeJobResult(jobId, {
-      status: 'failed',
-      data: { error: 'Job cancelled', cancelReason }
-    })
-  }
+  if (!existing || existing.status != 'failed') {
+    await storeJobResult(jobId, {
+      status: 'failed',
+      data: { error: 'Job cancelled', cancelReason, outputMode }
+    })
+  }
 
   await deleteJobStage(jobId)
 

src/services/job-store.ts

@@ -10,22 +10,41 @@
 import { redisClient, REDIS_KEYS, generateRedisKey } from '../config/redis'
 import { videoQueue } from '../config/bull'
 import { getCancelReason, isJobCancelled } from './job-cancel-store'
+import { recordUsageFinalization } from './usage-metrics'
 import { JobCancelledError } from '../utils/errors'
 import { createLogger } from '../utils/logger'
-import type { JobResult, ProcessingStage } from '../types'
+import type { CompletedJobResult, FailedJobResult, JobResult, ProcessingStage } from '../types'
 
 const logger = createLogger('JobStore')
 
-const JOB_RESULTS_GROUP = 'job-results'
-const JOB_RESULT_KEY_PREFIX = `${REDIS_KEYS.JOB_RESULT}`
-const JOB_STAGE_KEY_PREFIX = `${REDIS_KEYS.JOB_RESULT}:stage`
+const JOB_RESULTS_GROUP = 'job-results'
+const JOB_RESULT_KEY_PREFIX = `${REDIS_KEYS.JOB_RESULT}`
+const JOB_STAGE_KEY_PREFIX = `${REDIS_KEYS.JOB_RESULT}:stage`
+const DEFAULT_JOB_RESULT_RETENTION_HOURS = 24
+type StorableJobResult = Pick<CompletedJobResult, 'status' | 'data'> | Pick<FailedJobResult, 'status' | 'data'>
+
+function parsePositiveInteger(input: string | undefined, fallback: number): number {
+  const value = Number(input)
+  if (!Number.isFinite(value) || value <= 0) {
+    return fallback
+  }
+  return Math.floor(value)
+}
+
+function getJobResultRetentionSeconds(): number {
+  const retentionHours = parsePositiveInteger(
+    process.env.JOB_RESULT_RETENTION_HOURS,
+    DEFAULT_JOB_RESULT_RETENTION_HOURS
+  )
+  return retentionHours * 60 * 60
+}
 
 /**
  * 使用 Redis 存储任务结果
  */
 export async function storeJobResult(
   jobId: string,
-  result: Omit<JobResult, 'timestamp'>
+  result: StorableJobResult
 ): Promise<void> {
   if (result.status === 'completed' && (await isJobCancelled(jobId))) {
     const reason = await getCancelReason(jobId)
@@ -39,14 +58,26 @@ export async function storeJobResult(
     timestamp: Date.now()
   }
 
-  try {
-    await redisClient.set(key, JSON.stringify(data))
-    // 设置过期时间：7 天后自动清理
-    await redisClient.expire(key, 7 * 24 * 60 * 60)
-    logger.info('任务结果已存储', { jobId, status: result.status })
-  } catch (error) {
-    logger.error('存储任务结果失败', { jobId, error })
-    throw error
+  try {
+    const retentionSeconds = getJobResultRetentionSeconds()
+    await redisClient.set(key, JSON.stringify(data))
+    await redisClient.expire(key, retentionSeconds)
+    logger.info('任务结果已存储', { jobId, status: result.status })
+
+    const isCancelled = result.status === 'failed' ? Boolean(result.data.cancelReason) : false
+    const renderMs = result.status === 'completed' ? result.data.timings?.total : undefined
+    const outputMode = result.data.outputMode
+
+    await recordUsageFinalization({
+      jobId,
+      status: result.status,
+      outputMode,
+      isCancelled,
+      renderMs
+    })
+  } catch (error) {
+    logger.error('存储任务结果失败', { jobId, error })
+    throw error
   }
 }
 
@@ -141,18 +172,18 @@ export async function getAllJobResults(): Promise<Array<{ jobId: string; result:
 /**
  * 存储任务处理阶段
  */
-export async function storeJobStage(
-  jobId: string,
-  stage: ProcessingStage
-): Promise<void> {
+export async function storeJobStage(
+  jobId: string,
+  stage: ProcessingStage
+): Promise<void> {
   const key = generateRedisKey(JOB_STAGE_KEY_PREFIX, jobId)
 
-  try {
-    await redisClient.set(key, stage)
-    // 设置过期时间：与 job result 相同，7 天后自动清理
-    await redisClient.expire(key, 7 * 24 * 60 * 60)
-    logger.debug('任务阶段已存储', { jobId, stage })
-  } catch (error) {
+  try {
+    const retentionSeconds = getJobResultRetentionSeconds()
+    await redisClient.set(key, stage)
+    await redisClient.expire(key, retentionSeconds)
+    logger.debug('任务阶段已存储', { jobId, stage })
+  } catch (error) {
     logger.error('存储任务阶段失败', { jobId, error })
     throw error
   }

src/services/usage-metrics.ts

@@ -0,0 +1,301 @@
+import { redisClient } from '../config/redis'
+import type { OutputMode } from '../types'
+import { createLogger } from '../utils/logger'
+
+const logger = createLogger('UsageMetrics')
+
+const USAGE_DAILY_KEY_PREFIX = 'usage:daily:'
+const USAGE_FINALIZED_MARK_KEY_PREFIX = 'usage:finalized:'
+
+const DEFAULT_USAGE_RETENTION_DAYS = 90
+
+const DAILY_FIELDS = [
+  'submitted_total',
+  'submitted_generate',
+  'submitted_modify',
+  'completed_total',
+  'failed_total',
+  'cancelled_total',
+  'completed_video',
+  'completed_image',
+  'render_ms_sum'
+] as const
+
+type DailyField = (typeof DAILY_FIELDS)[number]
+
+type DailyCounters = Record<DailyField, number>
+
+export interface UsageDailyPoint {
+  date: string
+  submittedTotal: number
+  submittedGenerate: number
+  submittedModify: number
+  completedTotal: number
+  failedTotal: number
+  cancelledTotal: number
+  completedVideo: number
+  completedImage: number
+  renderMsSum: number
+  successRate: number
+  avgRenderMs: number
+}
+
+export interface UsageSummary {
+  rangeDays: number
+  daily: UsageDailyPoint[]
+  totals: {
+    submittedTotal: number
+    submittedGenerate: number
+    submittedModify: number
+    completedTotal: number
+    failedTotal: number
+    cancelledTotal: number
+    completedVideo: number
+    completedImage: number
+    renderMsSum: number
+    successRate: number
+    avgRenderMs: number
+  }
+}
+
+function parsePositiveInteger(input: string | undefined, fallback: number): number {
+  const parsed = Number(input)
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback
+  }
+  return Math.floor(parsed)
+}
+
+export function getUsageRetentionDays(): number {
+  return parsePositiveInteger(process.env.USAGE_RETENTION_DAYS, DEFAULT_USAGE_RETENTION_DAYS)
+}
+
+function getUsageRetentionSeconds(): number {
+  return getUsageRetentionDays() * 24 * 60 * 60
+}
+
+function getUtcDateString(date: Date): string {
+  return date.toISOString().slice(0, 10)
+}
+
+function getDailyKey(dateString: string): string {
+  return `${USAGE_DAILY_KEY_PREFIX}${dateString}`
+}
+
+function parseCounter(value: string | null): number {
+  if (!value) {
+    return 0
+  }
+  const parsed = Number.parseInt(value, 10)
+  if (!Number.isFinite(parsed)) {
+    return 0
+  }
+  return parsed
+}
+
+function buildDailyPoint(date: string, counters: DailyCounters): UsageDailyPoint {
+  const submittedTotal = counters.submitted_total
+  const completedTotal = counters.completed_total
+  const successRate = submittedTotal > 0 ? completedTotal / submittedTotal : 0
+  const avgRenderMs = completedTotal > 0 ? counters.render_ms_sum / completedTotal : 0
+
+  return {
+    date,
+    submittedTotal,
+    submittedGenerate: counters.submitted_generate,
+    submittedModify: counters.submitted_modify,
+    completedTotal,
+    failedTotal: counters.failed_total,
+    cancelledTotal: counters.cancelled_total,
+    completedVideo: counters.completed_video,
+    completedImage: counters.completed_image,
+    renderMsSum: counters.render_ms_sum,
+    successRate,
+    avgRenderMs
+  }
+}
+
+async function incrementDailyCounters(dateString: string, counters: Partial<DailyCounters>): Promise<void> {
+  const key = getDailyKey(dateString)
+  const retentionSeconds = getUsageRetentionSeconds()
+  const tx = redisClient.multi()
+
+  for (const field of DAILY_FIELDS) {
+    const increment = counters[field]
+    if (!increment) {
+      continue
+    }
+    tx.hincrby(key, field, Math.floor(increment))
+  }
+
+  tx.expire(key, retentionSeconds)
+  await tx.exec()
+}
+
+export async function recordUsageSubmission(
+  source: 'generate' | 'modify',
+  _outputMode: OutputMode
+): Promise<void> {
+  const dateString = getUtcDateString(new Date())
+  const counters: Partial<DailyCounters> = {
+    submitted_total: 1
+  }
+
+  if (source === 'generate') {
+    counters.submitted_generate = 1
+  } else {
+    counters.submitted_modify = 1
+  }
+
+  try {
+    await incrementDailyCounters(dateString, counters)
+  } catch (error) {
+    logger.warn('记录任务提交用量失败', { source, error: String(error) })
+  }
+}
+
+export async function recordUsageFinalization(args: {
+  jobId: string
+  status: 'completed' | 'failed'
+  outputMode?: OutputMode
+  isCancelled?: boolean
+  renderMs?: number
+}): Promise<void> {
+  const { jobId, status, outputMode, isCancelled = false, renderMs } = args
+  const retentionSeconds = getUsageRetentionSeconds()
+  const markKey = `${USAGE_FINALIZED_MARK_KEY_PREFIX}${jobId}`
+
+  try {
+    const markResult = await redisClient.set(markKey, '1', 'EX', retentionSeconds, 'NX')
+    if (markResult !== 'OK') {
+      return
+    }
+
+    const dateString = getUtcDateString(new Date())
+    const counters: Partial<DailyCounters> = {}
+
+    if (status === 'completed') {
+      counters.completed_total = 1
+      if (outputMode === 'video') {
+        counters.completed_video = 1
+      } else if (outputMode === 'image') {
+        counters.completed_image = 1
+      }
+
+      if (typeof renderMs === 'number' && Number.isFinite(renderMs) && renderMs > 0) {
+        counters.render_ms_sum = Math.round(renderMs)
+      }
+    } else {
+      counters.failed_total = 1
+      if (isCancelled) {
+        counters.cancelled_total = 1
+      }
+    }
+
+    await incrementDailyCounters(dateString, counters)
+  } catch (error) {
+    logger.warn('记录任务完成用量失败', {
+      jobId,
+      status,
+      outputMode,
+      isCancelled,
+      error: String(error)
+    })
+  }
+}
+
+function clampRangeDays(input: number): number {
+  const retentionDays = getUsageRetentionDays()
+  if (!Number.isFinite(input) || input <= 0) {
+    return Math.min(7, retentionDays)
+  }
+  return Math.min(Math.floor(input), retentionDays)
+}
+
+function createDateWindow(rangeDays: number): string[] {
+  const now = new Date()
+  const todayUtc = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()))
+  const dates: string[] = []
+
+  for (let offset = rangeDays - 1; offset >= 0; offset -= 1) {
+    const target = new Date(todayUtc)
+    target.setUTCDate(todayUtc.getUTCDate() - offset)
+    dates.push(getUtcDateString(target))
+  }
+
+  return dates
+}
+
+function getEmptyCounters(): DailyCounters {
+  return {
+    submitted_total: 0,
+    submitted_generate: 0,
+    submitted_modify: 0,
+    completed_total: 0,
+    failed_total: 0,
+    cancelled_total: 0,
+    completed_video: 0,
+    completed_image: 0,
+    render_ms_sum: 0
+  }
+}
+
+export async function getUsageSummary(days: number): Promise<UsageSummary> {
+  const rangeDays = clampRangeDays(days)
+  const dates = createDateWindow(rangeDays)
+
+  const pipeline = redisClient.pipeline()
+  for (const date of dates) {
+    pipeline.hmget(getDailyKey(date), ...DAILY_FIELDS)
+  }
+
+  const responses = await pipeline.exec()
+  const daily = dates.map((date, index) => {
+    const entry = responses?.[index]
+    const counters = getEmptyCounters()
+    const values = Array.isArray(entry?.[1]) ? (entry[1] as Array<string | null>) : []
+
+    DAILY_FIELDS.forEach((field, fieldIndex) => {
+      counters[field] = parseCounter(values[fieldIndex] ?? null)
+    })
+
+    return buildDailyPoint(date, counters)
+  })
+
+  const totals = daily.reduce(
+    (acc, current) => {
+      acc.submittedTotal += current.submittedTotal
+      acc.submittedGenerate += current.submittedGenerate
+      acc.submittedModify += current.submittedModify
+      acc.completedTotal += current.completedTotal
+      acc.failedTotal += current.failedTotal
+      acc.cancelledTotal += current.cancelledTotal
+      acc.completedVideo += current.completedVideo
+      acc.completedImage += current.completedImage
+      acc.renderMsSum += current.renderMsSum
+      return acc
+    },
+    {
+      submittedTotal: 0,
+      submittedGenerate: 0,
+      submittedModify: 0,
+      completedTotal: 0,
+      failedTotal: 0,
+      cancelledTotal: 0,
+      completedVideo: 0,
+      completedImage: 0,
+      renderMsSum: 0,
+      successRate: 0,
+      avgRenderMs: 0
+    }
+  )
+
+  totals.successRate = totals.submittedTotal > 0 ? totals.completedTotal / totals.submittedTotal : 0
+  totals.avgRenderMs = totals.completedTotal > 0 ? totals.renderMsSum / totals.completedTotal : 0
+
+  return {
+    rangeDays,
+    daily,
+    totals
+  }
+}

src/types/index.ts

@@ -119,15 +119,16 @@ export interface CompletedJobResult {
 /**
  * 浠诲姟缁撴灉 - 澶辫触鐘舵€?
  */
-export interface FailedJobResult {
-  status: 'failed'
-  data: {
-    error: string
-    details?: string
-    cancelReason?: string
-  }
-  timestamp: number
-}
+export interface FailedJobResult {
+  status: 'failed'
+  data: {
+    error: string
+    details?: string
+    cancelReason?: string
+    outputMode?: OutputMode
+  }
+  timestamp: number
+}
 
 /**
  * 浠诲姟缁撴灉鑱斿悎绫诲瀷