Skip to content

architecture.md

Latest commit

 

History

History
91 lines (73 loc) · 3.98 KB

architecture.md

File metadata and controls

91 lines (73 loc) · 3.98 KB
Raw

系统架构

SQLBot 当前采用前端、Node 网关、Python 数据服务和支撑服务协作的双栈架构。设计目标是在保持现有 /api/v1 契约兼容的前提下，让 api-node 成为统一对外入口，Python 继续承担数据面和 AI 重任务。

总体结构

flowchart LR
  User["用户浏览器 / 嵌入页"] --> Frontend["frontend<br/>Vue 3 + Vite"]
  Frontend --> Gateway["api-node<br/>NestJS + Fastify<br/>:8000"]
  Gateway --> Python["backend<br/>FastAPI data-python<br/>:8001"]
  Gateway --> Mcp["mcp/images<br/>FastAPI mcp_app<br/>:8002"]
  Python --> Pg["PostgreSQL<br/>:5432 容器内 / :5433 宿主机"]
  Python --> Model["LLM / Embedding 服务"]
  Python --> Ds["外部数据库 / Excel"]
  Python --> G2["g2-ssr<br/>:3000"]
  G2 --> Images["/opt/sqlbot/images"]
  Mcp --> Images
Loading

模块职责

模块 位置 职责
前端应用 frontend 管理端、问答页、数据源页面、模型配置、仪表盘编辑、嵌入页面和静态资源。
Node 网关 api-node 监听 8000，提供对外入口、CORS、请求 ID、健康检查、轻量 OpenAPI 和兼容透传。
Python 数据服务 backend 监听 8001，承载业务 API、数据源适配、SQL 生成执行、Embedding、Excel/文件、问答流式输出。
MCP 与图片服务 backend 中的 mcp_app 监听 8002，承载 MCP server 和 /images 静态图片服务。
图表渲染服务 g2-ssr 监听 3000，基于 @antv/g2-ssr 生成图表图片。
元数据数据库 PostgreSQL 保存用户、工作区、模型、数据源、问答、仪表盘、术语、训练数据和向量字段。
安装脚本 installer 提供安装、卸载和发行版 Compose 模板。

请求流转

sequenceDiagram
  participant B as Browser
  participant N as api-node:8000
  participant P as data-python:8001
  participant M as mcp/images:8002
  participant G as g2-ssr:3000
  participant DB as PostgreSQL

  B->>N: /api/v1/* 请求
  N->>N: 注入 x-sqlbot-trace-id
  N->>P: 未迁移公开接口透传
  P->>DB: 读取元数据、权限、问答记录
  P->>P: 召回术语、训练数据、表结构
  P-->>N: 流式或普通响应
  N-->>B: 保持原响应契约
  P->>G: 需要图片时请求图表渲染
  G-->>P: 生成图片文件
  B->>N: /images/* 或 MCP 相关请求
  N->>M: 转发到图片或 MCP 服务
Loading

路由边界

当前 api-node 已经提供：

  • GET /healthz
  • GET /api/v1/healthz
  • GET /openapi.json
  • GET /docs
  • GET|POST|PUT|PATCH|DELETE * 兼容透传

Python 仍保留主要业务路由，聚合入口位于 backend/apps/api.py，包括登录、用户、工作区、助手、模型、数据源、术语库、数据训练、问答、仪表盘、MCP、表关系和推荐问题等模块。

端口说明

服务 当前端口 说明
api-node 8000 对外入口，Compose 中发布到宿主机
data-python 8001 FastAPI 主应用，Compose 网络内访问
mcp/images 8002 MCP 与图片服务，Compose 网络内访问
g2-ssr 3000 图表渲染服务，Compose 中发布到宿主机
postgres 5432 / 5433 容器内 5432，本地 Compose 映射到宿主机 5433

数据与文件流

  • PostgreSQL 保存 SQLBot 元数据、问答记录、仪表盘配置和向量字段。
  • Excel 上传文件保存到 data/sqlbot/excel，普通文件保存到 data/sqlbot/file。
  • 图表图片保存到 data/sqlbot/images，由 MCP/images 服务和主应用静态挂载。
  • 日志保存到 data/sqlbot/logs。

设计约束

  • 前端继续使用 VITE_API_BASE_URL=http://localhost:8000/api/v1 这一类公开入口。
  • 双栈迁移期间不改变现有 /api/v1 路径和响应契约。
  • Chat 流式响应、上传下载和图片访问需要保持透传，不被网关重新包装。
  • Python 数据面暂不迁入 Node，包括 SQL 生成、Embedding、Excel 解析、外部数据库适配和 MCP。