Skip to content

dual-stack-node-python.md

Latest commit

 

History

History
78 lines (59 loc) · 2.71 KB

dual-stack-node-python.md

File metadata and controls

78 lines (59 loc) · 2.71 KB
Raw

SQLBot Node/Python 双栈迁移说明

本文说明当前仓库中的双栈后端形态。更完整的系统视角见 系统架构，开发启动方式见 开发与部署。

当前形态

  • api-node 是对外公开的 NestJS/Fastify 网关，监听 8000。
  • data-python 保留现有 FastAPI 主应用，监听 8001。
  • data-python 的 MCP 和图片服务通过 mcp_app 监听 8002。
  • g2-ssr 继续作为独立图表渲染服务，监听 3000。
  • PostgreSQL 在容器内监听 5432，根目录 Compose 映射到宿主机 5433。

请求流转

flowchart LR
  Browser["浏览器 / 前端 / 嵌入页"] --> Node["api-node<br/>:8000"]
  Node --> Python["data-python FastAPI<br/>:8001"]
  Node --> Mcp["data-python MCP/images<br/>:8002"]
  Python --> Postgres["postgres<br/>:5432 / :5433"]
  Python --> G2["g2-ssr<br/>:3000"]
  G2 --> Images["共享图片卷"]
  Mcp --> Images
Loading

当前路由状态

api-node 已提供网关基础能力：

  • GET /healthz
  • GET /api/v1/healthz
  • GET /openapi.json
  • GET /docs
  • 未迁移公开接口的兼容透传

Python 数据服务当前仍保留主要业务路由，包括：

  • 登录、用户、工作区、助手、模型、参数、API Key；
  • chat 流式问答；
  • datasource 执行与适配；
  • data_training、terminology、template；
  • dashboard、table_relation、recommended_problem；
  • embedding、Excel、文件处理；
  • MCP 接口和 /images/* 静态图片。

迁移目标

Node 后续适合逐步接管偏业务壳和管理面的能力：

  • 登录、用户、工作区、权限；
  • 助手、模型、参数、API Key；
  • 仪表盘元数据、审计；
  • 统一网关观测、请求上下文和契约治理。

Python 数据面保留：

  • chat 流式问答；
  • SQL 生成、校验与执行；
  • datasource 适配；
  • data_training、terminology、template；
  • embedding、Excel、文件处理；
  • MCP 和图表图片相关集成。

切换原则

  • 保持前端路径和响应契约不变。
  • 每次只迁移一组路由，先补齐 DTO、service、adapter、guard 和契约测试。
  • 对应契约测试通过后，再把同组接口从 Python 收口到 Node。
  • 未迁移接口继续由 Node 透传到 Python。
  • Chat 流式响应、上传下载、图片和 MCP 路径必须保持透传特性，不被重新包装。

本地验证重点

  • GET http://localhost:8000/healthz 能看到网关和 Python 上游状态。
  • GET http://localhost:8000/api/v1/healthz 返回 SQLBot 包装格式。
  • 前端继续使用 http://localhost:8000/api/v1。
  • /images/*、/mcp/*、/sse/* 相关请求会转发到 MCP/images 服务。
  • 常规 /api/v1/* 请求会转发到 Python FastAPI 主应用。