SQLBot 是基于大语言模型和 RAG 的智能问数系统。本文档包面向学习者和二次开发者，帮助你从产品概念、系统架构、核心业务链路和模块职责逐步理解当前代码库。
本文档描述的是当前仓库事实。文档不会新增或承诺未实现的 API、数据库结构或运行能力。
| 顺序 | 文档 | 适合阅读的问题 |
|---|---|---|
| 1 | 项目概览与核心概念 | SQLBot 解决什么问题，核心对象有哪些 |
| 2 | 系统架构 | 前端、Node 网关、Python 数据服务和支撑服务如何协作 |
| 3 | 业务流程 | 从模型配置、数据源接入到自然语言问数的完整链路 |
| 4 | 开发与部署 | 如何本地启动、调试、理解端口和常用命令 |
| 5 | 模块阅读路径 | 代码目录分别负责什么，应该从哪里开始读 |
| 6 | Node/Python 双栈迁移说明 | 当前双栈拆分状态和迁移边界 |
- 项目概览与核心概念：解释 ChatBI、Text-to-SQL、RAG、Embedding、工作区、助手、术语库、数据训练、问答、仪表盘和 MCP 等概念。
- 业务流程：用 Mermaid 图说明主要业务路径，以及问答链路中的上下文召回、SQL 生成、执行、图表和分析沉淀。
- 系统架构：说明
frontend、api-node、backend、g2-ssr、PostgreSQL 的职责边界。 - Node/Python 双栈迁移说明：说明当前 Node 网关和 Python 数据面共存的迁移形态。
| 服务 | 端口 | 访问范围 | 说明 |
|---|---|---|---|
api-node |
8000 |
对外入口 | NestJS/Fastify 网关，前端和公开 API 入口 |
data-python |
8001 |
Compose 内部 | Python FastAPI 数据服务 |
mcp/images |
8002 |
Compose 内部 | MCP 与图片静态服务 |
g2-ssr |
3000 |
本地 Compose 暴露 | AntV G2 服务端图表渲染 |
postgres |
容器内 5432，宿主机 5433 |
数据库 | 保存 SQLBot 元数据、配置、问答和向量数据 |
- 想体验产品：先看根目录 README.md 的快速开始。
- 想理解问答如何工作：阅读 业务流程。
- 想做二次开发：先读 系统架构，再读 模块阅读路径。
- 想调试服务：阅读 开发与部署。
- 想理解双栈拆分：阅读 Node/Python 双栈迁移说明。
- 文档不会修改业务代码、接口、数据库迁移、Docker 配置或运行逻辑。
- README 中描述的端口和模块以当前仓库源码、
docker-compose.yaml、start-python.sh、api-node和backend配置为准。 - 当前仓库副本没有
.git元数据，文档校验以文件清单、链接核对和内容核对为主。