# sql-lineage **Repository Path**: yeswater/sql-lineage ## Basic Information - **Project Name**: sql-lineage - **Description**: 企业级 SQL 血缘分析平台:JSqlParser + SQLGlot Sidecar + AI 混合引擎,Vue3 图谱与 AI 工作区,Docker Compose 一键部署,支持离线镜像包。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 3 - **Created**: 2026-06-16 - **Last Updated**: 2026-11-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SQL 血缘分析平台 面向小规模数据团队的 **AI 单引擎 SQL 血缘平台**。平台用固定的 AI JSON 契约提取表级/字段级血缘,再由平台侧校验器做结构、引用和元数据校验,输出可审计的质量状态。 ## 当前形态 | 维度 | 实现 | |---|---| | 解析引擎 | AI 唯一解析器,不保留传统解析器 fallback | | 质量状态 | `VERIFIED` / `PARTIAL` / `UNVERIFIED` | | 后端 | Java 21 + Spring Boot 3.3 + MyBatis Plus | | 数据库 | PostgreSQL 16,`lineage_v2` schema,8 张核心表 | | 前端 | React 18 + Vite + Tailwind CSS,4 个页面 | | 批量执行 | 本地线程池,单批最多 200 条,AI 并发 2 | | 登录权限 | 无登录;默认只监听 `127.0.0.1` | | 消息队列 | 无 | | 外部解析服务 | 无 | ## 分析链路 ```text SQL 文本 → 确定性脚本切分(只切语句,不解析 AST) → 候选元数据选择 → AI 输出固定 JSON → JSON 契约/枚举/引用完整性/表列存在性/关系去重校验 → VERIFIED / PARTIAL / UNVERIFIED → 幂等持久化 → PostgreSQL 递归 CTE 查询上下游 ``` AI 结构错误只允许一次“带校验错误上下文”的修复重试。重试后仍不合法时保存原始响应并标记 `UNVERIFIED`,不会把模型自报置信度当作质量结论。 ## 页面 - `/#/import`:SQL 文本、单条分析、XLSX/CSV/TXT 批量导入、任务进度、失败重试、数据源与 DDL 元数据准备。 - `/#/lineage`:全局表级图、表中心上下钻、字段级关系、元数据树、质量与告警详情。 - `/#/lineage/sql/:hash`:原始 SQL、AI 摘要、质量状态、表节点、字段映射和重新分析。 - `/#/models`:多模型 CRUD、默认模型、连通性测试。 ## 本地启动 前置:JDK 21、Maven 3.9+、Node 20+、pnpm、PostgreSQL 16。 1. 创建数据库并初始化: ```bash createdb sql_lineage psql -d sql_lineage -f docs/sql/lineage_v2.sql ``` 2. 配置 AI Key: ```bash export AI_API_KEY="your-key" export AI_BASE_URL="https://api.deepseek.com" export AI_MODEL="deepseek-chat" ``` 也可以不设置环境变量,在 `/#/models` 页面添加模型并设为默认。 3. 启动后端: ```bash cd sql-lineage-server mvn spring-boot:run ``` 4. 启动前端: ```bash cd sql-lineage-web-react pnpm install pnpm dev ``` 访问 `http://127.0.0.1:5174`。后端默认绑定 `127.0.0.1:8080`。 ## Docker Compose ```bash cd deploy cp .env.example .env # 编辑 .env,至少填写 AI_API_KEY 和 AI_KEY_SECRET docker compose up -d --build ``` - Web:`http://127.0.0.1:5173` - API:`http://127.0.0.1:8080` - PostgreSQL:`127.0.0.1:5432` 所有端口都绑定本机地址。不要把无登录实例直接暴露到公网;如需公网访问,必须在外层增加认证、TLS 和访问控制。 容器内后端为配合 Nginx 反向代理会监听 `0.0.0.0`,但 Compose 只把宿主机端口绑定到 `127.0.0.1`;非容器模式默认仍监听 `127.0.0.1`。 ## 核心数据模型 1. `lineage_datasource` 2. `lineage_table_metadata` 3. `lineage_ai_model` 4. `lineage_analysis` 5. `lineage_table_node` 6. `lineage_relation` 7. `lineage_analysis_task` 8. `lineage_analysis_error` 完整 DDL 与逐列注释见 [`docs/sql/lineage_v2.sql`](docs/sql/lineage_v2.sql)。 ## API 概览 统一响应: ```json { "code": 200, "message": "success", "data": {}, "timestamp": 0 } ``` 入口: - `POST /api/v1/lineage/analyze` - `GET /api/v1/lineage/graph` - `GET /api/v1/lineage/graph/global` - `GET /api/v1/lineage/sql/{hash}` - `POST /api/v1/lineage/import/text` - `POST /api/v1/lineage/import/file` - `GET /api/v1/lineage/tasks/{taskId}` - `POST /api/v1/lineage/errors/{errorId}/retry` - 数据源、DDL、表元数据 CRUD 与同步 - AI 模型 CRUD、默认模型、连通性测试 完整列表见 [`docs/api.md`](docs/api.md)。 ## 验证命令 ```bash cd sql-lineage-server && mvn clean test cd sql-lineage-web-react && pnpm build # 包含 tsc --noEmit cd deploy && docker compose config ``` ## 已知边界 - 数据源同步首期只实现 PostgreSQL;其他数据库通过 DDL 导入元数据。 - 无完整元数据时质量最高为 `PARTIAL`,不会把未知表/列标为已验证。 - AI 实际效果依赖所选模型。仓库提供黄金测试集与评估脚本,运行真实评估需要可用的 AI Key、PostgreSQL 和已导入的元数据。 - 旧库不迁移、不兼容;全新部署使用 `lineage_v2`。