Skip to content

development.md

Latest commit

 

History

History
181 lines (133 loc) · 4.93 KB

development.md

File metadata and controls

181 lines (133 loc) · 4.93 KB
Raw

开发与部署

本文面向想在本地阅读、运行和调试 SQLBot 的开发者。当前仓库包含 Vue 前端、NestJS/Fastify 网关、Python FastAPI 数据服务、g2-ssr 图表服务和 PostgreSQL。

环境要求

组件 建议版本 用途
Node.js >=20 运行 api-node，构建前端，运行 g2-ssr
Python 3.11.* 运行 backend FastAPI 服务
Docker 当前稳定版 运行 Compose 或单镜像部署
Docker Compose v2 启动本地多服务编排
uv 当前稳定版 安装 Python 依赖
PostgreSQL 17.x 本地数据库，Compose 中默认提供

本地 Compose 启动

仓库根目录的 docker-compose.yaml 会启动：

  • postgres
  • data-python
  • api-node
  • g2-ssr
docker compose up --build

启动后访问：

  • SQLBot 对外入口：http://localhost:8000
  • Node 健康检查：http://localhost:8000/healthz
  • API 包装健康检查：http://localhost:8000/api/v1/healthz
  • 网关文档入口：http://localhost:8000/docs
  • g2-ssr：http://localhost:3000
  • PostgreSQL 宿主机端口：localhost:5433

默认登录：

  • 用户名：admin
  • 密码：SQLBot@123456

前端开发

前端位于 frontend，开发环境通过 .env.development 指向网关：

VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_APP_TITLE=SQLBot (Development)

常用命令：

cd frontend
npm install
npm run dev
npm run build

说明：

  • npm run dev 会先执行 vue-tsc -b，再启动 Vite。
  • npm run build 会进行类型检查并构建前端产物。
  • npm run lint 在当前脚本中带有 --fix，会改写文件，做只读核对时不要运行。

Node 网关开发

网关位于 api-node，使用 NestJS 和 Fastify。它默认监听 8000，并通过环境变量连接 Python 上游。

cd api-node
npm install
npm run typecheck
npm run build

PowerShell 本地启动示例：

$env:PORT='8000'
$env:DATA_PYTHON_BASE_URL='http://127.0.0.1:8001'
$env:MCP_PYTHON_BASE_URL='http://127.0.0.1:8002'
npm run start:dev

关键环境变量：

变量 默认值 说明
PORT 8000 Node 网关监听端口
DATA_PYTHON_BASE_URL http://127.0.0.1:8001 Python FastAPI 主应用地址
MCP_PYTHON_BASE_URL http://127.0.0.1:8002 MCP 与图片服务地址
GATEWAY_REQUEST_TIMEOUT_MS 300000 透传请求超时时间
GATEWAY_HEALTH_TIMEOUT_MS 3000 上游健康检查超时时间
GATEWAY_BODY_LIMIT_BYTES 524288000 请求体大小限制
BACKEND_CORS_ORIGINS 空 CORS 允许来源，逗号分隔

Python 数据服务开发

Python 服务位于 backend，主应用是 main:app，MCP 和图片服务是 main:mcp_app。

cd backend
uv sync --extra cpu

PowerShell 本地环境变量示例：

$env:POSTGRES_SERVER='127.0.0.1'
$env:POSTGRES_PORT='5433'
$env:POSTGRES_DB='sqlbot'
$env:POSTGRES_USER='root'
$env:POSTGRES_PASSWORD='123456'
$env:PROJECT_NAME='SQLBot'
$env:DEFAULT_PWD='SQLBot@123456'
$env:MCP_IMAGE_HOST='http://127.0.0.1:3000'
$env:SERVER_IMAGE_HOST='http://localhost:8000/images/'

启动主应用：

uvicorn main:app --host 0.0.0.0 --port 8001 --workers 1 --proxy-headers

启动 MCP 与图片服务：

uvicorn main:mcp_app --host 0.0.0.0 --port 8002

注意：

  • Python 服务启动时会执行 Alembic 迁移、初始化缓存、初始化动态 CORS，并填充缺失的术语、数据训练、表和数据源 Embedding。
  • 本地独立启动 Python 前需要确保 PostgreSQL 可连接。

g2-ssr 开发

图表服务位于 g2-ssr，默认监听 3000。

cd g2-ssr
npm install
node app.js

服务接收图表类型、坐标轴、数据和输出路径，使用 @antv/g2-ssr 生成 PNG 文件。

常用验证

cd api-node
npm run typecheck
npm run build
python -m pytest tests

仓库当前测试主要覆盖 MiniMax 供应商配置和相关集成。部分集成测试需要环境变量，例如 MINIMAX_API_KEY，未设置时会跳过。

端口速查

服务 端口 访问方式
api-node 8000 宿主机访问
data-python 8001 Compose 内部或本地手动启动
mcp/images 8002 Compose 内部或本地手动启动
g2-ssr 3000 宿主机访问
postgres 5432 / 5433 容器内 5432，Compose 映射 5433

调试建议

  • 前端请求失败时，先确认 VITE_API_BASE_URL 是否指向 api-node:8000。
  • 网关透传失败时，检查 DATA_PYTHON_BASE_URL 和 MCP_PYTHON_BASE_URL。
  • Python 启动失败时，优先检查 PostgreSQL 连接、Alembic 迁移和模型依赖。
  • 问答生成不准时，优先补充字段说明、术语库、表关系和数据训练示例。
  • 图表图片不生成时，检查 MCP_IMAGE_HOST、SERVER_IMAGE_HOST、g2-ssr 和图片目录挂载。