Skip to content

usage.md

Latest commit

 

History

History
219 lines (136 loc) · 7.66 KB

usage.md

File metadata and controls

219 lines (136 loc) · 7.66 KB

产品使用文档

1. 功能总览

Lumina 是一款数据可视化与协作平台，核心模块包括：

  • 数据源：连接外部数据存储（MySQL 等）。
  • 数据集：基于数据源抽取字段、建立度量与维度。
  • 视图：基于数据集进行图表建模与展示。
  • 仪表盘：将多个视图编排布局、配置筛选并分享订阅。
  • 通知：定义消息渠道（邮件等）。
  • 订阅：按计划生成并发送仪表盘快照或视图结果。
  • 组织与成员：多组织与角色权限管理。

2. 数据源（Datasource）

用途：连接数据库或外部数据系统，提供原始数据表。

常见操作：

  1. 新建数据源：填写连接信息（主机、端口、库名、账号、密码）。
  2. 测试连接：保存前点击“测试连接”。
  3. 同步元数据：成功连接后可浏览库/模式/表与字段。

注意事项：

  • 数据源层面仅做连接与元数据读取，不做业务计算。
  • 连接信息可通过环境变量模板统一管理敏感信息。

3. 数据集（Dataset）

用途：在数据源表之上进行字段建模与轻量预处理，沉淀复用的“分析数据模型”。

常见操作：

  1. 从表生成数据集：在“选择数据源与数据表”后自动识别字段类型（维度/度量）。
  2. 字段编辑：支持重命名、表达式（简单计算）、是否参与维度/度量。
  3. 预览数据：快速查看样例数据，验证字段类型。

最佳实践：

  • 将公共筛选字段（如“日期”“地区”）统一在数据集中声明，利于视图与仪表盘复用。

4. 视图（View）

用途：基于单个数据集创建一个图表/表格等可视组件。

常见操作：

  1. 选择数据集，选择图表类型（折线、柱状、饼图、表格等）。
  2. 绑定维度/度量字段，配置筛选与排序。
  3. 保存视图，可在仪表盘中复用。

注意事项：

  • 视图支持独立预览与只读访问（可结合 Token）。

5. 仪表盘（Dashboard）

用途：将多个视图编排在统一画布中，配置全局筛选、主题与交互，面向分享与订阅。

常见操作：

  1. 新建仪表盘：填写名称与描述。
  2. 添加视图：从已有视图选择，或在仪表盘内创建并添加。
  3. 布局与样式：拖拽调整位置与大小，配置背景与主题色。
  4. 全局筛选：为多个组件绑定统一筛选器（时间范围、维度值等）。
  5. 分享预览：生成公开或签名链接（需 PREVIEW_TOKEN_SECRET）。

FAQ：

  • 仪表盘公开访问需其可见性为 public；组织内分享可使用签名链接（org 范围）。

6. 通知（Notification）

用途：配置消息通道，如邮件，用于发送订阅结果。

常见操作：

  1. 配置邮件发件人（.env.local 中 MAIL_*）。
  2. 在订阅中选择该通知方式作为发送通道。

7. 订阅（Subscription）

用途：按计划截取仪表盘图像/导出结果，并通过通知通道发送给收件人。

常见操作：

  1. 新建订阅：选择目标（仪表盘/视图）、调度频率（如每日 9:00）。
  2. 渲染设置：是否隐藏全局筛选器、页面尺寸等。
  3. 发送对象：选择组织成员或填写邮件地址。

注意事项：

  • 需要 Redis 与 RabbitMQ 正常运行以调度任务与队列消费。

8. 组织与成员管理（Organization & Members）

用途：多人协作与权限边界管理。

常见操作：

  1. 邀请成员：发送邀请邮件或分享邀请链接。
  2. 管理成员：查看成员列表、变更角色、移除成员。

9. 权限与角色（RBAC）

角色分级（示例）：

  • 管理员（ADMIN）：读写组织全部资源，管理成员与权限。
  • 编辑者（EDITOR）：读写自己与被授权资源。
  • 访客（VIEWER）：只读访问被授权资源。

资源权限：

  • 数据源、数据集、视图、仪表盘、通知、订阅均支持可见性与读写控制。
  • 支持批量授权/回收（在权限面板中进行）。

10. 快速操作指引

新建仪表盘：

  1. 进入“仪表盘列表” → “新建仪表盘”。
  2. 添加已有视图或现场创建视图。
  3. 配置布局与全局筛选 → 保存 → 分享或订阅。

邀请成员：

  1. 打开“组织与成员” → “邀请成员”。
  2. 选择角色并发送邀请链接/邮件。

编辑权限：

  1. 在任一资源详情页打开“权限设置”。
  2. 选择成员/角色并设置访问或编辑权限。

11. 支持的数据源

当前版本支持以下数据源类型（按字母序）：

  • ClickHouse：host、port、database、user、password
  • Elasticsearch（essearch）：endpoint、index、auth（如有）
  • MongoDB：uri 或 host、port、database、auth（如有）
  • MSSQL（SQL Server）：host、port、database、user、password
  • MySQL：host、port、database、user、password
  • Oracle：host、port、serviceName/tns、user、password
  • PostgreSQL：host、port、database、user、password

使用建议：

  • 优先创建“只读账号”，最小权限原则。
  • 若网络隔离，需为服务端开放到目标数据库的访问白名单。
  • 新增的数据源保存后可“同步元数据”获取 schema/表/字段。

12. 通知渠道

内置可用的通知方式：

  • 邮件（Email）：使用 .env.local 的 MAIL_* 配置，支持 SSL/TLS、发件人签名。
  • 钉钉机器人（DingTalk Robot）：Webhook 方式。
  • 企业协作：Slack（Webhook 或 Bot Token+Channel）、飞书 Lark（Webhook）、Discord（Webhook）。
  • Telegram：Bot Token + chat_id。

预留类型（需扩展或接入第三方网关）：

  • 短信（SMS）、电话通知（Phone Call）。

发送内容支持：

  • 文本消息（所有渠道）
  • 图片/截图（部分渠道，如邮件、Slack Bot、Discord、飞书 Webhook 以图片 URL）

13. 快速上手（详细）

目标：10 分钟完成“数据源 → 数据集 → 视图 → 仪表盘 → 分享/订阅”。

前提准备：已启动服务、完成组织初始化，且账号具备创建权限（ADMIN/EDITOR）。

步骤：

  1. 创建数据源
  • 进入“数据源” → “新建数据源”。
  • 选择类型（如 MySQL），填写 host/port/database/user/password。
  • 点击“测试连接”通过后保存；如需从内网访问，请检查网络与白名单。
  1. 从表生成数据集
  • 在“数据集” → “新建数据集”。
  • 选择数据源与表（可选 schema），系统会自动识别字段类型。
  • 如需调整，将关键维度（如日期、地区）设为维度，数值设为度量；保存。
  1. 创建视图（图表）
  • 进入“视图” → “新建视图”。
  • 选择数据集与图表类型（折线/柱状/饼图/表格等）。
  • 绑定维度/度量，设置排序与筛选，预览无误后保存。
  1. 组装仪表盘
  • 在“仪表盘列表” → “新建仪表盘”。
  • 添加多个视图，拖拽调整布局；在“全局筛选”中配置时间/地区等通用筛选。
  • 保存后，可在预览页验证交互效果。
  1. 分享/预览
  • 打开“分享”并按需选择：公开（public）或签名链接（org 范围 + 有效期）。
  • 需配置 PREVIEW_TOKEN_SECRET 才能签发组织范围签名链接。
  1. 订阅（可选）
  • 在“订阅”中新建订阅：选择目标“仪表盘”，设置频率（如工作日 09:00）。
  • 选择通知渠道（如邮件），配置收件人；保存后系统将按计划生成截图并发送。

问题排查：

  • 无法连接数据库：检查主机/端口/账号密码/白名单；容器环境请核对网络。
  • 列表为空或字段缺失：在数据源页执行“同步元数据”，或核对账号权限。
  • 签名链接不可用：确认 PREVIEW_TOKEN_SECRET 已配置且与签发环境一致。