Magic BI - 智能数据分析平台
目录
项目简介
Magic BI 是一个轻量化、易部署、高可用的单体智能数据分析平台，支持：
自然语言转 SQL (NL2SQL)- 专业 SQL 编辑器与执行
- 多类型数据可视化
- 完善的权限管理
- 审计日志追踪
- 数据源管理（支持 SQLite、MySQL、PostgreSQL、ClickHouse 等）
- 知识图谱可视化
- 报表管理与保存
- 会话式数据分析
无需复杂的分布式组件，一个单台服务器即可运行，开箱即用，特别适合中小企业和内部数据分析场景。
核心功能
1. 
认证与权限管理
- 用户管理：完整的用户 CRUD 功能
- 角色管理：灵活的角色定义与权限配置
- JWT 认证：安全的 Token 认证机制
- 细粒度权限控制：基于角色的权限访问控制 (RBAC)
- 权限菜单控制：根据权限动态显示/隐藏菜单
2. 
数据源管理
- 多数据源支持：
- SQLite（本地文件，默认）
- MySQL / MariaDB
- PostgreSQL
- ClickHouse
- Oracle
- Doris
- 连接测试：快速测试数据源可用性
- 元数据自动采集：自动采集表结构、字段、索引信息
- 表结构浏览：直观查看表结构和示例数据
- 数据源详情页：完整的数据源信息展示
3. 
智能对话查询
- 自然语言转 SQL：用中文描述你的数据问题，AI 自动生成 SQL
- 智能意图识别：自动识别用户的查询意图（趋势分析、统计排名、对比分析等）
- 对话式分析：像聊天一样进行数据分析
- 会话管理：支持创建、查看、删除对话会话
- SQL 历史记录：完整的 SQL 执行历史记录
- 直接执行 SQL：支持
执行 sql、执行sql、/sql前缀直接执行 - 可视化渲染：自动根据数据特点推荐并渲染合适的图表
- 无全局 Loading：对话执行时不会被遮罩阻挡，提升用户体验
4. 
SQL 专业工作台
- 专业编辑器：支持 SQL 语法高亮
- SQL 格式化：内置 SQL 格式化功能
- 执行历史：完整的 SQL 执行历史，支持查看、搜索、删除
- 结果可视化：支持多种图表类型展示查询结果
- 导出功能：支持将查询结果导出为 CSV
- 图表配置：灵活的图表配置与自定义
- 保存为报表：一键保存查询和图表配置为报表
- 无全局 Loading：SQL 执行时不会被遮罩阻挡
- 快捷键支持：F5 快速执行查询
5. 
报表管理
- 报表创建：快速创建数据报表
- 报表保存：保存 SQL 查询和图表配置
- 报表编辑：修改现有报表内容
- 报表列表：浏览和管理所有报表
- 报表预览：预览报表内容和图表
6. 
知识图谱
- 数据关系可视化：以图的形式展示表、字段、数据库之间的关系
- 节点类型区分：不同颜色代表不同类型的节点（表、字段、数据库等）
- 交互式探索：点击选中、缩放浏览、拖拽移动
- 图元展示：节点、边、标签、图例
7. 审计日志
- 完整操作记录：记录所有用户操作
- 操作详情：详细记录操作路径、方法、参数
- IP 地址追踪：记录操作的 IP 来源
- 时间筛选：按时间范围筛选审计记录
- 操作类型筛选：按操作类型筛选日志
- 安全审计：用于安全审计和问题追踪
8. 系统设置
- 用户管理：系统用户增删改查
- 角色管理：角色定义与权限配置
- 模型配置：AI 模型相关配置
- 同步任务：元数据同步任务管理
技术架构
架构特点
- 单体应用架构：前后端分离部署，但架构简单，无需分布式依赖
- 分层设计：清晰的层次结构，易于维护和扩展
- 模块化架构：功能模块化，便于独立开发和测试
- RESTful API：标准的 REST API 设计
系统层次
┌─────────────────────────────────────────────────────────────┐
│ 前端层 (Frontend) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 页面组件 │ │ 公共组件 │ │ 辅助模块 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Vue 3 + TypeScript + Vite │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
│ HTTP/REST
│
┌─────────────────────────────────────────────────────────────┐
│ 后端层 (Backend) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ API 路由层 │ │
│ │ (auth, chat, sql, datasource, report, audit, etc.) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 中间件层 │ │
│ │ (auth, permission, audit, rate_limit, csrf, etc.) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 业务服务层 │ │
│ │ (auth, chat, sql, datasource, report, audit, etc.) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AI Agent 层 │ │
│ │ (intent, metadata, sql, visualization, knowledge) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 数据访问层 (ORM) │ │
│ │ SQLAlchemy │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
│
┌─────────────────────────────────────────────────────────────┐
│ 数据存储层 │
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ 平台数据库 │ │ 业务数据源 │ │
│ │ (SQLite/MySQL) │ │ (SQLite/MySQL/PostgreSQL/...)│ │
│ └──────────────────┘ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
│
┌─────────────────────────────────────────────────────────────┐
│ 外部服务层 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ DeepSeek LLM API (大模型服务) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
后端架构设计
采用经典的 分层架构，各层次职责清晰：
backend/
├── app/
│ ├── api/ # API 路由层
│ │ └── v1/ # API v1 版本
│ ├── core/ # 核心配置层
│ │ ├── config.py # 配置管理
│ │ ├── database.py # 数据库连接
│ │ └── security.py # 安全相关（密码、Token）
│ ├── models/ # 数据模型层
│ ├── services/ # 业务服务层
│ ├── agents/ # AI Agent 层（核心智能逻辑）
│ │ ├── intent_agent.py # 意图识别
│ │ ├── metadata_agent.py # 元数据管理
│ │ ├── sql_agent.py # SQL 生成与验证
│ │ ├── visualization_agent.py # 可视化执行与图表推荐
│ │ └── knowledge_graph.py # 知识图谱生成
│ ├── adapters/ # 数据源适配器
│ │ └── sql_dialect/ # SQL 方言适配
│ └── middleware/ # 中间件层
│ ├── auth_middleware.py
│ ├── permission_middleware.py
│ ├── audit_middleware.py
│ ├── rate_limit_middleware.py
│ └── csrf_middleware.py
└── main.py # 应用入口
前端架构设计
采用 Vue 3 组件化架构：
frontend/src/
├── components/ # 公共组件
│ ├── HelpGuide.vue # 帮助指南
│ ├── Layout.vue # 布局组件
│ └── settings/ # 设置相关组件
├── views/ # 页面组件
│ ├── Login.vue
│ ├── Dashboard.vue
│ ├── Chat.vue
│ ├── SqlEditor.vue
│ ├── Datasource.vue
│ ├── DatasourceDetail.vue
│ ├── Report.vue
│ ├── DashboardDetail.vue
│ ├── AuditLog.vue
│ ├── KnowledgeGraph.vue
│ └── Settings.vue
├── router/ # 路由配置
├── store/ # 状态管理
├── utils/ # 工具函数
│ ├── api.ts # API 封装
│ ├── request.ts # 请求封装（含全局 Loading）
│ ├── auth.ts # 认证工具
│ └── format.ts # 格式化工具
├── App.vue
└── main.ts
技术选型
后端技术栈
| 技术 | 版本 | 用途 | 优势 |
|---|---|---|---|
| Python | 3.11+ | 主要开发语言 | 生态丰富、AI 工具链完善 |
| FastAPI | 0.100+ | Web 框架 | 高性能、自动文档、类型提示 |
| SQLAlchemy | 2.0+ | ORM 框架 | Python 最强大的 ORM，支持多种数据库 |
| Pydantic | 2.0+ | 数据验证 | 强大的数据验证和序列化 |
| Python-JOSE | 3.3+ | JWT 处理 | 完整的 JWT 支持 |
| Passlib | 1.7+ | 密码加密 | 安全的密码哈希 |
| Uvicorn | 0.23+ | ASGI 服务器 | 高性能 ASGI 服务器 |
| MySQLdb / PyMySQL | MySQL 连接 | Python MySQL 驱动 | |
| psycopg2-binary | PostgreSQL 连接 | PostgreSQL 驱动 | |
| SQLite | 默认数据库 | 零配置，开箱即用 | |
| Redis | 限流、缓存 | 高性能 KV 存储（可选） | |
| Celery | 异步任务 | 分布式任务调度（可选） |
前端技术栈
| 技术 | 版本 | 用途 | 优势 |
|---|---|---|---|
| Vue 3 | 3.4+ | 前端框架 | Composition API、性能优越 |
| TypeScript | 5.3+ | 类型系统 | 类型安全、更好的 IDE 支持 |
| Vite | 5.0+ | 构建工具 | 极速开发体验、热更新 |
| Element Plus | 2.4+ | UI 组件库 | 丰富的组件、完善的中文文档 |
| Vue Router | 4.2+ | 路由管理 | 官方路由、完美配合 Vue 3 |
| Pinia | 2.1+ | 状态管理 | Vue 3 官方推荐、简洁易用 |
| ECharts | 5.4+ | 图表库 | 功能最强大的开源图表库 |
| Monaco Editor | 0.52+ | 代码编辑器 | VS Code 同款编辑器、功能强大 |
| Axios | 1.6+ | HTTP 客户端 | 成熟的 HTTP 库、拦截器支持 |
| sql-formatter | 13.1+ | SQL 格式化 | SQL 代码美化 |
| Vitest | 4.1+ | 单元测试 | 现代化的 Vue 测试工具 |
AI 服务
| 服务 | 用途 | 特点 |
|---|---|---|
| DeepSeek API | NL2SQL、智能分析 | 性价比高、中文理解优秀 |
功能创新点
1. 
Agent 化的智能分析系统
不同于传统 BI 工具，Magic BI 采用 多 Agent 协同架构：
用户问题
↓
【意图识别 Agent】 分析用户查询意图
↓
【元数据 Agent】 准备表结构上下文
↓
【SQL 生成 Agent】 生成并验证 SQL
↓
【可视化 Agent】 执行并推荐图表
↓
结果展示
- 意图识别：自动识别趋势分析、统计排名、对比分析等意图
- 上下文感知：自动注入当前数据源的表结构信息
- SQL 安全验证：自动拦截危险操作（DROP、ALTER、DELETE 等）
- 智能可视化：根据数据特征推荐最合适的图表类型
2. 
会话式数据分析
- 自然语言交互：像聊天一样问问题，不用写 SQL
- 会话上下文：保留对话历史，连贯分析
- 混合交互模式：支持自然语言和直接 SQL 执行结合
3. 
灵活的可视化系统
- 多种图表类型：
- 柱状图、折线图、饼图、散点图
- 热力图、雷达图、漏斗图、仪表盘
- 知识图谱可视化
- 表格视图
- 智能图表推荐：根据数据特征自动推荐图表类型
- 灵活配置：支持自定义图表配置、颜色、尺寸
4. 
完善的安全机制
- SQL 安全校验：自动拦截危险 SQL 操作
- JWT 认证：安全的认证机制
- 权限控制：细粒度的 RBAC 权限管理
- 审计日志：完整的操作记录和追踪
- CSRF 防护：跨站请求伪造防护
- 速率限制：防暴力攻击和滥用
5. 
多数据源适配
- 方言适配器模式：统一的接口，适配不同 SQL 方言
- 元数据采集：自动采集表结构、字段、索引
- 数据源管理：统一管理多个数据源
6. 
用户友好的体验设计
- 帮助引导系统：内置操作引导和帮助文档
- 响应式设计：支持移动端、平板端、桌面端
- 全局 Loading 优化：对话和 SQL 执行时不被遮罩阻挡
- 美观的 UI：现代化的 UI 设计
7. 知识图谱可视化
- 关系可视化：直观展示表、字段、数据库之间的关系
- 交互式探索：点击选中、缩放浏览、拖拽移动
- 关系发现：帮助用户理解数据之间的关联
项目结构
完整项目目录
MagicBI/
├── backend/ # 后端代码
│ ├── app/
│ │ ├── adapters/
│ │ │ └── sql_dialect/ # SQL 方言适配
│ │ ├── agents/ # AI Agent 层
│ │ │ ├── intent_agent.py
│ │ │ ├── metadata_agent.py
│ │ │ ├── sql_agent.py
│ │ │ ├── visualization_agent.py
│ │ │ ├── knowledge_graph.py
│ │ │ └── protocol_adapter.py
│ │ ├── api/
│ │ │ └── v1/ # API v1
│ │ ├── core/ # 核心配置
│ │ ├── middleware/ # 中间件
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务服务
│ │ └── utils/ # 工具函数
│ ├── alembic/ # 数据库迁移
│ ├── main.py # 应用入口
│ ├── requirements.txt # 依赖包
│ └── .env.example # 环境变量示例
├── frontend/ # 前端代码
│ ├── src/
│ │ ├── components/ # 组件
│ │ ├── views/ # 页面
│ │ ├── router/ # 路由
│ │ ├── store/ # 状态管理
│ │ ├── utils/ # 工具
│ │ ├── App.vue
│ │ └── main.ts
│ ├── tests/ # 测试
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ └── vitest.config.ts
├── docs/ # 文档
├── magicbi_venv/ # 虚拟环境（可选）
└── README.md
快速开始
前置要求
- Python 3.11+
- Node.js 18+
- npm 9+
后端启动
1. 进入后端目录
cd backend
2. 安装依赖
# 使用虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置你的 DeepSeek API Key
主要配置项：
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=120
DEEPSEEK_API_KEY=your-deepseek-api-key-here
DATABASE_URL=sqlite:///./bi_platform.db
4. 启动服务
python main.py
后端将在 http://localhost:8000 启动
API 文档地址：http://localhost:8000/docs
前端启动
1. 进入前端目录
cd frontend
2. 安装依赖
npm install
3. 启动开发服务
npm run dev
前端将在 http://localhost:5173 启动
4. 构建生产版本
npm run build
构建产物在 dist/ 目录下
部署指南
Docker 部署（推荐）
虽然目前没有官方 Docker 镜像，但项目结构很容易容器化。
传统部署
后端部署
# 使用 Gunicorn + Uvicorn
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000
前端部署
构建后使用 Nginx 或类似 Web 服务器部署。
Nginx 配置示例：
server {
listen 80;
server_name your-domain.com;
location / {
root /path/to/frontend/dist;
try_files $uri $uri/ /index.html;
}
location /api {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
开发文档
API 设计
主要 API 端点：
| 端点 | 方法 | 说明 |
|---|---|---|
/api/v1/auth/login |
POST | 用户登录 |
/api/v1/auth/logout |
POST | 用户登出 |
/api/v1/chat/query |
POST | 智能对话查询 |
/api/v1/sql/execute |
POST | 执行 SQL |
/api/v1/datasource/ |
GET/POST/PUT/DELETE | 数据源管理 |
/api/v1/report/ |
GET/POST/PUT/DELETE | 报表管理 |
/api/v1/audit/ |
GET | 审计日志 |
/api/v1/user/ |
GET/POST/PUT/DELETE | 用户管理 |
/api/v1/role/ |
GET/POST/PUT/DELETE | 角色管理 |
开发约定
- 代码风格：遵循 PEP 8（Python）和 ESLint（JavaScript）
- Git 提交：遵循 Conventional Commits 规范
- 测试：重要功能需要单元测试
- 文档：新功能需要更新文档
默认账号
| 角色 | 用户名 | 密码 | 权限 |
|---|---|---|---|
| 超级管理员 | admin |
admin123 |
全部权限 |
首次登录后建议立即修改默认密码。
更新日志
v1.0.0 (2024-04)
首个正式版本发布- 智能对话查询功能
- SQL 专业工作台
- 数据源管理
- 报表管理
- 知识图谱可视化
- 审计日志
- 用户权限管理
- 全局 Loading 优化
- SQL 历史记录功能
- 帮助引导系统
贡献指南
欢迎提交 Issue 和 Pull Request！
许可证
MIT License
支持与联系
如有问题，欢迎提交 Issue。
Magic BI - 让数据分析变得简单、有趣！ 
