v2.2.0 · Python 3.11+ · FastAPI · D3.js
中文 | English
面向 Oracle 脚本 与 企业数仓 SQL 的开源字段级数据血缘分析系统。
解析 DDL / DML / 存储过程 / 控制文件 / 指标表，构建表级与字段级血缘、口径链与可视化图谱，用于数据治理、影响分析、审计复核与改造评估。
更多演示：演示说明 · Demo walkthrough
审核或改造时，经常要回答：
- 这个字段从哪里来？经过了哪些表、过程、表达式？
- 改一张中间表，会冲击哪些下游报表与指标？
- 能否导出可复核的口径证据，而不是只看一张图？
本系统把这些问题落到可查询的图与可导出的证据上。
| 能力 | 说明 |
|---|---|
| 字段级血缘 | BFS 追溯上下游，支持 upstream / downstream / both |
| 企业数仓分层 | 识别 SRC → MSL → ITL → IOL → ICL → IML → IDL → IEL → DQC 等层级（共 17 种） |
| Type5 ICL 交换表 | 将 xxx_ex 映射回正式表，避免分区交换导致血缘断裂 |
| 口径追溯与导出 | 提取加工口径，导出 Excel 审计证据 |
| 指标血缘 | 针对指标表与配置的专项构建 |
| D3 可视化 | 分层着色、路径高亮、搜索与节点详情 |
SOURCE_DATA/ → ParserRegistry → SQLite / 内存索引 → LineageService / CaliberTracer → API + D3
三层边界：app/api（路由）→ app/services（编排）→ core/（纯算法，不依赖 FastAPI）。
环境：Python 3.11+，pip 或 uv
python3.11 -m venv .venv
source .venv/bin/activate
python3.11 -m pip install -r requirements.txt
# 默认端口 8899
python3.11 run_app.py
# 强制重新解析数据源
python3.11 run_app.py --reparse打开：
| 入口 | URL |
|---|---|
| 前端图谱 | http://localhost:8899/static/index.html |
| API 文档 | http://localhost:8899/docs |
也可用 ./start.sh / ./stop.sh 管理后台进程。
示例 SQL 见 docs/examples/oracle_warehouse_lineage.sql。
CREATE TABLE ICL.CUSTOMER_DAILY_SNAPSHOT AS
SELECT
c.CUST_ID,
c.CUST_NAME,
a.ACCT_BALANCE,
CASE WHEN a.ACCT_BALANCE > 100000 THEN 'VIP' ELSE 'STANDARD' END AS CUSTOMER_TIER
FROM IML.CUSTOMER_PROFILE c
LEFT JOIN IOL.ACCOUNT_BALANCE a
ON c.CUST_ID = a.CUST_ID;curl -X POST http://localhost:8899/api/lineage/query \
-H 'Content-Type: application/json' \
-d '{
"target_table": "ICL.CUSTOMER_DAILY_SNAPSHOT",
"target_field": "CUSTOMER_TIER",
"direction": "upstream"
}'输出示例：docs/examples/lineage_query_output.json
将脚本放入 SOURCE_DATA/（不参与版本控制）：
SOURCE_DATA/
├── EDW/ # 数仓 DDL / DML
├── BRT/ # 报表等业务脚本
├── RRP/ # Oracle .tab / .prc 等
└── manifest.yml # 数据源与解析配置（可选）
| 能力 | 方法 | 路径 |
|---|---|---|
| 血缘查询 | POST | /api/lineage/query |
| 快捷血缘 | GET | /api/lineage/{table}/{field} |
| 口径查询 | POST | /api/caliber/query |
| 口径导出 | POST | /api/caliber/export |
| 指标血缘 | POST | /api/indicator/build |
| 表 / 过程搜索 | GET | /api/tables · /api/procedures |
| 文件 / 目录解析 | POST | /api/parse/upload · /api/parse/directory |
| 系统统计 / 层级 | GET | /api/stats · /api/system/layers |
完整契约见启动后的 Swagger：/docs。
| 层级 | 技术 |
|---|---|
| 后端 | FastAPI + Python 3.11+ |
| 模型 | Pydantic v2 + dataclass |
| SQL 解析 | sqlglot + Oracle / 数仓专用解析器 |
| 前端 | D3.js v7 + 原生 JS |
| 缓存 | SQLite（默认）+ 内存索引；可选 legacy pickle/json |
python3.11 -m pytest tests/
python3.11 -m pytest tests/test_lineage_api.py -v本地质量门禁（可选）：
bash scripts/install-git-hooks.sh # 安装 pre-commit / pre-push
scripts/agent-verify.sh quick # 提交前快检
scripts/agent-verify.sh full # 推送前全量测试| 文档 | 说明 |
|---|---|
| 演示说明 | 界面与查询走查 |
| v2.2.0 发布说明 | 含 ICL 血缘修复与 17 层级扩展 |
| 变更日志 | 版本历史 |
| 贡献指南 | 开发约定与提交范围 |
| 安全策略 | 漏洞报告 |
| 路线图 | 后续方向 |
| 代码 Wiki | 模块导航 |
| 架构评估 | 架构说明 |
SOURCE_DATA/含真实业务脚本时已在.gitignore中忽略，勿提交真实数据- 无外部数据库依赖；结果默认落在本地 SQLite / 内存索引
- 生产环境请配置
ADMIN_API_KEY保护缓存重建等管理接口