# 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**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQL 血缘分析平台

企业级 **SQL 血缘分析** 平台：传统解析引擎（JSqlParser / SQLGlot Sidecar）与 AI 大模型混合驱动，提供表级/字段级血缘、图谱可视化、AI 工作区、实时血缘追踪与企业 IAM 管理能力。

---

## 目录

- [系统介绍](#系统介绍)
- [技术栈](#技术栈)
- [项目模块](#项目模块)
- [系统架构](#系统架构)
- [功能概览与截图](#功能概览与截图)
- [快速开始（本地开发）](#快速开始本地开发)
- [Docker Compose 部署](#docker-compose-部署)
- [Gitee Release 离线包（推荐 Windows）](#gitee-release-离线包推荐-windows)
- [Docker Load 离线部署](#docker-load-离线部署)
- [功能使用说明](#功能使用说明)
- [数据库初始化](#数据库初始化)
- [默认账号与环境变量](#默认账号与环境变量)
- [相关文档](#相关文档)

---

## 系统介绍

平台面向数据仓库、数据中台与 SQL 治理场景，核心能力包括：

| 能力 | 说明 |
|------|------|
| **混合血缘分析** | JSqlParser + SQLGlot Sidecar + DeepSeek AI，支持 HYBRID / PARSER_ONLY / AI_ONLY 模式 |
| **多源导入** | 单条 SQL、Excel、JSON、批量 MQ 异步分析 |
| **血缘图谱** | G6 力导向/分层图，表节点与字段级关系可视化 |
| **AI 工作区** | 三段式布局：会话列表 / Composer / 流程·洞察·工具面板 |
| **实时血缘** | RocketMQ 驱动的 SQL 流捕获与实时分析 |
| **企业 IAM** | 用户/角色/部门/岗位/菜单权限、数据权限范围 |
| **AI 平台 Hub** | 模型资源、Prompt、知识库、MCP 工具、质量观测统一配置 |
| **运维监控** | 错误日志、Prometheus + Grafana 监控大盘（可选） |

---

## 技术栈

| 层级 | 技术 |
|------|------|
| **后端** | Java 21、Spring Boot 3.3、Spring Security + JWT、MyBatis Plus |
| **AI** | Spring AI、LangGraph4j（StateGraph 流程编排）、DeepSeek API |
| **消息队列** | Apache RocketMQ 5.x |
| **数据库** | PostgreSQL 16 |
| **SQL 解析** | JSqlParser（内置）、SQLGlot Sidecar（Python FastAPI） |
| **前端** | Vue 3、Vite、Pinia、Element Plus、AntV G6、CodeMirror |
| **部署** | Docker Compose、Nginx、Prometheus、Grafana |
| **测试** | JUnit 5、Mockito、Vitest、pytest、集成测试脚本 |

---

## 项目模块

```
sql-lineage/
├── sql-lineage-server/     # Spring Boot 后端（DDD 分层单体）
├── sql-lineage-web/        # Vue 3 前端
├── sqlglot-sidecar/        # Python SQLGlot 解析 Sidecar
├── deploy/                 # Docker Compose、监控配置、离线镜像包
├── docs/                   # 系统设计文档、DDL、开发计划
├── scripts/                # 集成测试、数据清理脚本
└── sdk/                    # Java / Python 客户端 SDK
```

| 模块 | 职责 |
|------|------|
| `sql-lineage-server` | REST API、血缘分析引擎、AI Agent、IAM、MQ 消费 |
| `sql-lineage-web` | 管理控制台 UI、血缘图谱、AI 工作区 |
| `sqlglot-sidecar` | 多方言 SQL AST 解析，补充 JSqlParser 覆盖 |
| `deploy` | 一键容器化部署与离线镜像导出 |
| `sdk/java` · `sdk/python` | 第三方系统集成 SDK |

---

## 系统架构

```mermaid
flowchart TB
    subgraph Client["客户端"]
        Browser["浏览器 / SDK"]
    end

    subgraph Web["sql-lineage-web"]
        Nginx["Nginx 静态资源 + API 反代"]
    end

    subgraph Server["sql-lineage-server"]
        API["REST / WebSocket"]
        Graph["LangGraph 分析流程"]
        IAM["IAM / RBAC"]
        AI["Spring AI + MCP"]
    end

    subgraph Parse["解析层"]
        JSP["JSqlParser"]
        Sidecar["SQLGlot Sidecar"]
    end

    subgraph Infra["基础设施"]
        PG[(PostgreSQL)]
        MQ[[RocketMQ]]
        AIAPI["DeepSeek API"]
    end

    subgraph Ops["运维（可选）"]
        Prom["Prometheus"]
        Graf["Grafana"]
    end

    Browser --> Nginx
    Nginx --> API
    API --> Graph
    Graph --> JSP
    Graph --> Sidecar
    Graph --> AI
    AI --> AIAPI
    API --> PG
    Graph --> MQ
    MQ --> Graph
    API --> Prom
    Prom --> Graf
```

**分析主路径（HYBRID 模式）**：SQL 输入 → 方言检测 → Sidecar/JSqlParser 解析 → 元数据增强 → AI 融合（可选）→ 持久化 → 图谱展示。

---

## 功能概览与截图

> 截图存放于 `docs/readme/screenshots/`。部署完成后可按下列路径补充实际截图。

| 功能 | 路径 | 截图文件 |
|------|------|----------|
| AI 工作区 | `/dashboard` | `01-ai-workspace.png` |
| 血缘分析 | `/lineage` | `02-lineage-analyze.png` |
| 血缘图谱 | `/data-browser` | `03-lineage-graph.png` |
| 流程跟踪 | `/flow-tracking` | `04-flow-tracking.png` |
| AI 平台 Hub | `/settings/ai-platform` | `05-ai-platform.png` |
| 权限管理 Hub | `/settings/admin/permission` | `06-permission-hub.png` |
| 监控大盘 | `/ops/monitoring` | `07-monitoring.png` |

---

## 快速开始（本地开发）

### 环境要求

- JDK 21（`export JAVA_HOME=$(/usr/libexec/java_home -v 21)`）
- Maven 3.9+
- Node.js 20+
- Docker（PostgreSQL、RocketMQ）
- DeepSeek 或兼容 OpenAI API 的 Key

### 1. 启动中间件

```bash
cd deploy
docker compose up -d postgres rocketmq-namesrv rocketmq-broker sqlglot-parser
```

### 2. 初始化数据库

```bash
psql -h 127.0.0.1 -U lineage -d sql_lineage -f docs/sql/schema.sql
psql -h 127.0.0.1 -U lineage -d sql_lineage -f docs/sql/iam-migration.sql
```

### 3. 启动后端

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export AI_API_KEY=sk-your-key
cd sql-lineage-server
mvn spring-boot:run
```

### 4. 启动前端

```bash
cd sql-lineage-web
npm ci
npm run dev
# http://localhost:5173
```

### 5. 运行测试

```bash
cd sql-lineage-server && mvn test
cd sql-lineage-web && npx vitest run
cd sqlglot-sidecar && python3 -m pytest test_analyzer.py -v
bash scripts/integration-test.sh   # 需前后端 + sidecar 运行
```

---

## Docker Compose 部署

推荐生产/演示环境使用 Compose 全栈启动。

### 步骤

```bash
cd deploy
cp .env.example .env
# 编辑 .env，至少设置 AI_API_KEY

chmod +x scripts/*.sh
./scripts/start.sh
```

含 Prometheus + Grafana 监控：

```bash
./scripts/start.sh --monitoring
```

### 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 | 80 | Nginx |
| 后端 API | 8080 | Spring Boot |
| SQLGlot Sidecar | 8081 | Python 解析 |
| PostgreSQL | 5432 | 业务库 |
| RocketMQ NameServer | 9876 | MQ |
| RocketMQ Dashboard | 8086 | MQ 控制台 |
| Prometheus | 9090 | profile: monitoring |
| Grafana | 3000 | profile: monitoring |

### 常用命令

```bash
cd deploy
docker compose ps
docker compose logs -f sql-lineage-server
docker compose down
docker compose down -v   # 同时删除数据卷（清空数据库）
```

**RocketMQ Broker 启动失败（`ScheduleMessageService` NPE）**：多为 `rocketmq_store` 卷权限问题（卷属 root，Broker 进程为 uid 3000）。当前 compose 已通过 `deploy/rocketmq/broker-entrypoint.sh` 在启动前 `chown`。若仍异常，可重建 Broker 卷：

```bash
docker compose stop rocketmq-broker
docker volume rm deploy_rocketmq_store deploy_rocketmq_logs
docker compose up -d rocketmq-broker
```

数据库在首次启动 postgres 容器时自动执行 `docs/sql/schema.sql` 与 `docs/sql/iam-migration.sql`。

---

## Gitee Release 离线包（推荐 Windows）

**不要**把约 2.5GB 的 Docker 镜像 tar 提交进 Git 源码库（clone 极慢、占配额）。  
**推荐**从 [Gitee 发行版](https://gitee.com/yeswater/sql-lineage/releases) 下载对应版本的离线包。

| 场景 | 做法 |
|------|------|
| Windows / 内网，无法跑 Maven·npm | 下载 Release 附件 → 解压到 `deploy/` → 见下方 Windows 步骤 |
| 有 Linux/Mac 构建环境 | 自行 `export-images.sh` 或下载 Release |

### Windows 快速部署

1. 安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
2. 克隆源码（或只下载 `deploy/` 目录）：
   ```powershell
   git clone https://gitee.com/yeswater/sql-lineage.git
   ```
3. 从 **发行版** 下载 `sql-lineage-offline-vX.Y.Z.zip`，解压后将 `images/` 放入 `deploy/images/`
4. 配置并启动：
   ```powershell
   cd sql-lineage\deploy
   copy .env.example .env
   # 编辑 .env，填入 AI_API_KEY
   .\scripts\load-images.ps1
   docker compose up -d --no-build
   ```
5. 浏览器打开 http://localhost ，账号 `admin` / `admin123`

> 镜像为 **linux/amd64**，在 Windows Docker Desktop 下通过 WSL2/Hyper-V 运行。  
> 维护者发布流程见 [docs/gitee/仓库简介与Release发布指南.md](docs/gitee/仓库简介与Release发布指南.md)。

---

## Docker Load 离线部署

适用于无外网或无法本地构建的目标机器（Mac / Linux / Windows Docker Desktop）。

> **Windows 用户**优先从 [Gitee 发行版](https://gitee.com/yeswater/sql-lineage/releases) 下载离线包。

### 在有网络的机器上导出

```bash
cd deploy
./scripts/export-images.sh
```

镜像 tar 包输出至 `deploy/images/`（详见 [deploy/images/README.md](deploy/images/README.md)）。

### 在目标机器上加载并启动

将 `deploy/` 目录（含 `images/*.tar`）拷贝到目标机器：

```bash
cd deploy
cp .env.example .env    # 填入 AI_API_KEY
./scripts/start.sh --offline
```

含监控：

```bash
./scripts/start.sh --offline --monitoring
```

也可手动加载：

```bash
./scripts/load-images.sh
docker compose up -d --no-build
```

---

## 功能使用说明

### 登录

- 地址：http://localhost（Compose）或 http://localhost:5173（本地 dev）
- 默认账号：`admin` / `admin123`

### 血缘分析

1. 进入 **血缘分析**，输入 SQL 或上传 Excel/JSON
2. 在 **个人偏好 → 解析引擎** 配置分析模式（HYBRID / PARSER_ONLY / AI_ONLY）
3. 分析完成后进入详情页查看表/字段血缘、冲突审核与 Schema 建模建议

### AI 工作区

1. 登录后默认进入 **AI 工作区**
2. 左侧管理会话，中间输入 SQL 或自然语言，右侧查看流程/洞察/工具调用结果
3. 在 **AI 平台** Hub 配置模型、Prompt、知识库与 MCP 工具

### 权限管理

- **系统管理 → 权限管理**：Tab 切换角色、部门、岗位、菜单
- **系统管理 → 用户管理**：分配角色与数据权限范围

### 运维

- **错误日志**：查看分析失败记录并重试
- **监控大盘**：嵌入 Grafana 仪表盘（需 `--profile monitoring`）

---

## 数据库初始化

| 文件 | 用途 |
|------|------|
| `docs/sql/schema.sql` | 血缘/配置/AI 扩展表 + 系统配置种子（Docker `01-schema.sql`） |
| `docs/sql/iam-migration.sql` | IAM 表、菜单种子、增量迁移（Docker `02-iam.sql`，可重复执行） |

手动初始化：

```bash
psql -U lineage -d sql_lineage -f docs/sql/schema.sql
psql -U lineage -d sql_lineage -f docs/sql/iam-migration.sql
```

侧栏菜单与 `sql-lineage-web/src/shared/settingsHubNav.ts` 保持一致，权威数据源为 `lineage.sys_menu`。

---

## 默认账号与环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AI_API_KEY` | DeepSeek / OpenAI 兼容 API Key | **必填** |
| `SPRING_DATASOURCE_USERNAME` | 数据库用户 | `lineage` |
| `SPRING_DATASOURCE_PASSWORD` | 数据库密码 | `lineage@2024` |
| `JWT_SECRET` | JWT 签名密钥 | `change-me-in-production` |
| `REALTIME_SIMULATOR` | 实时血缘模拟器 | `true` |

完整列表见 [deploy/.env.example](deploy/.env.example)。

---

## 相关文档

| 文档 | 说明 |
|------|------|
| [系统设计文档](docs/SQL血缘分析平台系统设计文档.md) | 整体架构、API、数据模型 |
| [分阶段开发原则](docs/dev-plan/分阶段开发总体原则与附录.md) | 开发规范与测试策略 |
| [栏目导航规范](.cursor/rules/navigation-structure.mdc) | 侧栏与 Hub 结构 |
| [集成测试脚本](scripts/integration-test.sh) | API 端到端验证 |

---

## License

本项目采用 [Apache License 2.0](LICENSE) 开源协议。

Copyright © 2026 [wateryes](https://gitee.com/yeswater)