Skip to content
Closed

Dev #1469

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,16 @@ backend/.venv
backend/.gitignore
backend/README.md
backend/scripts
backend/.DS_Store
backend/.DS_Store
backend/logs
backend/.pytest_cache
backend/.ruff_cache

# Frontend
frontend/node_modules
frontend/dist

# Local runtime data and secrets
.env
data
.git
12 changes: 12 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# 复制为 .env 后再启动:cp .env.example .env
# 必填:JWT 签名密钥,请替换为随机值,例如 `openssl rand -hex 32` 的输出
SECRET_KEY=please-change-me

# 可选:MCP 返回图表图片时使用的地址,改成部署机器的 IP
# SERVER_IMAGE_HOST=http://<服务器IP>:8001/images/

# 可选:自动分析相关配置(以下为默认值)
# CHAT_AUTO_ANALYSIS_ENABLED=true
# ANALYSIS_SUPPLEMENTARY_QUERY_MAX=3
# ANALYSIS_PLAN_DATA_ROWS=50
# ANALYSIS_SUPPLEMENTARY_TIMEOUT=120
6 changes: 5 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,9 +153,13 @@ _Avoid_: App Secret(验签密钥,不是透传凭据)
_Avoid_: app_id(仅用于反查应用,无认证作用)、Assistant Certificate

**MCP**:
以独立服务进程暴露问数工具集的集成形态,调用者以真实用户身份接入,数据权限按该用户计算。
以独立服务进程暴露问数工具集的集成形态,调用者以真实用户身份接入,数据权限按该用户计算。MCP 服务进程上有两个入口:`/mcp` 把问数流程整体暴露出去,由 SQLBot 的模型生成 SQL;`/sqlbot-mcp` 是无模型入口,由外部 Agent 自己写 SQL,SQLBot 只提供上下文和受控执行。
_Avoid_: Ordinary Assistant、Page-embedded Assistant

**Agent Token / Agent 令牌**:
用户自助创建、供外部 Agent 调用 `/sqlbot-mcp` 的 Bearer 凭据(`sk-sqlbot-` 前缀),绑定创建者和一个工作空间,可再收窄到部分数据源;只能访问 `/sqlbot-mcp`,库中只存摘要。
_Avoid_: API Key(可调用全部 API 的 AK/SK 签名凭据)

**Dashboard / 仪表板**:
由会话图表快照与文本、Tab 组件组成的画布;图表组件是会话记录的配置快照,数据在查看时实时查询。
_Avoid_: Chat、chat record
Expand Down
138 changes: 75 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,93 +1,105 @@
<p align="center"><img src="https://resource-fit2cloud-com.oss-cn-hangzhou.aliyuncs.com/sqlbot/sqlbot.png" alt="SQLBot" width="300" /></p>
<h3 align="center">基于大模型和 RAG 的智能问数系统</h3>

<p align="center">
<a href="https://trendshift.io/repositories/14540" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14540" alt="dataease%2FSQLBot | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

<p align="center">
<a href="https://github.com/dataease/SQLBot/releases/latest"><img src="https://img.shields.io/github/v/release/dataease/SQLBot" alt="Latest release"></a>
<a href="https://github.com/dataease/SQLBot"><img src="https://img.shields.io/github/stars/dataease/SQLBot?color=%231890FF&style=flat-square" alt="Stars"></a>
<a href="https://hub.docker.com/r/dataease/SQLbot"><img src="https://img.shields.io/docker/pulls/dataease/sqlbot?label=downloads" alt="Download"></a><br/>
</p>

<p align="center">
<a href="README.md"><img alt="中文(简体)" src="https://img.shields.io/badge/中文(简体)-d9d9d9"></a>
<a href="/docs/README.en.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>
</p>
<h3 align="center">基于大模型和 RAG 的智能问数系统(二次开发版)</h3>
<hr/>

SQLBot 是一款基于大语言模型和 RAG 的智能问数系统,由 DataEase 开源项目组匠心出品。借助 SQLBot,用户可以实现对话式数据分析(ChatBI),快速提炼获取所需的数据信息及可视化图表,并且支持进一步开展智能分析。
本项目基于开源项目 [dataease/SQLBot](https://github.com/dataease/SQLBot) 二次开发。在原有"自然语言提问 → 生成 SQL → 返回数据和图表"的基础上,增加了问数后自动生成分析结论的能力,分析中用到的派生数值由数据库计算,不由大模型心算。

## 工作原理
## 二次开发内容

<img width="1153" height="563" alt="image" src="https://github.com/user-attachments/assets/8bc40db1-2602-4b68-9802-b9be36281967" />
| 功能 | 说明 |
| --- | --- |
| 问数后自动分析 | 问数完成后自动生成分析结论,不需要再手动点击"数据分析"按钮。可以用 `CHAT_AUTO_ANALYSIS_ENABLED` 关闭。 |
| 补充计算 SQL | 生成分析前,大模型先规划占比、环比、合计这类派生指标的补充查询(最多 `ANALYSIS_SUPPLEMENTARY_QUERY_MAX` 条)。补充查询只能访问本次问数已授权的表,并且只允许只读语句,校验通过后在数据库执行,分析结论引用执行结果,减少数值错误。 |
| 执行过程可见 | "执行详情"里新增"规划分析计算"和"执行分析计算 SQL"两个步骤,分析过程的思考内容也会展示出来。 |
| 切换会话不丢进度 | 回答生成过程中切换到其他会话再切回来,页面会继续轮询并显示后端的执行进度,直到回答完成。 |
| 失败提示 | 分析生成失败时给出明确的错误信息(已覆盖中、英、繁中、韩、泰五种语言)。 |

## 核心优势
主要改动位置:`backend/apps/chat/task/llm.py`、`backend/templates/template.yaml`、`backend/common/core/config.py`、`frontend/src/views/chat/`。单元测试位于 `backend/tests/test_chat_auto_analysis.py`。

- **开箱即用**:仅需简单配置大模型与数据源,无需复杂开发,即可快速开启智能问数;依托大模型自然语言理解与 SQL 生成能力,结合 RAG 技术,实现高质量 Text-to-SQL 转换。
- **安全可控**:提供工作空间级资源隔离机制,构建清晰数据边界,保障数据访问安全;支持细粒度数据权限配置,强化权限管控能力,确保使用过程合规可控。
- **易于集成**:支持多种集成方式,提供 Web 嵌入、弹窗嵌入、MCP 调用等能力;能够快速嵌入到 n8n、Dify、MaxKB、DataEase 等应用,让各类应用快速拥有智能问数能力。
- **越问越准**:支持自定义提示词、术语库配置,可维护 SQL 示例校准逻辑,精准匹配业务场景;高效运营,基于用户交互数据持续迭代优化,问数效果随使用逐步提升,越问越准。
## 部署(Docker,推荐)

## 快速开始
### 1. 环境要求

### 安装部署
- Linux 服务器或 WSL2,4 核 8 GB 内存以上,磁盘可用空间 20 GB 以上
- Docker 20.10+,并安装 Docker Compose v2(`docker compose version` 能正常输出)
- 构建时要能访问 `registry.cn-qingdao.aliyuncs.com`、`ghcr.io`、npm 源和 PyPI
- 一个可用的大模型 API(OpenAI 兼容接口即可,例如 DeepSeek、通义千问)

准备一台 Linux 服务器,安装好 [Docker](https://docs.docker.com/get-docker/),执行以下一键安装脚本:
### 2. 获取代码并配置

```bash
docker run -d \
--name sqlbot \
--restart unless-stopped \
-p 8000:8000 \
-p 8001:8001 \
-v ./data/sqlbot/excel:/opt/sqlbot/data/excel \
-v ./data/sqlbot/file:/opt/sqlbot/data/file \
-v ./data/sqlbot/images:/opt/sqlbot/images \
-v ./data/sqlbot/logs:/opt/sqlbot/app/logs \
-v ./data/postgresql:/var/lib/postgresql/data \
--privileged=true \
dataease/sqlbot
git clone <本仓库地址> SQLBot
cd SQLBot

cp .env.example .env
# 把 .env 里的 SECRET_KEY 替换为随机值
sed -i "s/^SECRET_KEY=.*/SECRET_KEY=$(openssl rand -hex 32)/" .env
```

你也可以通过 [1Panel 应用商店](https://apps.fit2cloud.com/1panel) 快速部署 SQLBot。
### 3. 构建并启动

```bash
docker compose up -d --build
```

如果是内网环境,你可以通过 [离线安装包方式](https://community.fit2cloud.com/#/products/sqlbot/downloads) 部署 SQLBot。
镜像从本仓库源码构建,第一次构建需要 10 到 30 分钟,视网络情况而定。查看启动日志:

### 访问方式
```bash
docker compose logs -f sqlbot
```

- 在浏览器中打开: http://<你的服务器IP>:8000/
- 用户名: admin
- 密码: SQLBot@123456
日志出现 `Uvicorn running on http://0.0.0.0:8000` 表示启动完成。

### 联系我们
### 4. 访问

如你有更多问题,可以加入我们的技术交流群与我们交流。
- 地址:`http://<服务器IP>:8000/`
- 用户名:`admin`
- 密码:`SQLBot@123456`

<img width="180" height="180" alt="contact_me_qr" src="https://github.com/user-attachments/assets/14594c13-fa1b-4085-a77e-0cff63b17180" />
### 5. 首次使用

## UI 展示
1. 登录后进入"系统管理 → AI 模型配置",添加一个大模型并设为默认模型。
2. 进入"数据源",添加一个数据库连接(MySQL、PostgreSQL 等),选择要问数的表。
3. 回到"智能问数",选择该数据源后提问,例如"各地区上月销售额及占比"。回答完成后会自动生成分析结论,点开"执行详情"可以看到补充计算的 SQL。

<tr>
<img alt="q&a" src="https://github.com/user-attachments/assets/55526514-52f3-4cfe-98ec-08a986259280" />
</tr>
### 停止与清理

## 飞致云旗下的其他明星项目
```bash
docker compose down # 停止服务,数据保留在 ./data 目录
rm -rf ./data # 如需清空全部数据(不可恢复)
```

## 配置项

在 `.env` 中设置,修改后执行 `docker compose up -d` 生效。

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `SECRET_KEY` | 无,必填 | JWT 签名密钥 |
| `SERVER_IMAGE_HOST` | `http://localhost:8001/images/` | MCP 返回图表图片时使用的地址,外部访问时改成服务器 IP |
| `CHAT_AUTO_ANALYSIS_ENABLED` | `true` | 问数完成后是否自动生成分析 |
| `ANALYSIS_SUPPLEMENTARY_QUERY_MAX` | `3` | 每次分析最多执行的补充查询数,`0` 表示不做补充计算 |
| `ANALYSIS_PLAN_DATA_ROWS` | `50` | 规划补充查询时提供给大模型的结果行数上限 |
| `ANALYSIS_SUPPLEMENTARY_TIMEOUT` | `120` | 等待补充计算的最长秒数,超时则不使用补充结果 |

## 运行测试

```bash
cd backend
uv sync
uv run pytest tests/test_chat_auto_analysis.py
```

- [DataEase](https://github.com/dataease/dataease/) - 人人可用的开源 BI 工具
- [1Panel](https://github.com/1panel-dev/1panel/) - 现代化、开源的 Linux 服务器运维管理面板
- [MaxKB](https://github.com/1panel-dev/MaxKB/) - 强大易用的企业级智能体平台
- [JumpServer](https://github.com/jumpserver/jumpserver/) - 广受欢迎的开源堡垒机
- [Cordys CRM](https://github.com/1Panel-dev/CordysCRM) - 新一代的开源 AI CRM 系统
- [Halo](https://github.com/halo-dev/halo/) - 强大易用的开源建站工具
- [MeterSphere](https://github.com/metersphere/metersphere/) - 新一代的开源持续测试工具
## 常见问题

## License
- **启动报 `Set a unique SECRET_KEY in .env`**:没有创建 `.env` 或其中没有 `SECRET_KEY`,按第 2 步处理。
- **构建时拉取镜像失败**:检查服务器能否访问 `registry.cn-qingdao.aliyuncs.com` 和 `ghcr.io`,必要时为 Docker 配置代理或镜像加速。
- **8000 / 8001 端口被占用**:修改 `docker-compose.yaml` 中 `ports` 的左侧端口,例如 `18000:8000`。
- **提问没有回答**:确认已配置默认大模型,并且服务器能访问该模型的 API 地址。

本仓库遵循 [FIT2CLOUD Open Source License](LICENSE) 开源协议,该许可证本质上是 GPLv3,但有一些额外的限制。
## 致谢与 License

你可以基于 SQLBot 的源代码进行二次开发,但是需要遵守以下规定:
本项目基于 [dataease/SQLBot](https://github.com/dataease/SQLBot)(飞致云 DataEase 开源项目组)二次开发,遵循原项目的 [FIT2CLOUD Open Source License](LICENSE)。该协议本质上是 GPLv3,并附加以下限制:

- 不能替换和修改 SQLBot 的 Logo 和版权信息;
- 二次开发后的衍生作品必须遵守 GPL V3 的开源义务。
20 changes: 20 additions & 0 deletions backend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ SQLBOT_SKIP_TABLE_CHECK=true

开启后仅跳过表白名单检查,可能允许查询数据源账号可读取的未勾选表。真实表名提取始终执行,无法提取表名时仍拒绝 SQL。SQL 只读、危险函数、元数据查询控制、行权限处理及行数限制仍按原有流程执行。

该开关只影响网页问数和 `/mcp` 的模型生成 SQL;`/sqlbot-mcp` 的外部提交 SQL 始终做表和列检查。

## 数据源存储密钥

默认无需配置。API 首次启动时会在持久化目录 `UPLOAD_DIR/.secrets/datasource-keys.json` 自动生成部署专用密钥,默认完整路径为 `/opt/sqlbot/data/file/.secrets/datasource-keys.json`。保留现有 `file` 数据卷,API 和 MCP 使用同一文件。若数据库已有新版密文而密钥文件缺失,启动会停止,请恢复原密钥文件。
Expand All @@ -36,3 +38,21 @@ python3 -c 'import base64,json,secrets; key=base64.b64encode(secrets.token_bytes
轮换时先停止该部署的 API 和 MCP,保留旧密钥,加入新密钥并将 `active` 切换到新标识,原子替换文件。启动 API,等待现有配置重新加密,再恢复其他进程。用当前密钥文件验证数据库备份恢复后,可从在线文件移除旧密钥。历史备份所需密钥应离线保留至备份过期。恢复时先准备匹配该备份的密钥文件,再启动 API。已暴露的旧 ECB 密文仍可解密,应轮换对应数据源自身的凭据。

浏览器写入仍兼容旧请求编码,部署通过 HTTPS 保护传输。数据源列表和写入响应省略配置,授权编辑详情仅提供表单字段,密码和额外连接参数留空表示沿用。连接目标变化时需要重新提供已保存的敏感连接字段。API 客户端可发送显式空字符串清除密码或额外连接参数。

## sqlbot-mcp(无模型 Agent 入口)

`/sqlbot-mcp` 让 Claude、Codex 等外部 Agent 自己写 SQL,SQLBot 不调用模型,只提供数据源、表结构、术语、SQL 示例,并在行列权限、只读校验、语句超时和行数上限下执行。它和 `/mcp` 跑在同一个 MCP 进程上(`uvicorn main:mcp_app --port 8001`)。

1. 在网页右上角个人菜单打开“Agent 令牌”,创建令牌(可限定数据源)。令牌只显示一次,以创建者身份和当前工作空间生效。
2. 在 Agent 中添加 MCP(Streamable HTTP):

```bash
claude mcp add --transport http sqlbot-mcp http://<host>:8001/sqlbot-mcp \
--header "Authorization: Bearer sk-sqlbot-..."
```

只支持 stdio 的客户端可用 `npx mcp-remote http://<host>:8001/sqlbot-mcp --header "Authorization: Bearer sk-sqlbot-..."` 桥接。

工具:`agent_list_datasources`、`agent_get_query_context`、`agent_list_tables`、`agent_describe_tables`、`agent_execute_sql`。执行记录写入创建者的会话历史(来源为 MCP),调用写入操作日志。

部署注意:8001 端口应只对内网或可信网络开放;按令牌限流使用 `security_config` 的 `rate_limit_per_minute`(进程内计数,多 worker 时每个 worker 单独计数);语句超时目前在 PostgreSQL / Excel / MySQL 生效,其他数据源依赖连接配置的超时;数据源连接账号建议只授予只读权限。
49 changes: 49 additions & 0 deletions backend/alembic/versions/076_agent_token_ddl.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
"""076_agent_token_ddl

Bearer tokens for the SQLBot MCP server used by external agents. Only a
SHA-256 digest of each token is stored.

Revision ID: 3b7e0c1f9a42
Revises: d91543ca7b21
Create Date: 2026-11-13 18:00:00

"""
import sqlalchemy as sa
import sqlmodel.sql.sqltypes

from alembic import op

# revision identifiers, used by Alembic.
revision = '3b7e0c1f9a42'
down_revision = 'd91543ca7b21'
branch_labels = None
depends_on = None


def upgrade():
op.create_table(
'sys_agent_token',
sa.Column('id', sa.BigInteger(), nullable=False),
sa.Column('name', sqlmodel.sql.sqltypes.AutoString(length=255), nullable=False),
sa.Column('uid', sa.BigInteger(), nullable=False),
sa.Column('oid', sa.BigInteger(), nullable=False),
sa.Column('token_prefix', sqlmodel.sql.sqltypes.AutoString(length=32), nullable=False),
sa.Column('token_hash', sqlmodel.sql.sqltypes.AutoString(length=128), nullable=False),
sa.Column('status', sa.Boolean(), nullable=False, server_default=sa.true()),
sa.Column('allowed_ds_ids', sa.Text(), nullable=True),
sa.Column('create_time', sa.BigInteger(), nullable=False, server_default='0'),
sa.Column('last_used_time', sa.BigInteger(), nullable=True),
sa.Column('last_used_ip', sqlmodel.sql.sqltypes.AutoString(length=64), nullable=True),
sa.PrimaryKeyConstraint('id'),
)
op.create_index(op.f('ix_sys_agent_token_id'), 'sys_agent_token', ['id'], unique=False)
op.create_index(op.f('ix_sys_agent_token_uid'), 'sys_agent_token', ['uid'], unique=False)
op.create_index(op.f('ix_sys_agent_token_token_prefix'), 'sys_agent_token', ['token_prefix'], unique=True)


def downgrade():
# Dropping the table revokes every issued agent token.
op.drop_index(op.f('ix_sys_agent_token_token_prefix'), table_name='sys_agent_token')
op.drop_index(op.f('ix_sys_agent_token_uid'), table_name='sys_agent_token')
op.drop_index(op.f('ix_sys_agent_token_id'), table_name='sys_agent_token')
op.drop_table('sys_agent_token')
3 changes: 2 additions & 1 deletion backend/apps/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from apps.data_training.api import data_training
from apps.datasource.api import datasource, table_relation, recommended_problem
from apps.mcp import mcp
from apps.system.api import login, user, aimodel, workspace, assistant, parameter, apikey, variable_api
from apps.system.api import login, user, aimodel, workspace, assistant, parameter, apikey, variable_api, agent_token
from apps.terminology.api import terminology
from apps.settings.api import base
#from audit.api import audit_api
Expand All @@ -27,6 +27,7 @@
api_router.include_router(table_relation.router)
api_router.include_router(parameter.router)
api_router.include_router(apikey.router)
api_router.include_router(agent_token.router)

api_router.include_router(recommended_problem.router)

Expand Down
Loading