15分钟跑通DataHub元数据管理：3个由浅入深的定制配方-平芜编程栈

15分钟跑通DataHub元数据管理：3个由浅入深的定制配方

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

周四下午产品来催：周五前要把 Snowflake 里所有表的 schema 和 owner 接进公司的 DataHub 元数据管理平台，带 PII 后缀的表还要自动打标。以下是在测试机上从拉起环境到做完三个定制的真实流程，包括踩过的坑。

15分钟拉起本地DataHub并看到第一张表

Step 1：确认环境。需要 Docker Engine、Docker Compose v2 和 Python 3.10+。官方验证过的最低配置是 2 核 CPU、8GB 内存、13GB 磁盘。

docker --version && docker compose version python3 --version

Step 2：安装 DataHub CLI。这是你机器上唯一要装的软件，后面所有摄入都靠它。

python3 -m pip install --upgrade acryl-datahub datahub version

Step 3：一条命令拉起本地实例。这条命令会把 quickstart 的 compose 配置下载到~/.datahub/quickstart，然后启动 14 个容器（MySQL、OpenSearch、Kafka、GMS、前端等），正常网络下 10 分钟左右，大头在拉镜像。

datahub docker quickstart

Step 4：让 CLI 指向本地实例，并载入示例数据包。示例包里有约 1050 个实体，带血缘和词表，够你把界面摸熟。

datahub init --username datahub --password datahub datahub datapack load showcase-ecommerce

你此刻应该看到什么：打开 http://localhost:9002，用datahub/datahub登录，搜索fct_users_created，应能看到带 schema、所有权和上游血缘的数据集详情页。不想开浏览器也可以在终端验证：

datahub search "fct_users_created"

中途想推倒重来，datahub docker nuke一键清空，再跑一遍 quickstart 即可。

原理速览：刚才那几条命令背后发生了什么

先看整体面貌：左边是源源不断接入的源系统，右边是 GraphQL、REST、Kafka 三种消费出口，中间就是 DataHub 元数据平台本体。

再看datahub ingest走的细节链路：

这张图你只需记住：Kafka 的角色类似公司 OA 公告栏——所有元数据变更先贴到公告栏上，GMS 再把公告归档进 MySQL（唯一事实源）和搜索索引，UI 和 API 读的都是归档结果。

核心概念用一张表对完：

概念	一句话解释	项目里长什么样
Entity	数据资产的基本单元	Dataset、Dashboard、CorpUser
Aspect	实体上的一组属性	ownership、schemaMetadata，各是一个 PDL record
URN	实体的全局唯一标识	`urn:li:dataset:(urn:li:dataPlatform:snowflake,...)`
MCE / MCL	变更提案 / 变更记录事件	Kafka 上的两类 Avro 消息

细节可以看架构总览，现在不用通读，用到再回来查。

定制一：给摄入的表自动打标签、挂业务域

需求：Snowflake 摄入之后，表名带 pii 的自动贴pii标签，全部挂到analytics域。

不用改任何源码，正路是在 Recipe 里加 transformer，元数据流过时顺手加工。这段只干一件事：定义数据源和落点。

source: type: snowflake config: account_id: xy12345 username: "${SNOWFLAKE_USER}" password: "${SNOWFLAKE_PASSWORD}" database_pattern: allow: ["ANALYTICS"] sink: type: datahub-rest config: server: http://localhost:8080

这段只干一件事：声明两个转换——模式匹配打标、批量挂域。

transformers: - type: simple_add_dataset_globaltags config: tag_urns: ["urn:li:tag:pii"] - type: simple_add_domain config: domains: ["urn:li:domain:analytics"]

跑datahub ingest -c recipe.yml，然后打开对应数据集页面验证：标签栏出现pii，属性面板的 Domain 一栏出现 analytics 域。内置 transformer 全家桶和参数在 transformer 文档。

⚠️ 坑：你写进去的 URN（标签、域、owner）必须已经在实例里存在，transformer 不会自动创建这些实体。URN 不存在时标签静默失效，页面上什么都看不出来，记得先在 UI 里把标签建好。

定制二：加一个自定义Aspect，给数据集存数据质量分

需求：夜间跑质量引擎，给每张表打个分，想把这个分数存进 DataHub，又不想动核心模型。

轻量路径是metadata-models-custom模块：不碰主仓库的模型，构建出来当插件部署。需要动主仓库的，仓库地址在这里：

git clone https://gitcode.com/GitHub_Trending/da/datahub

这段只干一件事：定义新 Aspect 的 PDL。

namespace com.company.metadata.aspect @Aspect = { "name": "dataQualityScore" } record DataQualityScore { score: double lastEvaluated: long }

这段只干一件事：在实体注册表里声明这个 Aspect 挂到 dataset 上。

id: mycompany-dq-model entities: - name: dataset aspects: - dataQualityScore

这个文件放在metadata-models-custom/registry/entity-registry.yaml。注册表和实体、切面之间的关系长这样：

然后构建并安装插件：

cd metadata-models-custom ../gradlew build cd .. ./gradlew :metadata-models-custom:modelDeploy

安装完重启 GMS 容器让它加载新模型，再查配置端点确认加载成功：

docker restart datahub-datahub-gms-quickstart-1 curl -s http://localhost:8080/config | jq .models

输出里mycompany-dq-model下"loadResult": "SUCCESS"即成功。模块自带示例脚本：进metadata-models-custom/scripts目录跑./insert_one.sh，再datahub get --urn <urn>，就能看到 dataQualityScore 字段已经写进去了。

⚠️ 坑：PDL 要求文件名与 record 名一致、目录路径与 namespace 一致，任何一处对不上构建直接失败。上面这个例子，文件必须放在src/main/pegasus/com/company/metadata/aspect/DataQualityScore.pdl。

"到底该 fork 主仓库还是用自定义模型模块"的完整决策树，见扩展元数据模型文档和 metadata-models-custom 说明。

定制三：把dev环境的元数据变更同步到prod

需求：dev 环境拿来试跑，owner 和 schema 的变更要秒级反映到 prod 实例，不想两边各跑一遍摄入。

正路是 datahub-actions 框架：订阅源环境的 Kafka 变更流，把匹配的事件经 HTTP 转发给目标 GMS。配置十几行，这段只干一件事：订阅变更流并转发。

source: type: kafka config: connection: bootstrap: ${KAFKA_BOOTSTRAP_SERVER:-localhost:9092} schema_registry_url: ${SCHEMA_REGISTRY_URL:-http://localhost:8081} filter: event_type: MetadataChangeLogEvent_v1 action: type: metadata_change_sync config: gms_server: ${DEST_DATAHUB_GMS_URL} gms_auth_token: ${DEST_DATAHUB_GMS_TOKEN} aspects_to_include: [schemaMetadata, ownership, domain]

这张图你只需记住：actions 是个中转站，读源环境的"变更公告"再转帖给目标 GMS，不碰数据本身。

验证方式：在 dev 端改一个数据集的 owner，几秒内 prod 端同一数据集的 owner 跟着变。quickstart 的 compose 文件已内置 actions 容器，把这份配置挂进去、配好环境变量即可；带注释的完整样例看 metadata_change_sync.yaml。

⚠️ 坑：目标实例如果开了元数据服务认证而gms_auth_token没配，每条写入都是 401；另外源环境有自定义 aspect（比如你刚加的质量分）时，目标端必须先把模型插件部署好，否则对应 aspect 会被拒收。

上生产前对照这张表

quickstart 只适合试跑，生产要走 Kubernetes 部署，官方 K8s 指南有完整步骤。切换前把这张表过一遍：

关注点	建议做法	为什么
安全	更换全部默认凭据，开启元数据服务认证	quickstart 全是默认口令，端口默认绑定所有网卡
安全	OIDC 单点登录 + 按域最小权限的自定义策略	内置三种角色粒度不够，编辑权要按域圈定
性能	搜索集群 3 节点起，单分片 ≤50GB	搜索是元数据查询主链路，分片过大查询延迟陡增
性能	Kafka 消息保留 ≥7 天	actions 或消费者故障后能恢复回放
高可用	独立 MySQL 主从 + 定期`--backup`	单机 MySQL 无容灾，且备份不含时序数据
高可用	K8s 集群 ≥3 节点，无状态组件多副本	GMS 和前端可水平扩容、支持滚动升级