Skip to content

modules.md

Latest commit

 

History

History
129 lines (99 loc) · 6.21 KB

modules.md

File metadata and controls

129 lines (99 loc) · 6.21 KB
Raw

模块阅读路径

本文按目录说明 SQLBot 当前代码库的职责边界，并给出适合学习者的阅读顺序。

顶层目录

目录 职责
frontend Vue 3 前端，包含登录、布局、问答、数据源、模型、系统管理、仪表盘和嵌入页面。
api-node NestJS/Fastify 网关，提供统一入口、健康检查、OpenAPI 入口和兼容透传。
backend Python FastAPI 数据服务，承载主要业务 API、AI 问答、数据源和 MCP。
g2-ssr 服务端图表渲染服务，负责生成图表图片。
installer 安装、卸载脚本和发行版 Compose 模板。
tests Python 测试，当前主要覆盖模型供应商配置和 MiniMax 集成。
docs 技术文档。

前端阅读路径

建议从这些位置开始：

路径 关注点
frontend/src/main.ts Vue 应用初始化。
frontend/src/router 路由、权限跳转和页面入口。
frontend/src/utils/request.ts API 请求封装、鉴权、错误处理和下载逻辑。
frontend/src/api 前端 API 调用分组。
frontend/src/views/chat 问答页面、流式响应、执行明细和图表展示。
frontend/src/views/ds 数据源管理、表字段维护、Excel 上传和推荐问题配置。
frontend/src/views/dashboard 仪表盘编辑、预览和组件渲染。
frontend/src/views/system 用户、工作区、模型、术语、训练、权限、嵌入和系统参数。
frontend/src/entity/supplier.ts 模型供应商前端配置。

阅读建议：

  1. 先看 router 和 components/layout，理解应用框架。
  2. 再看 utils/request.ts 和 src/api，理解接口调用方式。
  3. 然后按业务模块阅读 views/chat、views/ds、views/system 和 views/dashboard。

api-node 阅读路径

api-node 是当前双栈架构的对外网关。

路径 关注点
api-node/src/main.ts Fastify Adapter、CORS、请求 ID、全局异常和启动端口。
api-node/src/config/gateway.config.ts 网关环境变量和默认值。
api-node/src/health /healthz 和 /api/v1/healthz 健康检查。
api-node/src/python Python 上游健康探测。
api-node/src/proxy 未迁移接口的兼容透传逻辑。
api-node/src/openapi 网关轻量 OpenAPI 和文档入口。
api-node/test/smoke-upstream.js 本地透传联通验证示例。

阅读重点：

  • ProxyService 如何按路径选择 DATA_PYTHON_BASE_URL 或 MCP_PYTHON_BASE_URL；
  • 网关如何透传请求体、响应头和流式响应；
  • x-sqlbot-trace-id 如何在请求链路中传播。

backend 阅读路径

backend 是 SQLBot 的核心数据服务。它保留了大部分业务接口和 AI 数据面能力。

路径 关注点
backend/main.py FastAPI 应用创建、生命周期、OpenAPI、MCP、静态图片和中间件。
backend/apps/api.py 业务路由聚合入口。
backend/common/core/config.py 配置、数据库连接、CORS、图片地址和默认参数。
backend/apps/system 登录、用户、工作区、模型、助手、参数、API Key 和变量。
backend/apps/datasource 数据源、表字段、表关系、推荐问题、Excel 处理和 Embedding。
backend/apps/db 数据库适配、SQL 执行、Schema、表和字段读取。
backend/apps/chat 问答记录、问题处理、SQL 生成、图表、分析和预测。
backend/apps/template 生成 SQL、图表、分析、预测和推荐问题的模板。
backend/apps/terminology 术语库管理和 Embedding。
backend/apps/data_training SQL 示例和训练数据管理。
backend/apps/mcp MCP 调用入口。
backend/alembic 数据库迁移脚本。

推荐阅读顺序：

  1. main.py 和 apps/api.py：理解 FastAPI 应用和路由装配。
  2. common/core/config.py：理解环境变量和默认配置。
  3. apps/system：理解登录、用户、工作区和模型基础配置。
  4. apps/datasource 和 apps/db：理解数据源同步、表字段和 SQL 执行。
  5. apps/chat/task/llm.py：理解问答链路中的数据源选择、SQL 生成、图表、分析和预测。
  6. apps/template：理解提示词模板如何影响模型输出。

g2-ssr 阅读路径

路径 关注点
g2-ssr/app.js HTTP 服务、图表请求解析和图片输出。
g2-ssr/charts 柱状图、条形图、折线图、饼图配置生成。
g2-ssr/Dockerfile 图表服务构建方式。
g2-ssr/ecosystem.config.js PM2 运行配置。

该模块只负责图表图片生成，不负责问答、SQL 或业务权限。

installer 阅读路径

路径 关注点
installer/install.sh 安装流程。
installer/uninstall.sh 卸载流程。
installer/install.conf 安装参数。
installer/sqlbot/docker-compose.yml 发行版单服务 Compose 模板。
installer/sqlbot/templates/sqlbot.conf 发行版环境变量模板。

注意：根目录 docker-compose.yaml 是当前仓库双栈本地编排，installer/sqlbot/docker-compose.yml 面向发行版安装模板，两者服务形态不同。

tests 阅读路径

路径 关注点
tests/test_supplier_config.py 前端供应商配置、i18n、图标和后端模型工厂支持检查。
tests/test_minimax_integration.py MiniMax API 联通集成测试，需要 MINIMAX_API_KEY。

常用执行方式：

python -m pytest tests

二次开发切入点

  • 增加模型供应商：优先查看 frontend/src/entity/supplier.ts、前端 i18n、图标资源和 backend/apps/ai_model。
  • 增加数据源类型：优先查看 frontend/src/views/ds、backend/apps/db/constant.py、backend/apps/db/db.py 和 backend/apps/db/db_sql.py。
  • 优化问答效果：优先查看术语库、数据训练、backend/apps/template 和 backend/apps/chat/task/llm.py。
  • 扩展嵌入或 MCP：优先查看 frontend/src/views/embedded、backend/apps/mcp 和助手配置。
  • 调整网关能力：优先查看 api-node/src/proxy、api-node/src/health 和 api-node/src/config。