18.3 · 用量分析仪表盘（Usage Analytics Dashboard）

用量分析仪表盘（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/18.3-usage-analytics-dashboard

翻译时间：2026-06-09T16:12:19.721Z

翻译模型：deepseek-chat

原文字符数：8444

项目：Open WebUI (open-webui)

---

使用分析仪表盘

相关源文件

以下文件为本 wiki 页面的生成提供了上下文：

• backend/open_webui/migrations/versions/8452d01d26d7_add_chat_message_table.py
• backend/open_webui/models/chat_messages.py
• backend/open_webui/routers/analytics.py
• src/lib/apis/analytics/index.ts
• src/lib/components/admin/Analytics/AnalyticsModelModal.svelte
• src/lib/components/admin/Analytics/Dashboard.svelte
• src/lib/components/common/ChatList.svelte

使用分析仪表盘为管理员提供了系统利用率、模型性能和用户参与度的全面概览。它通过聚合聊天历史数据，可视化展示不同时间段和用户群体中的消息量、Token 消耗和模型流行度趋势。

概览与数据流

分析系统通过查询 chat_message 表来运行，该表是使用度量指标的主要数据源。该表在聊天交互过程中填充，包含每条消息的结构化信息，包括关联的模型、用户和 Token 使用元数据。

分析请求管道

下图展示了从前端 Dashboard 组件到后端数据库的流程：

分析数据检索流程

graph TD
    subgraph "前端_SvelteKit"
        A["Dashboard.svelte"] -- "调用 API" --> B["lib/apis/analytics/index.ts"]
        B -- "GET /analytics/summary" --> C["Analytics_API_Router"]
    end

    subgraph "后端_FastAPI"
        C -- "调用" --> D["routers/analytics.py:get_summary"]
        D -- "查询" --> E["models/chat_messages.py:ChatMessages"]
        E -- "SQL SELECT" --> F[("SQL_数据库: chat_message_table")]
    end

    F -- "行数据" --> E
    E -- "聚合字典" --> D
    D -- "SummaryResponse (Pydantic)" --> C
    C -- "JSON 响应" --> B
    B -- "响应式状态更新" --> A

来源： src/lib/components/admin/Analytics/Dashboard.svelte:97-141, backend/open_webui/routers/analytics.py:153-177, src/lib/apis/analytics/index.ts:127-163

---

数据模型与持久化

分析功能由 ChatMessage 模型驱动。与将整个对话存储为大型 JSON 块的旧版 chat 表不同，chat_message 表将这些数据扁平化，以便高效查询和索引。

ChatMessage 模式

该模式包含针对分析优化的特定字段：

• model_id：用于按模型的用量统计 backend/open_webui/models/chat_messages.py:73。
• user_id：用于按用户的活动追踪 backend/open_webui/models/chat_messages.py:62。
• usage：以 JSON 对象形式存储 Token 计数（输入、输出、总计）backend/open_webui/models/chat_messages.py:86。
• created_at：BigInteger 时间戳，用于时间序列过滤 backend/open_webui/models/chat_messages.py:89。

数据库索引

为确保仪表盘在数百万条消息下仍能保持响应，系统使用了复合索引：

• chat_message_model_created_idx：(model_id, created_at)，用于按模型的时间范围查询 backend/open_webui/models/chat_messages.py:94。
• chat_message_user_created_idx：(user_id, created_at)，用于用户随时间变化的活动 backend/open_webui/models/chat_messages.py:95。

规范化与迁移

系统包含一个 Alembic 迁移脚本，可从现有 chat JSON 块回填 chat_message 表。它提取消息历史，通过 _normalize_timestamp 逻辑规范化时间戳，并处理批量插入，同时提供逐行回退处理，以确保升级期间的数据完整性 backend/open_webui/migrations/versions/8452d01d26d7_add_chat_message_table.py:27-55。

来源： backend/open_webui/models/chat_messages.py:56-96, backend/open_webui/migrations/versions/8452d01d26d7_add_chat_message_table.py:58-201, backend/open_webui/models/chat_messages.py:27-42

---

后端实现

分析逻辑封装在 open_webui/routers/analytics.py 中。它为不同的仪表盘组件提供了多个专用端点。

关键 API 端点

端点	函数	描述
/summary	get_summary	返回消息、聊天、模型和用户的总计数 backend/open_webui/routers/analytics.py:153。
/models	get_model_analytics	按模型聚合消息计数 backend/open_webui/routers/analytics.py:56。
/users	get_user_analytics	按用户聚合消息计数和 Token 使用量 backend/open_webui/routers/analytics.py:75。
/daily	get_daily_stats	提供图表的时间序列数据（按小时或天粒度）backend/open_webui/routers/analytics.py:189。
/tokens	getTokenUsage	返回按模型划分的详细 Token 消耗指标 src/lib/apis/analytics/index.ts:205。

聚合逻辑

后端使用 SQLAlchemy 的 func 模块执行服务器端聚合。例如，get_summary 调用 ChatMessages 表类的多个辅助方法，以计算特定 start_date 和 end_date 窗口内的总计 backend/open_webui/routers/analytics.py:162-177。使用数据在存储或处理前通过 get_usage 进行规范化，该函数从消息负载中提取 Token backend/open_webui/models/chat_messages.py:45-48。

来源： backend/open_webui/routers/analytics.py:20-210, backend/open_webui/models/chat_messages.py:131-206

---

前端组件

仪表盘使用 Svelte 组件构建，这些组件根据用户筛选条件（时间段和用户组）进行响应式更新。

组件层次结构与实体映射

graph TD
    subgraph "管理_分析_视图"
        Main["Dashboard.svelte"] --> Summary["摘要统计"]
        Main --> Chart["ChartLine.svelte"]
        Main --> Lists["用户/模型表格"]
        Main --> Modal["AnalyticsModelModal.svelte"]
    end

    subgraph "代码_实体_空间"
        DashID["Dashboard.svelte"]
        ChartID["ChartLine.svelte"]
        ModalID["AnalyticsModelModal.svelte"]
        API_Call["lib/apis/analytics/index.ts"]
        ChatListID["lib/components/common/ChatList.svelte"]
    end

    Main -- "状态管理" --> DashID
    Chart -- "可视化" --> ChartID
    Modal -- "下钻" --> ModalID
    DashID -- "数据获取" --> API_Call
    ModalID -- "渲染对话" --> ChatListID

仪表盘功能

1. 时间段选择：用户可按 24 小时、7 天、30 天、90 天或全部时间筛选数据。此选择会持久化到 localStorage src/lib/components/admin/Analytics/Dashboard.svelte:25-33。
2. 用户组筛选：管理员可通过 getGroups 获取的特定用户组来筛选所有分析数据 src/lib/components/admin/Analytics/Dashboard.svelte:37。
3. 可视化：

• 时间序列图表：ChartLine.svelte 渲染各模型的消息趋势 src/lib/components/admin/Analytics/Dashboard.svelte:15。
• 使用表格：模型和用户表格支持按消息计数、名称或 Token 使用量排序 src/lib/components/admin/Analytics/Dashboard.svelte:157-181。

模型下钻

点击模型会打开 AnalyticsModelModal.svelte。该组件提供：

• 概览标签页：使用 ModelActivityChart.svelte 显示反馈活动（赞/踩）以及胜负历史 src/lib/components/admin/Analytics/AnalyticsModelModal.svelte:195-226。
• 聊天标签页：使用 ChatList.svelte 列出与该模型关联的单个聊天。如果全局配置中启用了 enable_admin_chat_access，管理员可以审计特定对话 src/lib/components/admin/Analytics/AnalyticsModelModal.svelte:181-190。

来源： src/lib/components/admin/Analytics/Dashboard.svelte:1-191, src/lib/components/admin/Analytics/AnalyticsModelModal.svelte:1-155, src/lib/components/common/ChatList.svelte:1-28