中文优先的开源 AI 数据库助手

用自然语言提问，生成只读 SQL，返回结果、分析与图表。

核心能力 | 工作流程 | 部署与启动 | 技术栈

核心能力

自然语言查询 用中文描述需求，自动生成并执行只读 SQL，返回结构化结果。	自动分析链路 查询结果自动衔接 Python 分析与图表生成，一次提问完成完整分析。
语义层 定义业务术语（GMV、客单价等），AI 查询时自动引用，消除歧义。	Schema 关系视图 可视化拖拽建立表间 JOIN 关系，AI 自动使用正确的关联路径。

工作流程

flowchart LR
    query["自然语言提问"] --> context["结合语义层与 Schema 理解需求"]
    context --> sql["生成只读 SQL"]
    sql --> execute["执行查询"]
    execute --> result["返回结果与总结"]
    result --> decision{"需要进一步分析或图表?"}
    decision -->|是| python["Python 分析与图表"]
    decision -->|否| done["结束"]
    python --> done
    execute -->|SQL 出错| repair_sql["自动修复并重试"]
    python -->|Python 出错| repair_py["自动修复并重试"]
    repair_sql --> sql
    repair_py --> python

Loading

界面一览

Schema 关系视图

语义层配置

部署与启动

1. 获取代码

git clone git@github.com:MKY508/QueryGPT.git
cd querygpt

2. 选择你的平台启动

macOS	Linux	Windows
方式 A — 宿主机直接运行 需要 Python 3.11+ 和 Node.js LTS ./start.sh 方式 B — Docker 需要 Docker Desktop docker compose up --build	方式 A — 宿主机直接运行 需要 Python 3.11+ 和 Node.js LTS ./start.sh 方式 B — Docker 需要 Docker Engine docker compose up --build	推荐 — Docker Desktop Windows 用户建议使用 Docker，仓库不再维护 .bat / .ps1 脚本。 安装 Docker Desktop，然后： docker compose up --build 备选 — WSL2 安装 WSL2 后，在 WSL 终端中按 Linux 方式运行 ./start.sh。

3. 访问与配置

启动后访问 http://localhost:3000：

1. 在设置页添加模型（填入 provider 和 API Key）
2. 使用内置的 示例数据库，或添加自己的 SQLite / MySQL / PostgreSQL 连接
3. 按需设置默认模型、默认连接和上下文轮数
4. 回到聊天页开始提问

项目内置 SQLite 示例库 demo.db，空工作区启动时会自动补回示例连接。

技术栈

项目

前端

后端

数据库

配置说明

模型

支持 OpenAI-compatible、Anthropic、Ollama、Custom 网关。可配置项：

字段	说明
provider	模型提供方
base_url	API 端点
model_id	模型标识
api_key	密钥（Ollama 或无需鉴权的网关可启用可选模式）
extra headers	自定义请求头
query params	自定义查询参数
api_format	API 格式
healthcheck_mode	健康检查方式

数据库

支持 SQLite、MySQL、PostgreSQL。系统只允许执行只读 SQL。

内置 SQLite 示例库：

• 路径：apps/api/data/demo.db
• 默认连接名：示例数据库

启动脚本

./start.sh          # 宿主机模式：检查环境、安装依赖、初始化数据库、启动前后端
./start.sh setup    # 宿主机模式：仅安装环境
./start.sh stop     # 停止宿主机模式服务
./start.sh restart  # 重启宿主机模式服务
./start.sh status   # 查看宿主机模式状态
./start.sh logs     # 查看宿主机模式日志
./start.sh doctor   # 宿主机模式环境诊断
./start.sh test all # 宿主机模式运行全部测试
./start.sh cleanup  # 清理宿主机模式临时状态

补装分析依赖（scikit-learn、scipy、seaborn）：

./start.sh install analytics

可选环境变量：

QUERYGPT_BACKEND_RELOAD=1 ./start.sh    # 后端热重载
QUERYGPT_BACKEND_HOST=0.0.0.0 ./start.sh # 监听所有网卡

Docker 开发

Windows 开发环境现在统一建议使用 Docker；仓库不再维护 start.ps1 / start.bat。

默认开发栈会启动：

• web：Next.js 开发服务器（热更新）
• api：FastAPI 开发服务器（--reload）
• db：PostgreSQL 16

docker-compose up --build               # 前台启动全部服务
docker-compose up -d --build            # 后台启动全部服务
docker-compose down                     # 停止并移除容器
docker-compose down -v --remove-orphans # 连数据卷一起清理
docker-compose ps                       # 查看状态
docker-compose logs -f api web          # 查看前后端日志
docker-compose restart api web          # 重启前后端
docker-compose up db                    # 仅启动数据库
docker-compose run --rm api ./run-tests.sh
docker-compose run --rm web npm run type-check
docker-compose run --rm web npm test

说明：

• 默认浏览器访问 http://localhost:3000
• 默认后端访问 http://localhost:8000
• PostgreSQL 暴露在 localhost:5432
• 依赖变更后请继续使用 docker-compose up --build
• 若本机安装了 Docker Compose 插件，也可以把以上命令替换成 docker compose ...

本地开发（宿主机模式）

后端

cd apps/api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

前端

cd apps/web
npm install
npm run dev

环境变量

后端 apps/api/.env：

DATABASE_URL=sqlite+aiosqlite:///./data/querygpt.db
ENCRYPTION_KEY=your-fernet-key

前端 apps/web/.env.local：

NEXT_PUBLIC_API_URL=http://localhost:8000
# 可选：仅 Docker / 容器内 Next rewrite 使用
# INTERNAL_API_URL=http://api:8000

测试

# 前端
cd apps/web && npm run type-check && npm test && npm run build

# 后端
./apps/api/run-tests.sh

GitHub CI 覆盖

当前 GitHub Actions 分成两层：

• 快速层：后端 ruff + mypy(聊天/配置主链路) + pytest，前端 lint + type-check + vitest + build
• 集成层：Docker 全栈启动、Playwright 烟测、start.sh 宿主机烟测、SQLite / PostgreSQL / MySQL 连接测试、模型测试假网关

本地复现常用命令：

# Docker 全栈
docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build

# 后端集成测试（需先准备 PostgreSQL / MySQL / mock gateway 环境变量）
cd apps/api && pytest tests/test_config_integration.py -v

# 后端主链路类型检查
cd apps/api && mypy --config-file mypy.ini

# 前端浏览器烟测（需自行启动应用）
cd apps/web && npm run test:e2e

部署

后端

仓库自带 render.yaml，可直接用于 Render Blueprint 部署。

前端

推荐部署到 Vercel：

• Root Directory: apps/web
• Environment Variable: NEXT_PUBLIC_API_URL=<your-api-url>

已知边界

• 只允许只读 SQL，不支持写操作
• 自动修复覆盖 SQL、Python、图表配置等可恢复错误
• /chat/stop 按单实例语义设计
• 开发环境建议使用 Node.js LTS；如 next dev 异常，先清理 apps/web/.next

许可证

MIT