数据治理 DataHub

第一章：DataHub 概述

1.1 什么是 DataHub

概念名称	说明	注意事项
DataHub	由 LinkedIn 开源的元数据管理平台，用于构建企业级数据目录和元数据服务。	不是数据存储系统，而是元数据的”操作系统”，专注于数据发现、血缘和治理。
元数据平台	统一管理技术、业务和操作元数据的系统，支持搜索、血缘、策略等能力。	需与其他数据系统（如 Hive、Snowflake、Airflow）集成才能获取元数据。
开源项目	基于 Apache 2.0 许可证，由 LinkedIn 贡献并持续维护。	社区活跃，但企业级功能（如高级权限）可能需要自行扩展或使用商业版本（如 Acryl DataHub）。
实时元数据	支持近实时的元数据更新与传播，基于事件驱动架构（Event-Driven）。	实时性依赖于 Kafka 和摄取任务的配置，延迟通常在秒级。

1.2 DataHub 的核心概念

概念名称	说明	注意事项
Entity（实体）	数据目录中的核心对象，如 Dataset、Dashboard、Data Pipeline、User 等。	每个实体有唯一 URN（Uniform Resource Name），如 urn:li:dataset:(urn:li:dataPlatform:kafka,PageViewEvent,PROD)。
Aspect（方面）	描述实体某一维度的元数据，如 schema、ownership、description 等。	一个实体可拥有多个 Aspect，更新元数据即更新其 Aspect。
Snapshot	表示某个实体在某一时刻的所有 Aspect 的集合，用于数据同步。	在元数据摄取中以 MCE（Metadata Change Event）形式发送。
MCE（Metadata Change Event）	元数据变更事件，用于向 DataHub 发送新增或更新的元数据。	通常通过 Kafka 发送，也可通过 CLI 或 REST API 提交。
MCP（Metadata Change Proposal）	元数据变更提案，用于删除或软更新元数据（如删除字段）。	支持撤销操作，是实现元数据版本控制的基础。
URN（统一资源名）	全局唯一标识符，用于标识每个 Entity。	格式为 urn:li:<entityType>:<opaqueId>，不可重复。

1.3 DataHub 的架构组成

组件名称	说明	注意事项
GMS（Graph Metadata Service）	核心后端服务，处理元数据读写、搜索、血缘等请求。	基于 REST 和 GraphQL API，是所有客户端交互的入口。
Frontend（前端服务）	提供 Web UI，支持数据浏览、搜索、编辑等操作。	基于 React 构建，可定制化开发。
Kafka	消息队列，用于异步传输 MCE 和 MCP 事件。	必须配置正确 topic（如 MetadataChangeProposal_v1），否则摄取失败。
Elasticsearch	提供全文搜索和过滤功能，支持快速检索数据集、字段等。	需定期维护索引，避免性能下降。
MySQL / PostgreSQL	存储结构化元数据（如实体关系、用户信息等）。	默认使用 MySQL，生产环境建议使用 PostgreSQL 以提高稳定性。
Kafka Connect	可选组件，用于连接外部系统并自动摄取元数据。	适用于大规模、持续集成场景。

1.4 DataHub 与其他数据平台的对比

对比项	DataHub	Apache Atlas	Amundsen	备注
开源背景	LinkedIn 开源，社区活跃	Apache 项目，Hadoop 生态	Lyft 开源，现由 Linux 基金会维护	DataHub 架构更现代，支持实时性更强
元数据模型	基于 Entity-Aspect 模型，灵活可扩展	基于类型系统，较复杂	基于 Neo4j 图模型，侧重搜索	DataHub 的模型更易于理解和扩展
实时性	支持近实时元数据更新（秒级）	近实时，依赖 Kafka	批处理为主，延迟较高	DataHub 更适合动态数据环境
血缘支持	内置强大血缘功能，支持手动与自动采集	支持血缘，但配置复杂	血缘功能较弱	DataHub 血缘可视化更直观
搜索能力	基于 Elasticsearch，搜索速度快	支持搜索，性能一般	基于 Elasticsearch，搜索优秀	三者均支持搜索，DataHub 与 Amundsen 更优
易用性	提供 CLI、SDK、UI，集成方便	配置复杂，学习曲线陡峭	UI 简洁，但功能较少	DataHub 在易用性和功能之间平衡最好
扩展性	插件化架构，支持自定义 Aspect 和摄取器	可扩展，但需深入源码	扩展性一般	DataHub 更适合定制化开发

第二章：环境准备与安装

2.1 系统要求与依赖环境

依赖项	要求说明	注意事项
操作系统	Linux 或 macOS（推荐 Ubuntu 20.04+ 或 macOS 12+）	Windows 用户建议使用 WSL2 或 Docker Desktop
Docker	版本 ≥ 20.10，启用 Docker BuildKit	必须安装 Docker Engine 和 Docker Compose
Docker Compose	版本 ≥ v2.23.0（docker compose 插件）	注意是 docker compose（无连字符）而非 docker-compose（旧版）
内存	至少 8GB RAM，推荐 16GB 以上	DataHub 组件较多，内存不足会导致服务启动失败
磁盘空间	至少 10GB 可用空间	日志和 Elasticsearch 索引会占用较多空间
网络	可访问外网（下载镜像），开放 8080（前端）、9090（GMS）端口	防火墙或代理可能影响服务访问
Java（可选）	若从源码构建，需 JDK 11+	仅用于开发或定制构建，常规使用无需安装
Python（可选）	若使用 Python SDK，需 Python 3.8+	推荐使用虚拟环境隔离依赖

2.2 安装 DataHub（Docker 方式）

方法/步骤	语法/命令	用途	代码示例	注意事项
克隆仓库	git clone https://github.com/datahub-project/datahub.git	获取 DataHub 源码和 Docker 配置文件	git clone https://github.com/datahub-project/datahub.git	确保网络可访问 GitHub，或使用镜像源
进入目录	cd datahub/docker	进入 Docker 部署目录	cd datahub/docker	目录结构包含 docker-compose.yml 等关键文件
启动服务	docker compose up -d	后台启动所有 DataHub 服务	docker compose up -d	首次运行会下载多个镜像，耗时较长（10-30 分钟）
查看服务状态	docker compose ps	检查各容器是否正常运行	docker compose ps	确保 datahub-frontend、gms、kafka 等状态为 running
日志查看	docker compose logs <service-name>	调试服务启动问题	docker compose logs kafka	若服务未启动，查看日志定位错误（如端口冲突、内存不足）
停止服务	docker compose down	停止并删除容器	docker compose down	数据会保留在卷中，重启后仍存在
清除数据	docker compose down -v	停止服务并删除持久化数据（卷）	docker compose down -v	谨慎使用，将清除所有元数据

2.3 安装 DataHub（Kubernetes 方式）

方法/步骤	语法/命令	用途	代码示例	注意事项
添加 Helm 仓库	helm repo add datahub https://helm.datahubproject.io/	添加 DataHub Helm 仓库	helm repo add datahub https://helm.datahubproject.io/	需预先安装 Helm
更新仓库	helm repo update	同步最新 Chart 信息	helm repo update	每次安装前建议执行
安装 Chart	helm install datahub datahub/datahub --version <version>	使用 Helm 安装 DataHub	helm install datahub datahub/datahub --version 0.26.0	可指定版本，避免使用 latest
自定义配置	helm install datahub datahub/datahub -f my-values.yaml	使用自定义 values.yaml 配置资源、副本、存储等	helm install datahub datahub/datahub -f my-values.yaml	用于生产环境定制化部署
查看部署状态	kubectl get pods	检查 Pod 是否就绪	kubectl get pods	所有 Pod 应为 Running 状态
访问前端服务	kubectl port-forward service/datahub-frontend 8080:80	本地访问 Web UI	kubectl port-forward service/datahub-frontend 8080:80	确保 Kubernetes 集群网络配置正确
升级部署	helm upgrade datahub datahub/datahub -f my-values.yaml	升级到新版本或更新配置	helm upgrade datahub datahub/datahub -f my-values.yaml	支持滚动更新，减少停机时间
删除部署	helm uninstall datahub	卸载 DataHub	helm uninstall datahub	保留 PVC 需手动删除，否则数据可能残留

2.4 验证安装与启动服务

验证项	检查方法	预期结果	注意事项
服务进程状态	docker compose ps（Docker）或 kubectl get pods（K8s）	所有服务（如 frontend、gms、kafka、elasticsearch）处于 running 或 Running 状态	任一服务异常需查看日志排查
端口监听	netstat -an | grep 8080 或 lsof -i :8080	本地 8080 端口被监听	若端口被占用，修改 docker-compose.yml 中端口映射
Web UI 访问	浏览器访问 http://localhost:8080	显示 DataHub 登录页面或主页	首次加载可能较慢，等待 1-2 分钟
GraphQL API 测试	访问 http://localhost:8080/api/graphiql	打开 GraphQL IDE，可执行查询	可执行 { viewer { urn } } 测试是否返回用户 URN
Kafka 主题检查	docker compose exec kafka kafka-topics.sh --bootstrap-server localhost:9092 --list	显示包含 MetadataChangeProposal_v1 等主题	确保 Kafka 正常运行
Elasticsearch 索引	curl http://localhost:9200/_cat/indices	显示 datasetindex、corpuserindex 等索引	需确保 Elasticsearch 服务已就绪
CLI 连接测试	datahub login -u datahub -p datahub	返回登录成功	需先安装 datahub-cli（pip install acryl-datahub）

第三章：数据模型与元数据基础

3.1 元数据分类：技术元数据 vs 业务元数据

元数据类型	说明	示例	注意事项
技术元数据	描述数据的技术属性，由系统自动生成或从源系统提取。	字段名、字段类型、分区信息、数据平台（如 Kafka、Snowflake）、行数、大小等	是数据发现和血缘分析的基础，通常通过摄取器自动采集
业务元数据	描述数据的业务含义，通常由人工维护或流程化管理。	数据所有者（Owner）、敏感等级（PII）、业务术语、数据质量规则、使用场景等	提升数据可理解性，需与数据治理流程结合，避免信息滞后或不一致
操作元数据	记录数据的操作历史和运行状态。	最近访问时间、ETL 作业执行日志、摄取时间、失败记录等	用于监控和审计，支持数据生命周期管理
管理元数据	涉及权限、策略、合规性等管理信息。	访问控制列表（ACL）、保留策略、数据分类标签、审批流程等	通常与外部 IAM 系统集成，实现统一权限控制

3.2 DataHub 中的核心实体（Entities）

实体名称	说明	URN 示例	注意事项
Dataset	表示一个数据集，如数据库表、Kafka 主题、S3 文件等。	urn:li:dataset:(urn:li:dataPlatform:snowflake,analytics.users,PROD)	最常用实体，支持 schema、ownership、lineage 等多个 Aspect
Dashboard	表示一个可视化仪表板，如 Tableau、Looker 仪表板。	urn:li:dashboard:(looker,sales_overview)	可关联多个 Dataset，用于追踪数据使用场景
Data Pipeline	表示数据处理流程，如 Airflow DAG、Spark Job。	urn:li:dataJob:(airflow,dag_id=etl_users,task_id=transform)	支持血缘上下游分析，是自动化血缘采集的关键
CorpUser	表示组织内的用户，通常是数据所有者或使用者。	urn:li:corpuser:jdoe	用于 ownership、favorites 等功能，支持 SSO 集成
CorpGroup	表示用户组，用于批量管理权限和所有权。	urn:li:corpGroup:data-engineers	可包含多个 CorpUser，简化权限分配
Tag	自定义标签，用于分类或标记数据（如 deprecated、pii）。	urn:li:tag:pii	可应用于任何 Entity，支持搜索过滤
GlossaryTerm	业务术语表中的术语，用于统一业务语义。	urn:li:glossaryTerm:user_id	可与字段级元数据关联，提升数据可读性
Container	表示数据容器，如数据库、Schema、目录等。	urn:li:container:(urn:li:dataPlatform:snowflake,analytics,PROD)	用于组织 Dataset 层级结构，支持导航树

3.3 实体关系模型（Aspect, Entity, Relationship）

概念名称	说明	示例	注意事项
Entity（实体）	数据目录中的顶级对象，具有唯一 URN。	Dataset、Dashboard、CorpUser 等	所有元数据围绕 Entity 组织
Aspect（方面）	描述 Entity 的某一维度信息，以 JSON 形式存储。	schemaMetadata、ownership、description、datasetProperties 等	一个 Entity 可拥有多个 Aspect，更新时只需发送变更的 Aspect
Snapshot	包含一个或多个 Entity 的完整 Aspect 集合，用于批量同步。	MCE 中携带 DatasetSnapshot，包含 schema、ownership 等	是元数据摄取的基本单位
Relationship	表示两个 Entity 之间的关联，如上下游依赖、归属、引用等。	Dataset A → Dataset B（血缘）、Dataset → Owner（所有权）	由 MCP（Metadata Change Proposal）创建，支持图遍历
MCE（Metadata Change Event）	封装 Snapshot，表示新增或全量更新元数据。	发送 DatasetSnapshot 到 Kafka topic MetadataChangeProposal_v1	用于初始化或全量同步
MCP（Metadata Change Proposal）	提案式变更，用于删除、部分更新或建立关系。	删除字段、添加 upstream、修改 description	支持幂等操作和撤销，是实现增量更新的关键

3.4 Schema 设计与命名规范

规范类别	推荐做法	示例	注意事项
Dataset 命名	使用小写字母、下划线，避免特殊字符；体现业务域和用途。	sales_customer_orders、logs_page_view	避免使用缩写或模糊名称（如 tbl1）
分层命名	按数据层级划分（raw、cleaned、aggregated）。	raw_user_events、agg_daily_sales	便于理解数据加工阶段
平台标识	在 URN 或描述中明确数据平台（dataPlatform）。	dataPlatform: snowflake, kafka, hive	支持跨平台搜索和治理
字段命名	使用 snake_case，语义清晰，避免歧义。	user_id、created_timestamp、order_status	不推荐驼峰或连字符
描述规范	每个 Dataset 和关键字段应提供中文或英文描述。	“用户注册事件流，包含注册时间、渠道、设备信息”	描述应简洁、准确，避免空值
Owner 标准	指定真实负责人或团队邮箱，格式为 name@company.com。	owner: jane.doe@acme.com	支持多人，优先使用团队邮箱
Tag 使用	统一 Tag 命名，避免随意创建（如 PII、deprecated、gold）。	tag: pii、tag: gold	建议预先定义 Tag 白名单
Glossary 关联	关键字段应绑定业务术语表（GlossaryTerm）。	字段 user_id → glossaryTerm: "用户唯一标识"	提高非技术人员的数据理解能力

第四章：数据摄取（Ingestion）

4.1 摄取框架概述（MCE, MCP）

方法/概念	语法/消息结构	用途	代码示例（JSON 片段）	注意事项
MCE（Metadata Change Event）	{ "entityType": "dataset", "aspectName": "schemaMetadata", "aspectValue": { ... } }	全量更新 Entity 的某个 Aspect	{ "proposedSnapshot": { "urn": "...", "aspects": [ { "schemaMetadata": { ... } } ] } }	用于首次注册或大规模同步，不可用于删除操作
MCP（Metadata Change Proposal）	{ "entityUrn": "...", "aspectName": "ownership", "changeType": "UPSERT" }	增量更新、删除或建立关系	{ "entityUrn": "urn:li:dataset:...", "aspectName": "upstreamLineage", "changeDirection": "UPSTREAM", "aspect": { "upstreams": [...] } }	支持 UPSERT、DELETE，是血缘、所有权更新的主要方式
消息通道	Kafka topics: MetadataChangeProposal_v1、MetadataChangeLog_v1	异步传输元数据变更	生产者发送到 MetadataChangeProposal_v1，GMS 消费并持久化	必须确保 Kafka 连通性和 topic 存在
摄取方式	CLI、SDK、Airflow Operator、Kafka Producer	不同场景下的元数据提交方式	见后续小节	推荐使用 SDK 或 CLI，避免直接操作 Kafka
失败重试机制	MCP 支持幂等，MCE 可重复发送	保证数据一致性	设置 systemMetadata.runId 区分不同批次	建议为每次摄取任务生成唯一 runId

4.2 使用 DataHub CLI 摄取元数据

方法/命令	语法	用途	代码示例	注意事项
登录认证	datahub login -s <server-url> -u <username> -p <password>	认证连接到 DataHub 实例	datahub login -s http://localhost:8080 -u datahub -p datahub	首次使用需登录，token 保存在本地配置文件
摄取元数据	datahub ingest -c <recipe.yaml>	根据 YAML 配方文件摄取元数据	datahub ingest -c ./ingest-kafka.yaml	配方文件定义 source、sink、pipeline 参数
列出当前配方	datahub check	检查本地配方文件是否有效	datahub check -c ./recipe.yaml	可验证 YAML 格式和连接信息
查看运行历史	datahub admin list-ingestion-jobs --source <source-type>	查看已提交的摄取任务	datahub admin list-ingestion-jobs --source snowflake	需 GMS 支持 Admin API
删除摄取任务	datahub admin delete-ingestion-source --ingestion-source-id <id>	删除不再使用的摄取配置	datahub admin delete-ingestion-source --ingestion-source-id abc123	谨慎操作，删除后历史元数据仍保留
测试连接	datahub check connectivity	测试 CLI 是否能正常连接 GMS 和 Kafka	datahub check connectivity	排查网络或认证问题

4.3 使用 Python SDK 摄取元数据

方法名称	语法	用途	代码示例	注意事项
初始化客户端	DataHubGraph(config)	创建与 GMS 交互的图客户端	graph = DataHubGraph({ "server": "http://localhost:8080", "token": "..." })	需提前获取访问 token
发送 MCE	graph.emit_mce(mce)	发送元数据变更事件	graph.emit_mce(dataset_mce)	mce 需为符合协议的 MetadataChangeEvent 对象
发送 MCP	graph.emit_mcp(mcp)	发送元数据变更提案	graph.emit_mcp(upstream_mcp)	用于更新血缘、所有权等
获取实体详情	graph.get_aspect(entity_urn, aspect_type)	查询某个 Entity 的特定 Aspect	graph.get_aspect("urn:li:dataset:...", "ownership")	若 Aspect 不存在返回 None
批量摄取	MetadataFileLoader.load_from_file() + Emitter.emit()	从文件加载并发送多条元数据	loader = MetadataFileLoader("metadata.json"); for mce in loader: emitter.emit(mce)	支持 JSON、YAML 文件
错误处理	try-except OperationError, UnauthorizedError	处理连接、权限、格式错误	try: graph.emit_mce(...) except UnauthorizedError: print("Token invalid")	建议添加重试逻辑
安装 SDK	pip install acryl-datahub	安装 Python 客户端库	pip install acryl-datahub[...]（可选 extras）	支持 airflow、sql-parser 等插件

4.4 使用 Airflow 集成摄取

方法/Operator	语法	用途	代码示例（DAG 片段）	注意事项
DataHubEmitterOperator	DataHubEmitterOperator(...)	在 Task 中发送 MCE/MCP	DataHubEmitterOperator(task_id="send_mce", mce=mce_dict, ...)	需传递序列化的 MCE/MCP 字典
DataHubIngestionTask	create_datahub_ingestion_task(...)	封装完整摄取流程（类似 CLI）	create_datahub_ingestion_task(recipe_yaml="...", task_id="ingest")	recipe 内容与 CLI 相同
Airflow Hook	DataHubRestHook(datahub_conn_id="datahub_prod")	在自定义 Operator 中复用连接逻辑	hook = DataHubRestHook("datahub_prod"); hook.emit_mce(mce)	conn_id 需在 Airflow UI 中配置
连接配置	Conn Id: datahub_rest, Type: HTTP, Host: http://gms:8080	配置 Airflow 到 GMS 的连接	在 Admin > Connections 中设置	推荐使用 token 认证
血缘自动上报	Airflow 2.5+ 原生支持 DataHub 血缘	自动捕获 Task 输入输出 Dataset	airflow.cfg: [lineage] backend = datahub_provider.lineage.datahub	需启用 openlineage-provider

4.5 摄取配置文件详解（YAML 格式）

配置项	说明	示例值	注意事项
version	配方文件版本	1	固定为 1
run_id	本次摄取任务的唯一标识	ingest-kafka-2024-10-01	建议使用时间戳或任务名，用于去重和追踪
source	数据源配置，定义从哪摄取元数据	{ type: "kafka", config: { ... } }	type 如 snowflake、bigquery、file
source.type	源系统类型	kafka、snowflake、file、mysql 等	必须为 DataHub 支持的 connector
source.config	源系统连接参数	{"connection": {"bootstrap": "broker:9092"}}	根据 source 类型变化，可包含用户名、密码、host、database 等
sink	目标配置，定义元数据发送到哪	{ type: "datahub-rest", config: { "server": "http://localhost:8080" } }	常用 datahub-rest 或 datahub-kafka
pipeline	处理流水线，可添加 filter、transformer	[{ type: "filter", config: { "field": "platform", "value": "kafka" } }]	用于预处理，如过滤特定 dataset
recipes	（可选）多个配方组合	数组形式包含多个独立配方	适用于复杂场景
必需字段	version、run_id、source、sink		缺少任一将导致解析失败
注释支持	使用 # 添加注释	# This is a comment	提高配置可读性

第五章：数据发现与搜索

5.1 数据集搜索功能使用

功能	说明	使用方式	示例	注意事项
全文关键词搜索	支持在名称、描述、字段、标签等中模糊匹配关键词。	在 DataHub 主页搜索框输入关键词（如 user、sales）	搜索 orders 显示所有包含该词的 Dataset、Dashboard 等	支持中文（需配置分词器），响应时间受数据量影响
高级搜索入口	提供多条件组合筛选界面。	点击搜索框右侧”高级搜索”按钮进入筛选面板	选择平台为 snowflake，所有者为 data-team	适合复杂查询，可保存常用搜索视图
快速跳转	输入 URN 或 Dataset 名称可直接跳转到详情页。	在搜索框输入完整或部分 URN（如 analytics.users）	输入 kafka://page_views 跳转到 Kafka 主题详情	URN 格式必须正确
搜索建议	输入时自动提示匹配的实体名称。	输入 use，下拉提示 users、user_events、user_profile	提升搜索效率，减少拼写错误	建议使用标准命名规范以提高提示准确率
搜索历史	记录用户最近的搜索记录。	搜索框下拉显示历史关键词	快速复用之前的查询	可清除本地历史
排序与分页	支持按相关性、最近更新、访问频率等排序。	在搜索结果页选择”排序方式”	按”最近更新”排序查看最新注册的数据集	默认按相关性排序

5.2 搜索语法与过滤条件

语法/过滤项	说明	语法格式	示例	注意事项
字段前缀搜索	按特定元数据字段进行精确或模糊匹配。	field:value	platform:snowflake、owner:jdoe@acme.com	支持自动补全字段名
多值匹配	同一字段匹配多个值（OR 关系）。	field:(value1 OR value2)	tag:(pii OR gdpr)、platform:(kafka OR s3)	使用括号和 OR，不支持 AND 在括号内
模糊匹配	使用通配符 * 进行模糊搜索。	field:valu*、name:user_*	dataset:raw_*、field:email*	* 可出现在开头或结尾，避免全模糊（如 *user*）性能差
短语搜索	匹配完整短语，避免分词。	"exact phrase"	"user registration event"	用于带空格的描述或名称
排除条件	排除包含某关键词的结果。	-field:value	-tag:deprecated、-platform:hive	常用于过滤测试或废弃数据
时间范围	按更新或创建时间过滤（需启用时间索引）。	lastUpdated:[2024-01-01 TO 2024-12-31]	lastUpdated:[now-7d TO now]	支持 now 和相对时间
组合查询	多条件组合（AND 为默认逻辑）。	platform:snowflake owner:data-team tag:gold	dataset:orders -tag:staging platform:kafka	条件间空格表示 AND，可用括号分组
常用字段前缀	platform、owner、tag、glossaryTerm、dataset、field、description		glossaryTerm:customer_id	字段名不区分大小写，建议使用标准命名

5.3 数据集详情页解读

页面区域	内容说明	示例	注意事项
基本信息栏	展示 Dataset 名称、平台、URI、描述、创建时间等。	名称: analytics.users，平台: Snowflake，描述: “核心用户表”	名称可编辑，支持 Markdown 描述
Schema 信息	显示字段列表、类型、描述、是否为主键/PII 等。	字段: user_id (STRING)，描述: “用户唯一标识”，PII: 是	可展开查看嵌套结构（如 JSON、Avro）
所有者（Ownership）	列出数据负责人，支持添加/移除。	Owner: jane.doe@acme.com (Data Engineer)、marketing-team@acme.com	支持个人和团队，类型可为 Technical、Business 等
标签（Tags）	显示业务或技术标签，点击可搜索同类数据。	pii、gold、gdpr	可添加系统预设或自定义标签
术语表（Glossary）	关联的业务术语，提升语义理解。	字段 email → GlossaryTerm: “客户电子邮箱”	术语可链接到企业级数据字典
统计信息	显示行数、大小、分区数、最近更新时间等。	行数: 1.2M，大小: 2.4 GB，分区: dt=2024-10-01	数据来自源系统或摄取器上报
使用情况（Usage）	展示最近访问用户、查询频率、热门字段等。	最近访问: jdoe，查询次数: 45 (7天内)，热门字段: status、created_at	用于识别核心数据资产
血缘图谱	可视化上下游依赖关系（见 5.4 节）。	图形化展示上游源表和下游报表	支持展开/折叠、定位特定节点
数据质量	显示数据质量检查结果（如非空率、唯一性）。	user_id: 唯一性 99.8%，email: 非空率 95%	需集成 Great Expectations 或 Soda 等工具
活动日志	记录元数据变更历史（如描述修改、所有权变更）。	“jdoe updated description at 2024-10-01 10:30”	审计追踪依据

5.4 血缘与依赖关系查看

功能	说明	使用方式	示例	注意事项
血缘图可视化	图形化展示 Dataset 的上下游依赖。	在详情页点击”Lineage”标签页	查看 dwh_orders 的上游为 ods_orders，下游为 report_sales	支持缩放、拖拽、高亮路径
上游依赖	查看当前 Dataset 的数据来源。	点击”Upstream”切换视图	发现 analytics.users 来自 kafka://user_events 和 mysql://users	用于影响分析（Impact Analysis）
下游依赖	查看当前 Dataset 被哪些作业或报表使用。	点击”Downstream”切换视图	发现 sales_summary 被 Looker 仪表板和 Airflow 任务使用	用于变更影响评估
路径高亮	点击某节点高亮其与当前节点的连接路径。	鼠标悬停或点击某个上游表	高亮从 raw_events 到 agg_daily 的完整链路	帮助理解复杂依赖
血缘层级控制	控制显示的血缘深度（如仅直接依赖、或展开多层）。	使用”Expand”按钮或滑动条	展开到 3 层以查看原始日志来源	深度越大性能越慢
血缘来源标识	显示血缘是自动采集还是手动添加。	图标显示 “Auto” 或 “Manual”	区分可信度，自动血缘更准确
导出血缘图	将血缘关系导出为 JSON 或图片。	点击”Export”按钮，选择格式	导出用于文档或汇报	支持 PNG、SVG、JSON 格式
影响分析（Impact Analysis）	模拟某 Dataset 变更对下游的影响。	选择”Analyze Impact”功能	评估删除 staging_users 对下游报表的影响	需完整血缘数据支持

第六章：数据血缘（Lineage）

6.1 血缘数据模型介绍

概念	说明	示例	注意事项
Upstream	当前 Dataset 的数据来源实体。	Dataset A ← Dataset B，则 B 是 A 的上游	可有多个上游
Downstream	使用当前 Dataset 作为输入的实体。	Dataset A → Dataset C，则 C 是 A 的下游	常见于 ETL 任务、报表、模型
Lineage Aspect	存储血缘关系的元数据字段，类型为 upstreamLineage。	upstreamLineage: { "upstreams": [ { "dataset": "urn:...", "type": "TRANSFORMED" } ] }	通过 MCP 更新
Lineage Type	血缘关系类型，描述数据转换性质。	DERIVED、COPY、TRANSFORMED、LOOKUP	TRANSFORMED 表示经过加工，COPY 表示直接复制
Facet	血缘的附加信息，如字段级映射、转换 SQL 片段。	transformSql: "SELECT user_id, UPPER(name)..."	用于精细血缘分析
Field-level Lineage	记录字段级别的映射关系（如 src.name → dst.full_name）。	在 upstreamLineage 中通过 fieldsUpdated 字段定义	需解析 SQL 或执行计划，采集难度高
Run ID	血缘采集任务的唯一标识，用于去重和追踪。	systemMetadata.runId: "ingest-airflow-20241001"	建议每次摄取使用唯一 ID
实体类型支持	支持 Dataset、DataJob（如 Airflow Task）、Dashboard 之间的血缘。	Airflow Task → Dataset, Dashboard → Dataset	构成完整数据链路

6.2 上游/下游依赖分析

分析类型	说明	使用方法	应用场景	注意事项
直接依赖分析	仅查看一级上下游。	在血缘图中关闭”Expand”	快速了解 immediate 来源或使用者	最常用，性能好
深度依赖分析	查看多层级依赖（如源系统 → ODS → DWD → DWS → 报表）。	展开血缘图至 3 层以上	数据治理、架构优化	可能出现环路或性能瓶颈
跨平台依赖	分析不同系统间的数据流动（如 Kafka → Spark → Snowflake → Looker）。	使用平台过滤器或全局图谱	理解端到端数据流	需确保所有系统元数据已接入
关键路径识别	找出核心数据资产及其影响范围。	按”下游数量”排序，识别 hub 节点	优先保障高影响数据的 SLA	gold 级数据通常下游较多
断点检测	发现无上游或无下游的孤立节点。	搜索 upstream:0 或 downstream:0	清理废弃数据、发现未注册的中间表	需结合业务判断是否合理
影响范围评估	评估某 Dataset 删除或变更的影响。	选中节点，查看下游列表及数量	变更管理、版本升级	建议结合数据质量、使用频率综合判断
溯源分析（Traceability）	从最终报表反向追踪到原始数据。	从 Dashboard 出发，逆向查看上游 Dataset	审计、问题排查	需完整血缘链路

6.3 手动添加血缘关系

方法	语法/操作步骤	用途	示例	注意事项
DataHub UI 手动添加	进入 Dataset 详情页 → Lineage → “Add Upstream” / “Add Downstream”	快速修复缺失血缘或添加临时依赖	添加 kafka://user_events 为 dwh_users 的上游	仅支持 Dataset 级，不支持字段级
Python SDK	graph.emit_mcp(upstream_mcp)	在脚本中程序化添加血缘	构造 upstreamLineage MCP 并发送	需构造正确 URN 和关系类型
CLI 命令	datahub add-lineage-upstream --entityUrn <urn> --upstreamUrn <urn>	批量或自动化添加血缘	datahub add-lineage-upstream -e "urn:..." -u "urn:..."	支持从文件批量导入
MCP JSON 消息	发送 MetadataChangeProposal 到 Kafka	与现有系统集成，实时上报血缘	{ "entityUrn": "...", "aspectName": "upstreamLineage", "changeType": "UPSERT", "aspect": { "upstreams": [...] } }	需确保 Kafka 连通性
字段级血缘	在 MCP 中指定 fieldsUpdated 映射	精确描述字段转换逻辑	"fieldsUpdated": [ { "source": "src.name", "destination": "dst.full_name" } ]	需解析 SQL 或手动维护，成本较高
删除血缘	changeType: DELETE 或 UI 中删除链接	修正错误血缘	删除已下线系统的依赖关系	删除操作不可逆，需确认

6.4 自动血缘采集（通过摄取器）

摄取器类型	支持的血缘来源	配置方式	示例	注意事项
Airflow 摄取器	从 DAG 的 inlets/outlets 或 Task 装饰器中提取。	在 recipe 中设置 source.type: airflow	@task(outlets=[Dataset("snowflake://...")])	需启用 OpenLineage 或使用 DataHub Operator
DBT 摄取器	解析 manifest.json 中的模型依赖关系。	source.type: dbt，配置 manifest_path 和 catalog_path	自动识别 ref('orders') 生成血缘	支持字段级血缘，推荐使用
Spark 摄取器	通过 Spark Listener 捕获 DataFrame 读写操作。	启动 Spark 时添加 datahub-spark-listener 包	读取 s3a://bucket/input，写入 hive://db.table	需部署 Listener 到集群
Snowflake View	解析 View 的 SELECT 语句获取上游表。	source.type: snowflake，启用 include_views: true	CREATE VIEW v_users AS SELECT * FROM raw_users → 血缘自动建立	需有查询权限
Kafka 摄取器	通过 Schema Registry 或生产者元数据推断来源。	source.type: kafka，配置 schema_registry_url	从 Avro schema 推断上游服务	精度有限，建议结合业务标注
BigQuery Audit Logs	解析查询日志中的 jobCompleted 事件。	source.type: bigquery，配置 project_id 和日志表	分析 SELECT a.id FROM A a JOIN B b 建立表 A、B 到结果表的血缘	需启用审计日志，延迟约 15 分钟
OpenLineage	标准化血缘采集框架，支持 Spark、Airflow、DBT 等。	配置 OL Client 上报到 DataHub Gateway	统一血缘格式，跨平台兼容	推荐作为自动血缘的标准化方案
定时采集	摄取器定期轮询源系统获取血缘。	在 recipe 中设置 interval: "PT1H"	每小时同步一次 Airflow DAG 血缘	避免过于频繁，防止源系统压力

第七章：数据治理与策略配置

7.1 敏感数据标记（PII）

功能	说明	使用方式	示例	注意事项
PII 自动识别	基于字段名、正则表达式、数据采样自动检测敏感信息。	启用 PII 扫描器（如 DataHub PII Scanner），配置规则库	检测到字段 ssn、credit_card_number 被标记为 PII.SSN、PII.CREDIT_CARD	需定期更新识别规则，避免误报/漏报
手动标记 PII	用户手动为字段或 Dataset 添加 PII 标签。	在 Dataset 详情页 Schema 中点击字段 → “Add Tag” → 选择 PII.* 类型	为 email 字段添加 PII.EMAIL 标签	适用于自动识别未覆盖的场景
PII 分级	根据敏感程度分级（如 PUBLIC、INTERNAL、CONFIDENTIAL、RESTRICTED）。	在策略中配置 PII 分类等级，或通过标签继承	PII.SSN → RESTRICTED，PII.ZIP_CODE → INTERNAL	分级用于访问控制和审计
加密/脱敏提示	在 UI 中对 PII 字段进行视觉提示（如锁图标、模糊显示）。	系统自动对 PII 字段添加遮罩或图标	查看数据预览时，phone 字段显示为 ***-****-1234	实际数据不修改，仅前端展示控制
PII 报告	生成组织内 PII 数据分布报告。	使用”PII Dashboard”或 API 导出清单	报告：120 张表含 PII，其中 45 张未设置所有者	用于 GDPR、CCPA 合规审计
扫描策略配置	定义 PII 扫描频率、范围、触发条件。	在 Admin 设置中配置扫描任务（如每日全量/增量扫描）	增量扫描：仅扫描过去 24 小时更新的 Dataset	扫描可能影响源系统性能，建议在低峰期运行
权限联动	PII 数据访问需额外审批或角色授权。	与治理策略（7.3节）结合，限制非授权用户访问	只有 data_privacy_team 可查看 PII.SSN 字段	需与 IAM 系统集成

7.2 自定义标签与分类（Tags & Glossary Terms）

功能	说明	使用方式	示例	注意事项
创建自定义标签	定义技术或业务标签用于分类数据。	Admin → Tags → “Create Tag”	etl、real-time、deprecated、gold、bronze	标签名应简洁、标准化，避免随意创建
标签继承	支持标签从父级（如 Schema 字段）继承到 Dataset。	自动或手动批量应用	为 user_profile 所有字段添加 PII 标签后，Dataset 自动标记	可配置是否启用自动继承
术语表（Glossary）创建	定义企业级业务术语，建立语义统一。	Admin → Glossary → “Create Term”	Term: Customer Lifetime Value (CLV)，Definition: “客户生命周期价值…”	建议由数据治理委员会维护
术语关联数据	将 Dataset 或字段关联到业务术语。	在详情页点击字段 → “Add Glossary Term” → 选择已有术语	revenue 字段 → Revenue (GAAP)	支持多对多关联
层级术语表	支持术语分类树（如 Finance → Revenue → Subscription Revenue）。	创建术语时指定父节点	构建可导航的业务词汇体系	便于按业务域浏览数据
批量管理	通过 UI 或 API 批量添加/移除标签或术语。	选择多个 Dataset → “Bulk Edit” → 添加标签/术语	为所有 kafka 主题批量添加 streaming 标签	提升治理效率
搜索与发现	通过标签或术语搜索相关数据。	搜索框输入 tag:gold 或 glossaryTerm:CLV	查找所有 gold 级数据集	是数据发现的核心手段
审核与过期	定期审核标签和术语的有效性。	设置术语过期提醒或审计日志	术语 Old_Customer_Score 标记为”已弃用”	避免术语表膨胀

7.3 治理策略配置（Policies）

策略类型	说明	配置方式	示例	注意事项
访问控制策略	控制用户或组对数据的读、写、编辑权限。	Admin → Policies → Create → 选择资源类型（Dataset）、条件、权限	允许 analysts 组读取 tag:public 的 Dataset	优先使用基于角色的访问控制（RBAC）
PII 访问策略	特殊限制敏感数据的访问。	创建策略：资源 = tag:PII.*, 权限 = View PII, 主体 = 特定团队	仅 security-team 可查看 PII.PASSPORT	可结合动态脱敏（Dynamic Masking）
编辑权限策略	限制元数据修改权限（如描述、标签、所有者）。	策略条件：ownership.type = Technical, 权限：Edit Ownership	仅数据所有者可修改 Dataset 描述	防止元数据污染
搜索可见性策略	控制数据在搜索结果中的可见性。	策略：dataset.tag = internal → 仅对 internal-users 可见	隐藏测试数据或未发布模型	配合数据生命周期管理使用
血缘可见性策略	控制血缘图的查看权限。	策略：资源类型 = Lineage, 条件 = upstream.tag = restricted	防止低权限用户通过血缘发现敏感上游	高级安全需求
策略优先级	多策略冲突时按优先级生效。	系统按顺序评估，高优先级策略覆盖低优先级	Deny 策略通常优先于 Allow	建议明确策略优先级规则
策略审计	查看策略应用日志和效果。	在 Policy 详情页查看”Audit Log”	调试权限问题	所有变更应可追溯
系统策略 vs 用户策略	系统预设策略（不可删）与用户自定义策略。	系统策略通常为默认行为（如管理员全权）	用户策略用于业务定制	修改系统策略需谨慎

7.4 数据所有者（Ownership）管理

功能	说明	使用方式	示例	注意事项
添加所有者	为 Dataset 指定负责人。	详情页 → Ownership → “Add Owner” → 输入用户/组	添加 jane.doe@acme.com 为 dwh_users 的 Technical Owner	建议每 Dataset 至少有一个所有者
所有者类型	区分技术所有者（Technical）和业务所有者（Business）。	添加时选择类型	data-engineer-team (Technical)、marketing-lead (Business)	便于问题定位和责任划分
批量设置所有者	为多个 Dataset 统一设置所有者。	搜索后选择多个 Dataset → “Bulk Edit” → “Add Ownership”	为所有 platform:kafka 的主题添加 streaming-team	治理初期快速补全
自动所有者分配	基于命名规则或正则表达式自动分配。	配置 Ownership Ingestion Rule（如 dataset.name ~ /^analytics..*/ → team-analytics）	analytics.* → analytics-team@acme.com	需定期维护规则
所有者通知	所有者收到变更、问题报告等通知。	系统自动发送邮件或站内信	Dataset 被频繁访问或血缘变更时通知所有者	确保邮箱正确
所有者审批	某些操作需所有者审批（如访问请求）。	集成审批流系统，触发审批任务	用户申请查看 PII 数据 → 所有者审批	提升数据安全
移除/移交所有者	变更负责人或团队。	在 Ownership 列表中移除或替换	员工离职时移交所有权	避免出现”无主数据”
所有权审计	审查组织内所有权覆盖率。	生成报告：无所有者 Dataset 数量、平均每个所有者管理的数据集数	发现 50 张表无所有者，需治理	是数据治理关键指标

第八章：前端界面操作指南

8.1 登录与用户界面概览

功能	说明	使用方式	示例	注意事项
登录方式	支持 SSO（SAML/OAuth）、LDAP、本地账号登录。	访问 DataHub URL → 输入凭证或点击 SSO 按钮	通过 Google SSO 登录	SSO 推荐用于企业部署
首页概览	展示推荐数据集、最近访问、热门搜索、通知等。	登录后自动进入首页	首页显示”您最近查看的 5 个 Dataset”	可自定义首页布局
个性化仪表板	用户可定制关注的数据和指标。	点击”Dashboard” → “Create Personal Dashboard”	添加”我的收藏”、“PII 数据监控”小组件	提升使用效率
多租户支持	支持多个组织或项目空间（若启用）。	登录后选择工作区（Workspace）	acme-prod、acme-dev	权限隔离
响应式设计	支持桌面与移动设备访问。	浏览器访问，自动适配	在 iPad 上查看血缘图	部分复杂操作建议使用桌面端
语言与主题	支持多语言和深色/浅色主题切换。	用户设置中选择语言和主题	切换为中文界面或深色模式	提升用户体验
首次登录引导	新用户引导教程。	首次登录自动弹出引导流程	介绍搜索、查看 Dataset 等基本操作	可跳过
会话管理	查看和管理登录会话。	个人设置 → “Active Sessions”	注销其他设备上的会话	安全最佳实践

8.2 导航栏与功能模块说明

导航项	功能说明	子菜单/入口	快捷键	注意事项
首页（Home）	个性化信息流，快速入口。	推荐、最近、热门、通知	H	点击 Logo 可返回
发现（Discover）	数据搜索与浏览核心模块。	搜索框、高级搜索、筛选面板	/（聚焦搜索）	支持保存搜索视图
数据集（Datasets）	列出所有注册的 Dataset。	可按平台、标签、所有者筛选	D	可切换列表/卡片视图
仪表板（Dashboards）	集中管理 BI 仪表板元数据。	关联 Looker、Tableau、Superset 等	B	显示使用频率和所有者
数据管道（Data Pipelines）	展示 ETL/流处理任务（如 Airflow DAG）。	显示运行状态、血缘、负责人	P	需集成调度系统
术语表（Glossary）	浏览企业级业务术语。	树形结构展示术语分类	G	可搜索术语并查看关联数据
血缘图（Lineage Graph）	全局可视化数据流动。	展示跨平台端到端血缘	L	支持搜索节点、高亮路径
管理（Admin）	系统配置与治理（需权限）。	用户、策略、标签、术语表、摄取器配置等	A	仅管理员可见
收藏（Favorites）	查看用户收藏的数据。	星标按钮添加/移除	F	快速访问高频数据
通知（Notifications）	查看系统消息、审批请求、提及等。	小铃铛图标	N	可标记已读或清除

8.3 数据集、仪表板、管道的浏览与编辑

操作类型	数据集（Dataset）	仪表板（Dashboard）	数据管道（Pipeline）	注意事项
浏览	查看 Schema、描述、标签、血缘、使用情况	查看图表、查询、数据源、所有者、访问频率	查看任务列表、调度周期、运行日志、上下游	支持分页和过滤
搜索与筛选	在 Discover 页按字段、平台、标签搜索	按 BI 工具类型（Looker/Superset）、所有者筛选	按调度器（Airflow）、状态（运行中/失败）筛选	可保存筛选视图为视图
查看详情	点击名称进入详情页	点击进入详情页，查看关联的 Dataset 和图表	查看 DAG 图、任务详情、执行历史	详情页是核心操作界面
编辑元数据	修改描述、添加标签/术语、更新所有者	更新描述、负责人、关联数据集	更新描述、负责人、调度说明	需有编辑权限，变更记录在活动日志
添加收藏	点击星标按钮	点击星标按钮	点击星标按钮	用于快速访问
分享链接	点击”Share”生成可访问链接（可带权限提示）	同上	同上	链接可发给同事
导出信息	导出 Schema、血缘图（PNG/SVG）、元数据（JSON）	导出为 PDF 或 PNG	导出 DAG 图或元数据	支持多种格式
发起协作	在评论区 @ 用户或发送通知	同上	同上	促进团队沟通

8.4 个人资料与通知设置

设置项	说明	配置方式	示例	注意事项
个人资料编辑	更新姓名、头像、职位、部门等。	点击右上角头像 → “Profile” → “Edit”	上传头像，填写”Data Analyst, Marketing”	信息用于所有者展示和协作
联系方式	设置邮箱、电话（用于通知和审批）。	在 Profile 中添加	jdoe@acme.com、+1-555-1234	确保邮箱准确
通知偏好	选择接收通知的方式和类型。	Settings → Notifications → 勾选事件类型	开启”评论提及”、“审批请求”、“数据变更”	可选择邮件、站内信或关闭
主题与语言	切换界面主题（亮/暗）和显示语言。	Settings → Appearance → 选择主题和语言	切换为”Dark Mode”和”中文”	立即生效
时区设置	设置显示时间的时区。	Settings → General → Timezone	Asia/Shanghai	影响时间戳显示
安全设置	更改密码、管理 SSO、会话管理。	Settings → Security	修改本地密码，注销其他会话	SSO 用户可能无法修改密码
数据偏好	设置默认搜索范围、结果数量等。	Settings → Preferences	默认显示 50 条搜索结果	个性化体验
隐私设置	控制个人活动是否公开（如”最近查看”）。	Settings → Privacy	隐藏”最近活动”对他人可见	保护用户隐私

第九章：API 与 SDK 使用

9.1 GraphQL API 基础

功能	说明	使用方式	示例	注意事项
GraphQL 端点	提供 /api/graphql 接口用于查询和变更元数据。	发送 POST 请求至 https://your-datahub/api/graphql，携带 GraphQL 查询	查询所有标签：{ listTags { tags { name } } }	需认证（Bearer Token 或 Cookie）
查询（Query）	用于读取元数据（如 Dataset、用户、标签等）。	使用 query { ... } 结构	query { getDataset(urn: "...") { name description } }	支持分页、过滤、字段选择
变更（Mutation）	用于修改元数据（如更新描述、添加标签）。	使用 mutation { ... } 结构	mutation { updateDescription(input: { entityUrn: "...", value: "..." }) }	需权限，变更记录日志
Schema 浏览	查看可用类型、字段和参数。	访问 GraphQL Playground 或使用 __schema 查询	query { __schema { types { name fields { name } } } }	工具如 GraphiQL、Altair 可提升开发效率
批量查询	一次请求获取多个资源。	在查询中组合多个字段或使用循环	query { getDataset(...), getUser(...), listTags(...) }	减少网络开销
参数化查询	使用变量传递参数，提升复用性。	定义变量 $urn: String! 并在查询中使用	query GetDataset($urn: String!) { getDataset(urn: $urn) { ... } }	推荐用于客户端开发
响应格式	返回 JSON 格式，包含 data、errors 字段。	解析响应中的 data 获取结果，errors 判断失败	{ "data": { "getDataset": { "name": "users" } }, "errors": null }	始终检查 errors 字段
Playground	内置交互式 API 调试工具。	访问 https://your-datahub/api/graphiql	在浏览器中测试查询和认证	生产环境建议关闭或限制访问

9.2 查询元数据（Querying Entities）

操作	说明	GraphQL 查询示例	返回字段示例	注意事项
查询 Dataset	获取 Dataset 的基本信息和元数据切片（Aspects）。	query { getDataset(urn: "urn:li:dataset:...") { name platform description } }	name, platform, description, created, lastModified	URN 需精确匹配
查询 Schema	获取 Dataset 的字段结构。	query { getDataset(urn: "...") { schema { fields { fieldPath type description } } } }	fieldPath, type, nullable, description	支持嵌套字段（如 user.address.city）
搜索 Dataset	全文搜索或按条件筛选 Dataset。	query { search(input: { type: DATASET, query: "user", from: 0, size: 10 }) { entities { urn } } }	urn, name, score, metadata（摘要）	支持 query, filters（标签、平台等）
查询标签	获取所有或特定标签。	query { listTags { total tags { name } } }	name, description, created	可用于构建标签选择器
查询术语表	获取业务术语及其关联。	query { getGlossaryTerm(urn: "urn:li:glossaryTerm:CLV") { name definition relatedTerms } }	name, definition, relatedTerms, relatedEntities	支持层级遍历
查询血缘	获取 Dataset 的上下游依赖。	query { getUpstream(urn: "...") { upstreams { dataset { name } } } }	upstreams, downstreams, fields, confidence	支持跨平台血缘
查询用户/组	获取用户信息及所属组。	query { getCorpUser(urn: "urn:li:corpuser:jdoe") { info { displayName email } } }	displayName, email, groups, roles	用于权限校验或通知
批量获取	一次查询多个实体。	query { getDataset(...), getDashboard(...), getDataJob(...) }	多个实体的响应合并返回	注意请求大小限制

9.3 更新元数据（Update Aspects）

操作	说明	Mutation 示例	参数说明	注意事项
更新描述	修改 Dataset、Dashboard 等的描述信息。	mutation { updateDescription(input: { entityUrn: "...", value: "新描述" }) }	entityUrn: 资源 URN, value: 描述文本	支持 Markdown 格式
添加/移除标签	为实体添加或删除标签。	mutation { addTags(input: { urn: "...", tags: ["tag:li:tag:PII"] }) }	tags: 标签 URN 数组	移除使用 removeTags
关联术语表	将字段或 Dataset 与业务术语关联。	mutation { addGlossaryTerms(input: { urn: "...", terms: ["urn:li:glossaryTerm:Revenue"] }) }	terms: 术语 URN 数组	支持多术语关联
更新所有者	添加或替换数据所有者。	mutation { addOwner(input: { ownerUrn: "urn:li:corpuser:jdoe", type: TECHNICAL }) }	ownerUrn: 用户/组 URN, type: 所有者类型	需有编辑权限
更新自定义属性	修改 Dataset 的自定义字段（Custom Properties）。	mutation { updateCustomProperties(input: { urn: "...", customProperties: { key: "value" } }) }	customProperties: 键值对对象	用于存储非标准元数据
更新血缘	手动注入或修正血缘关系（高级）。	mutation { updateLineage(input: { entityUrn: "...", upstreams: [ { datasetUrn: "...", auditStamp: { ... } } ] }) }	upstreams: 上游列表，auditStamp: 操作人时间戳	通常由摄取器自动填充，手动用于修复
批量更新	通过脚本批量修改多个实体。	循环调用 Mutation 或使用批处理 API（若支持）	脚本遍历 Dataset 列表并更新描述	注意速率限制和事务一致性
创建新实体	通过 API 注册新 Dataset（需平台支持）。	mutation { ingestProposal(...) }（依赖具体实现）	提供完整元数据切片	通常通过摄取器完成，API 用于特殊场景

9.4 Python SDK 客户端使用

功能	说明	使用方式（代码示例）	所需依赖	注意事项
安装 SDK	安装官方 Python 客户端库。	pip install datahub-api-client	requests, pydantic	检查版本兼容性
初始化客户端	创建 DataHub 客户端实例。	from datahub.client import DataHubClient client = DataHubClient(host="https://your-datahub", token="your-token")	host: DataHub 地址, token: 访问令牌	Token 可在用户设置中生成
查询 Dataset	获取 Dataset 信息。	dataset = client.get_dataset("urn:li:dataset:...") print(dataset.name)	get_dataset() 返回对象	捕获 ApiError 异常
搜索数据	执行搜索操作。	results = client.search("user", entity_type="DATASET") for item in results: print(item.urn)	search(query, entity_type, start, count)	支持分页
更新描述	修改元数据描述。	client.update_description(entity_urn="...", description="新描述")	调用 update_description 方法	需权限
添加标签	为实体打标签。	client.add_tags(entity_urn="...", tags=["PII"])	tags 为标签名列表	标签需已存在
添加术语表	关联业务术语。	client.add_glossary_terms(entity_urn="...", terms=["Revenue"])	terms 为术语名列表	术语需已注册
批量操作	遍历多个 Dataset 执行操作。	for urn in urn_list: client.update_description(urn, "auto-updated")	结合搜索 API 获取列表	添加延迟避免限流
自定义脚本	构建自动化治理任务（如同步所有者）。	脚本：读取 CSV → 匹配 Dataset → 调用 add_owner()	pandas, csv	用于数据治理自动化

9.5 错误处理与认证机制

机制	说明	配置方式与示例	常见错误码	注意事项
Bearer Token 认证	使用长生命周期令牌进行 API 调用。	请求头：Authorization: Bearer <token>	401 Unauthorized（无效 Token）	Token 在用户设置中生成，需保密
OAuth 2.0 / SSO	与企业身份提供商集成。	配置 SAML/OAuth 2.0，获取 Access Token	403 Forbidden（权限不足）	适用于自动化服务账号
API Key	某些部署支持 API Key 认证。	请求头：X-API-Key: your-api-key	429 Too Many Requests（速率超限）	建议用于内部脚本
错误响应结构	统一返回错误信息。	{ "errors": [ { "message": "Dataset not found", "code": "NOT_FOUND" } ] }	NOT_FOUND, INVALID_REQUEST, INTERNAL_ERROR	始终检查 errors 字段
重试机制	处理临时性失败（如网络抖动）。	指数退避重试（Exponential Backoff）	503 Service Unavailable	SDK 通常内置重试逻辑
速率限制	防止 API 滥用。	默认限制（如 100 次/分钟），超限返回 429	X-RateLimit-Limit, X-RateLimit-Remaining 响应头	生产环境需监控调用频率
审计日志	记录所有 API 调用。	在 Admin → Audit Logs 中查看	包含用户、IP、操作、时间戳	用于安全审计和问题排查
超时设置	避免请求长时间挂起。	客户端设置连接和读取超时（如 30s）	ConnectionTimeout, ReadTimeout	建议设置合理超时

第十章：监控与运维

10.1 日志查看与问题排查

问题类型	排查方法	日志位置与命令	关键日志信息	解决方案
摄取失败	检查摄取器是否成功推送元数据。	docker logs datahub-ingestion 或 Kubernetes logs	Failed to ingest, Connection refused, Invalid schema	检查源配置、网络、认证、Schema 兼容性
搜索无结果	元数据未索引或 Elasticsearch 问题。	docker logs datahub-elasticsearch	indexing error, shard failure	重启 ES，检查索引状态，重新运行摄取
登录失败	SSO 配置错误或用户不存在。	docker logs datahub-frontend	SAML auth failed, User not found	检查 SSO 配置、用户同步、LDAP 连接
血缘缺失	血缘未采集或解析失败。	docker logs datahub-datahub-gms	Failed to parse lineage, upstream not found	检查血缘摄取器（如 Airflow Lineage Plugin）配置
性能缓慢	前端加载慢或 API 响应延迟。	docker stats、prometheus 监控、前端 Network 面板	高 CPU/内存，慢查询日志	优化查询、增加资源、检查索引
API 返回 500	服务内部错误。	docker logs datahub-gms（后端服务）	NullPointerException, Database connection error	重启服务，检查数据库连接，查看堆栈跟踪
数据不一致	UI 显示与实际元数据不符。	比对数据库（MySQL/Metadata Store）与 UI	stale cache, index-doc mismatch	清除缓存，重新索引
通知未送达	邮件或站内信未发送。	docker logs datahub-mail（若有独立服务）	SMTP auth failed, Email send error	检查邮件服务器配置

10.2 性能调优建议

调优方向	建议措施	配置示例或命令	适用场景	注意事项
增加资源	提升容器或虚拟机的 CPU 和内存。	docker-compose.override.yml 中增加 mem_limit: 8g	高并发、大数据量	避免资源争用
Elasticsearch 优化	调整分片、副本、刷新间隔。	index.refresh_interval: 30s，增加分片数	搜索缓慢、索引延迟	避免过多分片影响性能
启用缓存	使用 Redis 缓存高频访问数据。	确保 datahub-redis 正常运行，配置 TTL	减少 GMS 数据库查询压力	监控缓存命中率
摄取批处理	合并小批量摄取任务，减少频率。	recipe.yaml 中设置 max_batch_size: 1000	摄取任务频繁导致系统负载高	平衡实时性与性能
查询优化	避免全表扫描，使用过滤条件。	搜索时添加 platform:kafka、tag:PII 等过滤器	前端卡顿、API 超时	教育用户使用高级搜索
数据库调优	优化 MySQL/PostgreSQL 配置（如连接池、索引）。	增加 max_connections，为常用查询字段建索引	GMS 响应慢	定期维护数据库
前端懒加载	大血缘图或长列表分页加载。	系统默认支持，无需配置	血缘图加载卡死	用户体验优化
监控告警	配置 Prometheus + Grafana 监控关键指标。	监控 JVM 内存、ES 健康度、API 延迟	预防性运维	设置阈值告警

10.3 升级 DataHub 版本

步骤	说明	操作命令或方式	注意事项
1. 备份数据	升级前必须备份所有组件数据。	备份 MySQL、Elasticsearch、Neo4j 数据卷或使用 mysqldump、elasticdump	确保备份完整且可恢复
2. 查看发布说明	阅读新版本 Breaking Changes 和迁移步骤。	访问 GitHub Releases 页面	注意 API、配置、Schema 变更
3. 停止服务	停止所有 DataHub 容器。	docker-compose down	避免写入冲突
4. 更新镜像	拉取新版本镜像。	docker-compose pull 或修改 docker-compose.yml 中版本号	确保所有服务镜像版本一致
5. 更新配置	根据新版本要求调整 docker-compose.yml 或 Helm values.yaml。	添加新环境变量、端口、依赖	参考官方迁移指南
6. 启动服务	启动新版本容器。	docker-compose up -d	观察日志是否有启动错误
7. 验证功能	检查登录、搜索、血缘、API 是否正常。	手动测试核心功能，运行健康检查脚本	确保关键业务不受影响
8. 回滚计划	若升级失败，恢复备份并降级。	docker-compose down，恢复旧镜像和备份数据	回滚脚本应预先测试

10.4 备份与恢复策略

策略	说明	实现方式	频率	注意事项
全量备份	定期完整备份所有核心数据。	mysqldump -h db -u user -p datahub_db > backup.sql	每周一次	确保备份文件加密存储
		elasticdump --input=http://es --output=backup.json
增量备份	备份自上次以来的变更。	使用数据库 binlog 或 Elasticsearch 快照增量功能	每日一次	需配合全量备份使用
自动化脚本	使用 cron 定时执行备份脚本。	0 2 * * 0 /backup/datahub_backup.sh	按计划	脚本需包含错误检测和通知
备份验证	定期测试备份可恢复性。	在测试环境导入备份，验证数据完整性	每季度一次	避免”备份失效”风险
多地存储	将备份复制到不同地理位置。	使用 rsync、rclone 同步到云存储（S3、GCS）	每次备份后	防止单点故障
恢复流程	明确灾难恢复步骤。	文档化恢复流程：停止服务 → 恢复数据库 → 恢复索引 → 启动服务	应急时使用	所有运维人员需熟悉流程
版本兼容性	确保备份可被目标版本恢复。	测试备份在新旧版本间的兼容性	升级前后	避免因版本不兼容无法恢复
加密与安全	保护备份数据安全。	使用 gpg 或云 KMS 加密备份文件	始终启用	防止敏感数据泄露

第十一章：高级主题与扩展

11.1 自定义 Aspect 开发

功能	说明	实现方式	示例场景	注意事项
定义新 Aspect	扩展元数据模型，添加业务专属字段（如”数据敏感等级”、“合规负责人”）。	使用 PDL (Python Data Language) 定义 Schema，生成 Java/Python 类	创建 DataCompliance Aspect，包含 sensitivityLevel、dpoContact 字段	遵循命名规范（如 com.company.aspect.DataCompliance）
注册到 Metadata Model	将新 Aspect 注册到 DataHub 元数据模型中。	将生成的类打包并部署到 datahub-gms 服务	更新 entity-registry.yml 或通过 API 注册	需重启 GMS 服务生效
摄取自定义数据	通过摄取器将自定义 Aspect 写入 DataHub。	在摄取器配置中使用 MetadataChangeProposal 写入新 Aspect	在 kafka-source.yml 中添加 aspectName: DataCompliance 和值	确保字段类型匹配
查询与展示	在 UI 和 API 中查询和显示自定义字段。	GraphQL 查询新增字段；前端插件扩展实体详情页	query { getDataset(...) { aspects { dataCompliance { sensitivityLevel } } } }	前端需开发自定义 Renderer 插件
版本控制	管理 Aspect 的 Schema 演进（如添加字段）。	使用 PDL 的兼容性规则（不删除字段，可选新增）	从 v1 到 v2 添加 retentionPeriod 字段	避免破坏性变更
数据验证	在写入时校验自定义字段合法性。	在摄取器或 GMS 中添加校验逻辑	检查 sensitivityLevel 是否为 PUBLIC、INTERNAL、CONFIDENTIAL	可结合 JSON Schema
权限控制	控制谁可以读写自定义 Aspect。	在 Policy 中配置基于 Aspect 的权限	仅合规团队可编辑 DataCompliance 字段	与 11.4 多租户结合使用
工具支持	IDE 插件支持 PDL 编辑与校验。	使用 VS Code PDL 插件	语法高亮、错误提示	提升开发效率

11.2 插件化摄取器开发

类型	说明	开发方式	示例插件	注意事项
Source 插件	从外部系统（数据库、数据仓库）提取元数据。	继承 Source 基类，实现 get_workunits() 方法	SnowflakeSource、BigQuerySource	支持增量/全量模式
Transformer 插件	在摄取过程中转换元数据（如重命名、过滤、丰富）。	实现 Transformer 接口，处理 MetadataWorkUnit 流	AddDatasetOwnershipTransformer、FilterPatternTransformer	可链式组合
Sink 插件	将元数据写入目标系统（如 Kafka、文件、外部 API）。	实现 Sink 接口，处理摄取流水线输出	KafkaSink、FileSink	用于审计或同步到其他系统
自定义 Source	为私有系统开发摄取器。	使用 datahub-cli 模板创建插件，实现连接、查询、生成 MCE/MCP	从内部 CRM 系统摄取表元数据	处理认证、分页、错误重试
配置驱动	通过 YAML 配置启用和参数化插件。	在 recipe.yml 中声明 source.type: my-crm-source	统一配置管理	支持环境变量注入
错误处理	插件内捕获异常并记录。	使用 Report 对象记录成功/失败统计	report.report_failure(...)	避免因单条数据失败中断整个任务
性能优化	批量查询、并行处理、缓存连接。	使用连接池、异步 I/O、批量 API 调用	从 1000 张表中并行获取 Schema	降低源系统负载
发布与共享	将插件发布为 PyPI 包供团队使用。	python setup.py sdist、pip install my-datahub-source	企业内部私有仓库	遵循版本语义化

11.3 与外部系统集成（如 Slack、Jira）

集成目标	集成方式	使用场景	配置与示例	注意事项
Slack	通过 Webhook 或 Bot 发送通知。	所有者审批请求、数据异常告警、血缘变更提醒	配置 SLACK_WEBHOOK_URL，触发 onOwnershipChange 事件	使用 Markdown 格式化消息
Jira	创建工单跟踪数据问题。	用户反馈”数据错误”时自动创建 Jira Ticket	调用 Jira REST API，填充项目、摘要、描述	映射 DataHub 用户到 Jira 账户
ServiceNow	数据资产与 IT 服务管理集成。	数据库变更触发 CMDB 更新	使用 SOAP/REST API 同步 Dataset 信息	确保字段映射准确
PagerDuty	严重数据中断告警。	ETL 流水线失败且血缘影响关键报表时触发告警	配置 Prometheus 告警规则 → Alertmanager → PagerDuty	避免告警风暴
Confluence	同步数据文档。	将 Dataset 描述自动发布到 Confluence 页面	使用 Confluence REST API 更新页面内容	支持双向同步（需额外逻辑）
CI/CD 管道	在部署时验证元数据。	在 CI 阶段运行摄取器，确保新表已注册并打标签	GitHub Actions 调用 datahub ingest	防止”影子数据”
企业微信 / 钉钉	国内常用通知渠道。	通过自定义机器人发送消息	配置 Webhook URL，发送 JSON 消息	遵守企业安全策略
自定义 Webhook	与任意 HTTP 服务集成。	数据更新时触发内部审批流	配置通用 Webhook 接收器，携带事件载荷	签名验证确保安全性

11.4 多租户与权限隔离

隔离维度	实现方式	配置方法	适用场景	注意事项
命名空间隔离	不同团队使用独立的 Dataset 命名空间（如 team_a.users）。	约定命名规范，配合 FilterPattern 摄取器过滤	多团队共享集群	非强制，依赖治理
实体标签隔离	用标签（Tag）标识租户，权限基于标签控制。	创建 tenant:finance、tenant:hr 标签，策略中限制访问	精细化访问控制	需自动化打标
所有者继承	子资源自动继承父资源所有者。	在摄取器中设置 auto_owner_inheritance: true	数据库 → Schema → Table 权限链	减少管理开销
自定义角色	定义租户管理员、数据编辑者、只读用户等角色。	在 Admin UI 创建角色，绑定权限（如 Edit Description、Add Tags）	角色复用，权限集中管理	遵循最小权限原则
策略引擎	基于属性（Attribute-Based）的动态权限控制。	创建策略：IF user.department == entity.tags.tenant THEN allow read	动态、可编程的权限模型	需要属性同步（如 LDAP）
摄取器级隔离	不同租户使用独立摄取器配置。	为 Finance 团队配置专用 snowflake-finance.yml 摄取器	安全合规要求	资源隔离
UI 视图定制	租户仅看到自己的数据。	前端默认添加 tag:tenant:current 过滤条件	提升用户体验	可绕过（需后端强制校验）
审计与报告	按租户生成合规报告。	查询 API 添加 filter: { tag: "tenant:finance" }	满足 GDPR、HIPAA 等要求	数据保留策略可按租户配置

第十二章：实战案例

12.1 构建企业级数据目录

阶段	关键任务	工具与方法	成功指标	挑战与对策
1. 规划与设计	定义数据域、术语表、分类标准。	与业务部门协作，建立数据治理委员会	完成《数据分类标准》文档	业务参与度低 → 高层推动
2. 摄取核心资产	连接主要数据源（数仓、湖、BI 工具）。	使用官方摄取器（Snowflake、BigQuery、Tableau）	覆盖 80% 以上关键 Dataset	源系统认证复杂 → 提供服务账号
3. 丰富元数据	自动填充描述、标签、所有者。	摄取器 auto-tagging、auto-ownership；NLP 生成描述	90% Dataset 有描述和标签	所有者缺失 → 基于 Git/HR 系统自动推断
4. 搜索与发现	优化搜索体验，支持高级过滤。	配置 Elasticsearch 同义词、权重；培训用户使用搜索语法	搜索使用率提升 50%	搜索不准 → 优化索引和分词器
5. 用户采纳	推广使用，收集反馈。	举办培训、设立”数据大使”、奖励活跃用户	月活用户 > 200	使用率低 → 与日常工作流集成（如 Jira 创建工单）
6. 持续治理	建立元数据质量规则和自动化修复。	定期扫描缺失描述、过期所有者，自动通知或打标	元数据完整率 > 95%	数据腐化 → 自动化治理流水线
7. 度量与改进	跟踪使用指标和业务价值。	监控搜索次数、血缘查看、数据共享次数	业务决策效率提升 30%	价值难量化 → 关联业务指标（如报表开发周期）

12.2 实现端到端数据血缘追踪

步骤	实现方式	技术栈	示例	注意事项
1. 源系统血缘	从数据库、ETL、BI 工具提取血缘。	数据库: 查询 INFORMATION_SCHEMA	dbt 自动生成字段级血缘	需要源系统支持元数据导出
		ETL: 解析 Airflow DAG、dbt manifest.json
		BI: Tableau Hyper Extract
2. 血缘标准化	将不同来源的血缘统一为 DataHub 血缘模型。	摄取器将源血缘映射为 UpstreamLineage Aspect	将 Airflow 的 Task A → Task B 映射为 Dataset 血缘	处理跨平台 URN 映射（如 Kafka Topic → Hive Table）
3. 血缘合并	合并多来源血缘（如 dbt + Airflow）。	DataHub 自动合并相同 upstreamUrn 的血缘	同一 Dataset 的血缘来自多个管道	避免重复边
4. 血缘可视化	在 UI 中展示血缘图。	前端使用 D3.js 渲染有向图，支持缩放、搜索、高亮	查看 sales_fact 表的上下游 3 层依赖	大图性能优化（懒加载、分层渲染）
5. 影响分析	变更前评估影响范围。	选择表 → “影响分析” → 显示下游报表、模型、用户	下线旧表前识别 10 个依赖报表	支持字段级影响分析
6. 血缘质量	监控血缘完整性和准确性。	摄取器报告血缘覆盖率；人工抽样验证	目标：关键流水线血缘覆盖率 > 90%	处理间接依赖（如代码中拼接 SQL）
7. 主动血缘	通过日志分析推断未知血缘。	分析查询日志（如 Presto），识别 SELECT a FROM b → b → a	发现未被 dbt 覆盖的 Ad-hoc 查询血缘	误报率较高，需置信度过滤
8. 与数据质量集成	血缘结合质量规则。	质量告警时，血缘图高亮问题源头	revenue 字段异常 → 追溯到 raw_transactions 表	闭环问题排查

12.3 自动化元数据治理流程

流程	自动化方案	工具与技术	触发条件	价值
所有者自动分配	基于数据使用模式或 HR 信息推断所有者。	脚本分析查询日志 + HR API → 调用 DataHub API 添加所有者	新表创建后 24 小时无所有者	解决”孤儿数据”问题
描述自动生成	使用 LLM（如 GPT）为表和字段生成描述。	摄取器后接 Transformer，调用 OpenAI API 基于 Schema 生成描述	摄取新 Dataset 时	提升元数据丰富度
敏感数据识别	自动扫描字段名、值，打上 PII/PCI 标签。	正则匹配（如 email）、NLP 模型、统计抽样	摄取时或每日扫描	满足合规要求
过期数据归档	标记长期未访问的数据。	查询使用日志，若 lastAccessed < now - 365d → 打 stale 标签	每月执行	降低存储成本，提升目录质量
质量规则检查	验证元数据完整性。	定时脚本检查：是否有描述？所有者？业务术语？	每日扫描	保障元数据质量
变更审批流	重要变更（如下线表）需审批。	UI 提交请求 → 创建 Jira Ticket → 审批通过后调用 API 执行	用户点击”请求下线”	防止误操作
通知与提醒	自动通知所有者或用户。	基于事件（如评论、@提及、权限变更）发送邮件/Slack	实时或每日汇总	提升协作效率
治理报告生成	自动生成合规报告。	脚本查询 API → 生成 PDF/HTML 报告 → 邮件发送	每月 1 日	满足审计要求

12.4 与数据质量工具集成

集成方式	说明	集成工具示例	实现方法	效果
质量结果展示	在 DataHub 实体页显示质量分数和规则状态。	Great Expectations、dbt、Monte Carlo	质量工具将结果写入 DataHub 自定义 Aspect（如 DataQuality）	一站式查看数据健康度
问题溯源	质量告警时，跳转到 DataHub 查看血缘和上下文。	Deequ、Soda Core	质量 Dashboard 嵌入 DataHub 实体链接	快速定位问题根源
质量元数据摄取	将质量规则和结果作为元数据管理。	自定义摄取器	解析 great_expectations/validations 目录 → 生成 DataQuality Aspect	质量规则版本化、可追溯
质量驱动血缘	质量问题沿血缘向上游传播。	DataHub + Monte Carlo	质量工具调用 DataHub API 获取上游 → 递归标记风险	全局影响评估
自动修复建议	基于质量结果推荐治理动作。	NLP + 规则引擎	”空值率 > 50%” → 建议”检查上游 ETL” 或 “添加数据清洗规则”	智能化治理
SLA 监控	将质量规则与数据 SLA 关联。	Amundsen（扩展）、自定义系统	在 DataHub 标记 SLA: 99.9% accuracy → 质量工具监控并告警	保障数据可靠性
闭环治理	从发现问题到修复的完整流程。	Jira + DataHub + dbt	质量失败 → DataHub 打标 → 创建 Jira → 修复后更新状态	实现治理闭环
统一评分卡	综合质量、完整性、使用率生成数据评分。	自定义评分模型	每日计算 Data Health Score = f(quality, freshness, usage)	数据资产估值、优先级排序