# AI-QuerySystem
**Repository Path**: leitao2000/AI-QuerySystem
## Basic Information
- **Project Name**: AI-QuerySystem
- **Description**: AI驱动的自然语言查询系统 - 支持自然语言转SQL查询
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-07-25
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# AI 智能问数系统
一个基于大语言模型（LLM）的智能数据分析系统，支持自然语言查询数据库、可视化看板、权限管理、自动更新等功能。开箱即用，无需编写 SQL，用中文自然语言即可与数据库对话。
[](version.json)
[](LICENSE)
[](https://www.python.org/)
[](https://nodejs.org/)
---
## 目录
- [功能特性](#功能特性)
- [设计预览](#设计预览)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [环境要求](#环境要求)
- [源码运行](#源码运行)
- [EXE 安装包](#exe-安装包)
- [Linux 服务器部署](#linux-服务器部署)
- [使用指南](#使用指南)
- [智能查数](#智能查数)
- [模型配置](#模型配置)
- [自定义看板](#自定义看板)
- [权限管理](#权限管理)
- [纠错学习与 SQL 规则](#纠错学习与-sql-规则)
- [数据库备份](#数据库备份)
- [自动更新](#自动更新)
- [版本发布流程](#版本发布流程)
- [Webhook 自动更新](#webhook-自动更新)
- [项目结构](#项目结构)
- [API 文档](#api-文档)
- [构建说明](#构建说明)
- [Windows EXE](#windows-exe)
- [Linux 二进制](#linux-二进制)
- [常见问题](#常见问题)
- [更新日志](#更新日志)
- [许可证](#许可证)
---
## 功能特性
- 🤖 **智能查数**：用中文自然语言提问，LLM 自动生成并执行 SQL 查询，支持多轮对话追问
- 🔍 **智能表匹配**：基于中文描述的语义匹配，自动从海量表中筛选相关表，精准定位目标数据
- 📊 **可视化看板**：拖拽式布局，支持柱状图、折线图、饼图、KPI 卡片、数据表格等多种组件
- 🔄 **看板自动刷新**：设置刷新间隔，看板数据定时自动更新
- 🌐 **一键发布**：生成公开链接分享看板，外部人员无需登录即可查看
- 🛡️ **三层权限控制**：角色管理 + 表级/字段级权限 + 行级数据过滤（Row-Level Security）
- 📝 **多模型支持**：支持 DeepSeek、通义千问、Moonshot (Kimi)、豆包、智谱 GLM、MiMo 等主流大模型
- 🔧 **纠错学习**：用户可对 AI 生成的错误 SQL 进行纠正，系统记录规则后自动应用到后续查询
- 📏 **全局 SQL 规则**：可配置全局业务规则，所有查询自动注入（如数据权限过滤、合规要求等）
- 💾 **数据库备份**：一键备份/还原，支持定时自动备份与自动清理
- 🔄 **自动更新**：基于 Gitee Release 的 EXE 自动更新，无需手动下载
- 🔗 **Webhook 集成**：支持 Gitee Webhook，代码推送后自动执行更新
- 📋 **查询历史与收藏**：完整记录历史查询，支持保存为收藏模板
- 🎨 **深色主题**：统一的暗色系 UI 设计，霓虹风格视觉效果
---
## 设计预览
> 以下为基于豆包（Doubao）设计系统的 UI 设计原型，统一深色主题 + 品牌蓝 `#0065fd` 主色调。
### 主功能区
| 登录页 | 数据概览 |
|--------|----------|
| 
| 
|
| 智能查数 | 对话分析 |
|----------|----------|
| 
| 
|
| 自定义看板 | 查询历史 |
|------------|----------|
| 
| 
|
| 我的收藏 |
|----------|
| 
|
### 管理后台
| 数据源管理 | 元数据管理 |
|------------|------------|
| 
| 
|
| 权限管理 | 用户管理 |
|----------|----------|
| 
| 
|
| 审计日志 | 系统日志 |
|----------|----------|
| 
| 
|
### 系统配置
| 模型配置 | 纠错学习 |
|----------|----------|
| 
| 
|
| 全局规则 | 数据库备份 |
|----------|------------|
| 
| 
|
---
## 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| **前端** | React 18 + Vite + Ant Design 5 + ECharts | SPA 单页应用，支持代码编辑器 (CodeMirror)、拖拽布局 (react-grid-layout) |
| **后端** | Python FastAPI + SQLAlchemy + Uvicorn | RESTful API，异步架构，自动生成 OpenAPI 文档 |
| **数据库** | SQLite (系统库) + SQL Server / Oracle / MySQL (业务库) | 系统元数据存 SQLite，业务数据支持多数据库连接 |
| **打包** | PyInstaller (Windows EXE / Linux ELF) | 单文件打包，前后端合一 |
| **安装器** | Inno Setup 7 (Windows) | 图形化安装向导 |
| **容器** | Docker (跨平台构建) | Windows 上交叉编译 Linux 二进制 |
---
## 快速开始
### 环境要求
- **源码运行**：Python 3.8+ / Node.js 16+ / Git
- **EXE 运行**：Windows 7+ 即可，无需安装任何依赖
- **数据库驱动**（连接业务数据库时需要）：
- SQL Server：需安装 [ODBC Driver 17](https://learn.microsoft.com/zh-cn/sql/connect/odbc/download-odbc-driver-for-sql-server)
- Oracle：需安装 [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client.html)
### 源码运行
```bash
# 1. 克隆仓库
git clone https://gitee.com/leitao2000/AI-QuerySystem.git
cd AI-QuerySystem
# 2. 初始化数据库（安装依赖 + 创建管理员账号）
init.bat
# 3. 启动后端（端口 3000）
run-api.bat
# 4. 启动前端（端口 8000，开发模式）
run-web.bat
```
启动后访问 http://localhost:8000 ，使用默认账号登录：
- **管理员**：`admin` / `admin123`
- **演示用户**：`demo` / `demo123`
### EXE 安装包
1. 从 [Gitee Release](https://gitee.com/leitao2000/AI-QuerySystem/releases) 下载 `AI-QuerySystem-Setup.exe`
2. 运行安装程序，按向导完成安装
3. 双击桌面快捷方式启动（或从开始菜单启动）
4. 系统自动打开浏览器，使用 `admin / admin123` 登录
> **提示**：EXE 版无需安装 Python 或 Node.js，所有依赖已打包。浏览器关闭后程序自动退出。
### Linux 服务器部署
项目支持在 Windows 上交叉编译为 Linux ELF 二进制文件，并使用 systemd 管理服务：
```bash
# 1. 上传部署脚本和二进制到服务器
scp deploy-linux.sh ai-query-system root@SERVER_IP:/root/
# 2. 在服务器上执行部署
sudo bash deploy-linux.sh
```
部署后自动注册为 systemd 服务，支持开机自启。详细说明请参考 [构建说明](#linux-二进制)。
---
## 使用指南
### 智能查数
在「对话分析」页面，用自然语言描述你的查询需求，系统自动生成 SQL 并执行：
**示例问题：**
- "查询本月销售额最高的 10 个产品"
- "统计各部门近 30 天的人数变化趋势"
- "显示 3 月份各人员的不良品数量"
系统工作流程：
```
用户输入自然语言 → 智能表匹配（语义识别） → LLM 生成 SQL → 安全校验 → 执行查询 → 返回结果
```
**核心能力：**
- 基于中文描述的语义表匹配，无需记忆英文表名
- 自动处理外键关联，JOIN 后返回可读的名称而非原始 ID
- 支持多轮对话追问，保持上下文连贯
- 时间类查询自动适配当前年份（不指定年份时默认当年）
- 结果可导出为 Excel 文件
### 模型配置
在「管理后台 → 模型配置」中添加大模型：
| 供应商 | Base URL | 推荐模型 |
|--------|----------|----------|
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
| Moonshot (Kimi) | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
| 豆包 | `https://ark.cn-beijing.volces.com/api/v3` | `doubao-1.5-pro-32k` |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-plus` |
| MiMo (小米) | `https://api.xiaomimimo.com/v1` | `mimo-v2.5-pro` |
**操作步骤：**
1. 选择供应商 → 自动填充 Base URL
2. 输入 API Key
3. 选择推荐模型或手动输入
4. 点击「测试」验证连接
5. 保存配置
> **提示**：支持同时配置多个模型，查数时可自由切换。
### 自定义看板
**创建看板：**
1. 进入「自定义看板」页面，点击「创建看板」
2. 输入名称、描述
3. 设置自动刷新间隔（可选，最小 1 分钟）
4. 点击「创建」
**添加组件（编辑模式）：**
1. 进入看板 → 点击「编辑布局」
2. 点击「添加组件」
3. 选择组件类型：柱状图、折线图、饼图、KPI 卡片、数据表格等
4. 选择数据源
5. 输入 SQL 查询语句
6. 点击「预览数据」 → 「智能填充」自动配置图表字段
7. 拖拽调整大小和位置，保存组件
**发布看板：**
1. 点击「发布看板」
2. 复制生成的公开链接
3. 分享给其他人（无需登录即可查看，支持自动刷新）
### 权限管理
系统提供三层权限控制机制：
| 层级 | 说明 | 示例 |
|------|------|------|
| **表级权限** | 控制用户可见的表 | 普通用户只能看到"销售订单表"和"产品表" |
| **字段级权限** | 控制表内字段的可见/隐藏/脱敏 | "工资金额"字段设为脱敏，显示为 `****` |
| **行级过滤** | 控制用户能查看的数据行 | `department_id = current_user.dept_id` |
权限通过 **角色** 进行管理：创建角色 → 配置权限规则 → 将用户分配到角色。
### 纠错学习与 SQL 规则
**纠错管理：**
当 AI 生成的 SQL 不正确时，管理员可在「纠错管理」页面添加纠正规则：
- 记录原始问题与错误 SQL
- 提供正确的表和 SQL 示例
- 系统自动总结规则，后续类似问题优先应用
**全局 SQL 规则：**
在「SQL 规则」页面配置全局业务规则，所有查询自动注入。例如：
- 所有查询必须包含 `is_deleted = 0`（逻辑删除过滤）
- 特定表查询必须限制数据范围
- 默认排序规则
### 数据库备份
- **手动备份**：在「备份恢复」页面一键创建备份
- **定时备份**：配置自动备份间隔和保留策略
- **一键还原**：选择历史备份文件快速还原
- **自动清理**：超过保留天数或数量上限的备份自动删除
---
## 自动更新
项目支持基于 Gitee Release 的 EXE 自动更新机制，用户无需手动下载安装包即可升级到最新版本。
### 版本发布流程
**管理员发布新版本：**
1. 修改 `version.json`，更新版本号和更新日志：
```json
{
"version": "3.2",
"build": 1,
"release_date": "2026-07-10",
"changelog": "新增功能：xxx；修复：xxx",
"gitee_repo": "leitao2000/AI-QuerySystem"
}
```
2. 运行 `build-exe.bat` 编译新版本 EXE
3. 在 Gitee 仓库创建 Release，tag 名称与版本号一致（如 `v3.2`），上传编译好的 `.exe` 文件
**用户端更新：**
- 正常情况下，系统启动后自动显示新版本提示横幅
- 点击「一键更新」，系统自动从 Gitee Release 下载新 EXE 并替换，重启后生效
- 如更新失败，可点击「回滚版本」恢复上一版本
> **安全说明**：自动更新只下载编译后的 EXE 二进制文件，绝不下载 Python 源码。
### Webhook 自动更新
如果部署在服务器上，可配置 Gitee Webhook 实现推送后自动部署：
1. 在服务器上运行 Webhook 监听器：
```bash
python webhook_listener.py
```
2. 在 Gitee 仓库设置中添加 Webhook：
- URL：`http://your-server:9000/webhook`
- 事件：Push
3. 代码推送后自动执行 `git pull` → 安装依赖 → 构建前端 → 重启服务
---
## 项目结构
```
AI-QuerySystem/
├── backend/ # 后端代码（FastAPI）
│ ├── app/
│ │ ├── api/ # API 路由层
│ │ │ ├── auth.py # 用户认证（登录/注册）
│ │ │ ├── query.py # 智能查数（核心 NL→SQL）
│ │ │ ├── datasources.py # 数据源管理
│ │ │ ├── metadata.py # 元数据管理（表结构同步）
│ │ │ ├── permissions.py # 权限管理
│ │ │ ├── dashboards.py # 自定义看板
│ │ │ ├── corrections.py # 纠错学习
│ │ │ ├── sql_rules.py # 全局 SQL 规则
│ │ │ ├── model_configs.py # 模型配置
│ │ │ ├── backups.py # 数据库备份/还原
│ │ │ ├── system_logs.py # 系统日志
│ │ │ ├── admin.py # 管理员接口
│ │ │ └── update.py # 自动更新 API
│ │ ├── models/ # 数据库模型（SQLAlchemy ORM）
│ │ │ ├── user.py # 用户模型
│ │ │ ├── role.py # 角色权限模型
│ │ │ ├── datasource.py # 数据源模型
│ │ │ ├── metadata_model.py # 元数据模型
│ │ │ ├── query_log.py # 查询日志模型
│ │ │ ├── dashboard.py # 看板模型
│ │ │ ├── correction_model.py # 纠错规则模型
│ │ │ ├── sql_rule.py # SQL 规则模型
│ │ │ ├── model_config.py # 模型配置模型
│ │ │ ├── backup.py # 备份模型
│ │ │ └── system_log.py # 系统日志模型
│ │ ├── services/ # 业务逻辑层
│ │ │ ├── nl_sql_engine.py # LLM SQL 生成引擎（核心）
│ │ │ ├── db_connector.py # 数据库连接执行器
│ │ │ ├── permission_service.py # 权限过滤服务
│ │ │ ├── backup_service.py # 备份调度服务
│ │ │ ├── auto_updater.py # 自动更新服务
│ │ │ └── execution_logger.py # 执行日志记录
│ │ ├── core/ # 核心模块
│ │ │ ├── database.py # 数据库配置与连接
│ │ │ ├── security.py # 认证安全（JWT）
│ │ │ └── logging.py # 日志配置
│ │ └── utils/ # 工具函数
│ │ ├── cache.py # 查询结果缓存
│ │ └── crypto.py # 数据加密
│ ├── static/ # 前端构建产物（生产模式）
│ ├── main.py # 后端入口（含 EXE 模式逻辑）
│ ├── init_db.py # 数据库初始化脚本
│ └── requirements.txt # Python 依赖清单
├── frontend/ # 前端代码（React + Vite）
│ ├── src/
│ │ ├── components/ # 通用组件
│ │ │ └── UpdateNotifier.jsx # 更新通知组件
│ │ ├── pages/ # 页面组件
│ │ │ ├── LoginPage.jsx # 登录页
│ │ │ ├── DashboardPage.jsx # 数据概览
│ │ │ ├── QueryPage.jsx # 智能查数页
│ │ │ ├── ChatPage.jsx # 对话分析页
│ │ │ ├── DashboardBuilderPage.jsx # 看板编辑器
│ │ │ ├── HistoryPage.jsx # 查询历史
│ │ │ ├── FavoritesPage.jsx # 我的收藏
│ │ │ └── ... # 管理后台各页面
│ │ ├── services/ # API 请求封装
│ │ ├── utils/ # 前端工具函数
│ │ ├── App.jsx # 应用入口（路由、主题配置）
│ │ └── main.jsx # React DOM 挂载
│ ├── public/
│ │ ├── app.ico # 应用图标
│ │ └── app.png # 应用 Logo
│ ├── package.json # 前端依赖清单
│ └── vite.config.js # Vite 构建配置
├── build-exe.bat # Windows EXE 构建脚本
├── Dockerfile.build # Linux 交叉编译 Dockerfile
├── deploy-linux.sh # Linux 服务器一键部署脚本
├── installer.iss # Inno Setup 安装包配置
├── webhook_listener.py # Gitee Webhook 监听器
├── version.json # 版本信息与更新配置
├── update_config.json # 应用配置文件（端口、Token 等）
├── init.bat # 一键初始化脚本
├── run-api.bat # 启动后端
├── run-web.bat # 启动前端
├── update.bat # 手动更新脚本
├── LICENSE # Apache 2.0 许可证
└── README.md # 项目说明文档
```
---
## API 文档
后端基于 FastAPI 构建，启动后自动生成 OpenAPI 文档：
- **Swagger UI**：http://localhost:3000/docs
- **ReDoc**：http://localhost:3000/redoc
### 核心 API 一览
| 模块 | 路径前缀 | 主要接口 |
|------|----------|----------|
| 认证 | `/api/auth` | 登录、注册、获取当前用户 |
| 数据源 | `/api/datasources` | 添加/编辑/删除/测试连接/扫描表结构 |
| 元数据 | `/api/metadata` | 同步/查看/编辑表元数据 |
| 权限 | `/api/permissions` | 管理角色和权限规则 |
| 智能查数 | `/api/query` | 查数(`/ask`)、追问(`/follow-up`)、会话管理、历史、收藏 |
| 看板 | `/api/query` | 创建/编辑/发布看板、管理组件 |
| 模型配置 | `/api/model-configs` | 管理 LLM 模型配置 |
| 纠错规则 | `/api/query` | 纠错规则的增删改查 |
| SQL 规则 | `/api/sql-rules` | 全局 SQL 规则的增删改查 |
| 备份 | `/api/backups` | 手动备份/还原/配置定时策略 |
| 系统日志 | `/api/system-logs` | 访问日志、审计日志查询 |
| 管理 | `/api/admin` | 用户管理等管理员接口 |
| 更新 | `/api` | 版本检查、更新触发、回滚 |
---
## 构建说明
### Windows EXE
```bash
# 运行构建脚本（自动完成：前端构建 → 后端打包 → 安装器生成）
build-exe.bat
```
构建产物：
- `backend/dist/ai-query-system.exe` — 单文件 EXE（约 80-120MB）
- `Output/AI-QuerySystem-Setup.exe` — Inno Setup 安装包
### Linux 二进制
使用 Docker 在 Windows 上交叉编译 Linux ELF 二进制：
```powershell
# 构建镜像
docker build -f Dockerfile.build -t ai-qs-builder .
# 提取二进制
docker create --name tmp ai-qs-builder
mkdir dist -Force
docker cp tmp:/work/backend/dist/ai-query-system ./dist/
docker rm tmp
# 上传到服务器
scp .\dist\ai-query-system deploy-linux.sh root@SERVER_IP:/root/
```
在服务器上执行部署后，自动注册 systemd 服务，支持：
- `systemctl start/stop/restart ai-query-system`
- `systemctl status ai-query-system`
- `journalctl -u ai-query-system -f` 查看实时日志
---
## 常见问题
### Q: 如何添加新的业务数据库？
A: 在「管理后台 → 数据源」中添加，支持 SQL Server、Oracle、MySQL。添加后点击「扫描表结构」自动同步元数据。
### Q: LLM 生成的 SQL 不准确怎么办？
A:
1. 确保数据源已扫描同步元数据
2. 在元数据管理中为表/字段补充中文描述和别名
3. 在「纠错管理」中添加纠正规则，系统会学习优化
4. 检查模型配置中 API Key 和 Base URL 是否正确
### Q: 如何限制用户只能查看特定数据？
A: 在「权限管理」中创建角色，配置：
- **表级权限**：限制可见的表
- **字段级权限**：隐藏敏感字段或设置脱敏
- **行级过滤**：添加如 `department = '销售部'` 的条件
### Q: 看板发布后链接安全吗？
A: 发布链接包含随机生成的 Token，只有知道链接的人才能访问。发布后可在看板设置中「撤销发布」使链接失效。
### Q: 自动更新失败怎么办？
A:
1. 确认 Gitee Token 已正确配置（在 `update_config.json` 中）
2. 确认 Gitee Release 中已上传对应版本的 EXE 文件
3. 如更新中断，在管理更新弹窗中使用「回滚版本」恢复
### Q: EXE 启动后如何查看日志？
A: 有两种方式：
- **调试模式**：将 `update_config.json` 中的 `show_console` 设为 `true`，启动后会显示控制台窗口
- **日志文件**：日志默认写入 EXE 同目录下的 `logs/` 文件夹（`app.log`、`error.log`、`access.log`）
### Q: 开发模式下前端的 API 代理如何配置？
A: `frontend/vite.config.js` 中已配置代理，将 `/api` 请求转发到 `http://localhost:3002`（开发模式后端端口）。如需修改，编辑 `proxy` 配置即可。
---
## 更新日志
### v3.1 (2026-07-03)
- 优化系统整体布局：统一深色主题风格
- 美化 Header 用户区域
- 修复全局滚动条问题
- 管理页面表格霓虹化主题
- 修复页面高度溢出
### v1.0.0 (2026-07-01)
- 初始版本发布
- 支持自然语言智能查数
- 支持多数据源（SQL Server / Oracle / MySQL）
- 支持自定义可视化看板
- 支持看板一键发布（公开链接）
- 支持 EXE 自动更新（基于 Gitee Release）
- 支持三层权限控制
- 支持 10+ 国内主流大模型
- 支持数据库备份与还原
- 支持纠错学习与全局 SQL 规则
---
## 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源。
---
## 联系方式
- **Gitee 仓库**：https://gitee.com/leitao2000/AI-QuerySystem
- **问题反馈**：在 Gitee 仓库提交 [Issue](https://gitee.com/leitao2000/AI-QuerySystem/issues)