Server - 配置 SQLBot 智能问数项目

欢迎关注我的CSDN：https://spike.blog.csdn.net/

本文地址：https://spike.blog.csdn.net/article/details/160468125

免责声明：本文来源于个人知识与公开资料，仅用于学术交流，欢迎讨论，不支持转载。

---

SQLBot 是一款基于大语言模型和 RAG 技术的开源智能问数系统，由 DataEase 团队出品。用户只需用自然语言提问，系统便能自动生成 SQL、查询数据库并返回结果与可视化图表，无需具备 SQL 编写能力即可完成数据分析。SQLBot 支持多种主流数据库，内置工作空间隔离与细粒度权限管控，保障数据安全；同时提供术语库、SQL 示例等训练机制，使问数效果随使用持续优化、越问越准。在集成方式上，SQLBot 支持 Web 嵌入、MCP 调用，可快速接入 Dify、n8n、DataEase 等平台，帮助各类业务系统快速获得智能问数能力。

环境依赖

依赖	版本要求	安装方式
Python	3.11.x	brew install python@3.11
Node.js	22.x	brew install node@22
pnpm	10.x	随 Node.js 一起安装
PostgreSQL	17.x	brew install postgresql@17
pgvector	-	brew install pgvector

---

首次初始化（只需执行一次）

1. 创建 Python 虚拟环境

python3.11 -m venv .venv

2. 安装后端依赖

# 主依赖（阿里云镜像加速）
.venv/bin/pip install -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com \
  "fastapi[standard]>=0.115.12,<0.120.0" "python-multipart" "passlib[bcrypt]" "tenacity" \
  "pydantic>2.0" "alembic" "httpx" "psycopg[binary]" "sqlmodel" "bcrypt==4.0.1" \
  "pydantic-settings" "sentry-sdk[fastapi]" "pyjwt" "pycryptodome" \
  "langchain>=0.3,<0.4" "langchain-core>=0.3,<1.0" "langchain-openai>=0.3,<0.4" \
  "langchain-community>=0.3,<0.4" "langchain-huggingface>=0.2.0,<1.0.0" \
  "sentence-transformers>=4.0.2" "pgvector" "dashscope" "pymysql" "cryptography" \
  "pymssql" "pandas" "openpyxl" "psycopg2-binary" "oracledb" "pyyaml" \
  "fastapi-mcp>=0.3.4,<0.4.0" "tabulate" "fastapi-cache2" "sqlparse" "redis" \
  "xlsxwriter" "python-calamine" "xlrd" "clickhouse-sqlalchemy" "dicttoxml" \
  "redshift-connector" "elasticsearch[requests]>=7.10,<8.0" "ldap3" "sqlglot" \
  "numpy==2.3.5" "llama_index>=0.12.35" "sse-starlette>=1.6.1,<2.0"

# sqlbot-xpack（从 testpypi 安装）
.venv/bin/pip install -i https://test.pypi.org/simple \
  --extra-index-url http://mirrors.aliyun.com/pypi/simple \
  --trusted-host mirrors.aliyun.com \
  "sqlbot-xpack>=0.0.5.13,<0.0.6.0"

注意 ：fastapi 需固定在 <0.120.0，否则 fastapi-mcp 会与 pydantic 产生不兼容错误。

3. 安装前端依赖

cd frontend && pnpm install
cd ..

4. 初始化数据库

# 启动 PostgreSQL
brew services start postgresql@17

# 创建用户和数据库
psql postgres -c "CREATE USER root WITH PASSWORD 'Password123@pg';"
psql postgres -c "CREATE DATABASE sqlbot OWNER root;"
psql postgres -c "ALTER USER root SUPERUSER;"

# 安装 pgvector 扩展
psql -U root -d sqlbot -c "CREATE EXTENSION IF NOT EXISTS vector;"

5. 创建本地数据目录

mkdir -p data/file data/excel data/images data/logs data/models data/db_client/oracle_instant_client

6. 创建 .env 配置文件

在项目根目录创建 .env（已加入 .gitignore，不会提交）：

POSTGRES_SERVER=localhost
POSTGRES_PORT=5432
POSTGRES_DB=sqlbot
POSTGRES_USER=root
POSTGRES_PASSWORD=Password123@pg

PROJECT_NAME=SQLBot
DEFAULT_PWD=SQLBot@123456
SECRET_KEY=y5txe1mRmS_JpOrUzFzHEu-kIQn3lf7ll0AOv9DQh0s
BACKEND_CORS_ORIGINS="http://localhost,http://localhost:13002,https://localhost,https://localhost:13002"
LOG_LEVEL=INFO
SQL_DEBUG=False

BASE_DIR=/Users/wang/workspace/baic-intelligent-data/data
UPLOAD_DIR=/Users/wang/workspace/baic-intelligent-data/data/file
MCP_IMAGE_PATH=/Users/wang/workspace/baic-intelligent-data/data/images
EXCEL_PATH=/Users/wang/workspace/baic-intelligent-data/data/excel
LOCAL_MODEL_PATH=/Users/wang/workspace/baic-intelligent-data/data/models
ORACLE_CLIENT_PATH=/Users/wang/workspace/baic-intelligent-data/data/db_client/oracle_instant_client

7. 执行数据库迁移

cd backend && ../.venv/bin/alembic upgrade head && cd ..

---

日常启动

启动 PostgreSQL

brew services start postgresql@17

启动后端（支持热重载）

cd backend && ../.venv/bin/uvicorn main:app --host 0.0.0.0 --port 18001 --reload

启动前端（另开终端）

cd frontend && pnpm dev

---

访问地址

服务	地址
前端	http://localhost:13002
后端 API	http://localhost:18001
API 文档	http://localhost:18001/docs

---

常见问题

Oracle 客户端警告 ：启动时会看到 init oracle client failed 的 ERROR 日志，这是正常现象，本地开发不需要 Oracle 客户端，不影响功能。

端口被占用：

lsof -ti :18001 | xargs kill -9
lsof -ti :13002 | xargs kill -9