# analyticsSys

**Repository Path**: dywen2172/analyticsSys

## Basic Information

- **Project Name**: analyticsSys
- **Description**: xxx
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# analyticsSys

企业级智能数据分析系统，将自然语言提问转化为可执行的数据查询、图表结果与分析能力。围绕 ChatBI / Text-to-SQL / RAG / 嵌入式助手 / 数据源治理构建的完整平台。

## 功能概览

- 管理员配置大模型、数据源、权限、工作空间和嵌入式助手
- 业务用户通过聊天进行问数、看图、导出结果、追问分析和预测
- 通过术语库、数据训练、表结构注释、历史样例等上下文提升 SQL 生成质量
- 支持内置 Web 界面和嵌入页面 / MCP 接口两种使用方式

## 功能模块

### 智能问数 (ChatBI)

对应代码：`backend/apps/chat`、`frontend/src/views/chat`

- 自然语言提问触发问答流程
- 大模型生成 SQL → 执行查询 → 组织图表数据 → 流式返回前端
- 重新生成、推荐问题、结果分析、预测数据
- 导出查询结果为 Excel
- 返回内容涵盖：SQL 执行结果、图表配置与图片、分析/预测结果、执行日志与使用量

### 数据源接入与元数据治理

对应代码：`backend/apps/datasource`、`frontend/src/views/ds`

- 数据源连接管理（新增、编辑、删除、连通性检测）
- 拉取数据表和字段信息
- 选取可供问答使用的表
- 数据预览
- 维护表注释、字段注释、字段权限
- Excel/CSV 导入 PostgreSQL
- 导出/导入数据源 schema 注释模板

### 术语库与数据训练

对应代码：`backend/apps/terminology`、`backend/apps/data_training`

- 维护业务术语、别名、概念映射
- 存储训练样本与校准数据
- 结合 embedding 检索为提示词和上下文构造提供辅助
- 系统启动时自动补齐 embedding 数据

### 仪表板与可视化编辑

对应代码：`backend/apps/dashboard`、`frontend/src/views/dashboard`

- Dashboard 浏览与管理
- 画布式编辑器
- 图表预览与组件化渲染
- 聊天问答结果联动生成图表

### 嵌入式助手与外部集成

对应代码：`backend/apps/system/api/assistant.py`、`frontend/src/views/system/embedded`、`frontend/src/views/embedded`

- 为不同业务域创建嵌入式助手应用
- 限制助手可访问的数据范围和域名来源
- 自定义嵌入 UI（logo、浮标图标等）
- 独立嵌入页面、预览页和 token 校验

### MCP 集成接口

对应代码：`backend/apps/mcp/mcp.py`、`main.py`（`FastApiMCP`）

- 启动会话
- 查询工作空间
- 获取数据源列表
- 发起问答
- 调用外部助手

### 系统管理与安全控制

对应代码：`backend/apps/system`、前端 `system` / `set` 路由

- 登录认证与 token 鉴权
- 用户、成员、工作空间管理
- AI 模型配置
- 参数配置与系统变量
- 平台接入与认证方式配置
- API Key 管理
- 审计日志
- 工作空间隔离、角色权限、按资源授权、嵌入域名校验

## 技术架构

### 整体结构

前后端分离 + 辅助渲染服务：

| 模块 | 说明 |
|------|------|
| `frontend` | Vue 3 + TypeScript 单页应用 |
| `backend` | FastAPI + SQLModel + Alembic 主业务服务 |
| `g2-ssr` | Node.js 图表服务端渲染服务 |
| `installer` | 安装与运维脚本 |
| `tests` | 供应商配置与模型连通性测试 |

运行时服务端口：

| 端口 | 服务 |
|------|------|
| 8000 | 主 Web / API 服务 |
| 8001 | MCP 服务 |
| 3000 | G2 SSR 图表渲染服务 |

系统数据库为 PostgreSQL，容器镜像内集成了本地 PostgreSQL 启动流程。

### 后端

入口：`backend/main.py`

- 基于 FastAPI
- `lifespan` 启动逻辑自动执行 Alembic 迁移
- 启动时初始化缓存、动态 CORS、embedding 数据
- API 文档支持多语言占位符替换
- 中间件统一处理 token、响应包装、请求上下文
- 同时挂载标准 API 和 MCP Server

路由聚合：`backend/apps/api.py`（登录与用户、工作空间、助手应用、AI 模型、设置项、术语库、数据训练、数据源、聊天问答、仪表板、MCP、参数与变量）

### 大模型与 RAG

模型工厂：`backend/apps/ai_model/model_factory.py`

支持的模型协议：

- OpenAI 协议兼容模型
- vLLM / OpenAI 兼容模型
- Azure OpenAI

已适配的模型供应商：阿里云百炼、千帆、DeepSeek、腾讯混元、讯飞星火、Gemini、OpenAI、Kimi、腾讯云、火山引擎、MiniMax、通用 OpenAI 兼容接口

RAG 能力：

- 术语 embedding
- 数据训练 embedding
- 表和数据源 embedding
- 结合表结构、样例 SQL、业务术语进行上下文增强

### 数据层

系统库：PostgreSQL，配置见 `backend/common/core/config.py`

支持的外部数据源：PostgreSQL、MySQL、Oracle、SQL Server、ClickHouse、Doris、StarRocks、Kingbase、DM、Redshift、Elasticsearch、Excel/CSV

Schema 迁移：Alembic，版本脚本位于 `backend/alembic/versions`

### 前端

技术栈：Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、Vue I18n、AntV G2 / S2 / X6、TinyMCE

路由结构（`frontend/src/router/index.ts`）：

| 路由域 | 说明 |
|--------|------|
| `chat` | 数据问答 |
| `dashboard` | 仪表板与编辑器 |
| `set` | 工作空间内配置（成员、权限、术语、训练、Prompt） |
| `system` | 全局管理（用户、模型、嵌入、系统参数、认证、平台、审计） |
| `assistant` / `embeddedPage` | 外部嵌入场景 |

### 图表 SSR 服务

独立 Node.js 服务，入口：`g2-ssr/app.js`

- 接收图表类型、坐标轴和数据
- 调用 `@antv/g2-ssr` 渲染图片
- 输出图表文件供问答或嵌入场景引用
- 支持前端可交互图表和服务端静态图像两种输出方式

## 部署

### Docker

根目录文件：`Dockerfile`、`docker-compose.yaml`、`start.sh`

容器启动顺序：

1. PostgreSQL
2. `g2-ssr` 服务
3. MCP 服务（端口 8001）
4. 主服务（端口 8000）

`docker-compose.yaml` 默认挂载目录：

- `data/sqlbot/excel`
- `data/sqlbot/file`
- `data/sqlbot/images`
- `data/sqlbot/logs`
- `data/postgresql`

### 本地开发

环境要求：

- Python 3.11
- Node.js
- PostgreSQL

启动步骤：

1. 启动 PostgreSQL
2. `backend` 目录安装依赖，运行 `uvicorn main:app --reload`
3. （可选）启动 MCP 服务：`uvicorn main:mcp_app --port 8001`
4. `g2-ssr` 目录安装依赖，启动图表渲染服务
5. `frontend` 目录安装依赖，运行 Vite 开发服务器

## 目录结构

```
analyticsSys/
├─ backend/        FastAPI 后端、业务模块、数据库迁移
├─ frontend/       Vue 3 前端
├─ g2-ssr/         G2 图表服务端渲染服务
├─ installer/      安装、卸载、运维脚本
├─ docs/           文档
├─ tests/          测试用例
├─ docker-compose.yaml
├─ Dockerfile
└─ start.sh
```

## License

请参阅 [LICENSE](LICENSE)。