企业官网建设流程全解析

DataHub UI 无代码元数据摄取实战指南：从权限配置、定时同步到故障排查

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

本文围绕 DataHub 的UI 元数据摄取（Metadata Ingestion）功能展开：你将在不做任何代码开发的前提下，通过界面向导连接 Snowflake、BigQuery、MySQL、Kafka 等数据源，按计划自动把表结构、血缘、使用统计与数据质量信息拉入 DataHub，并学会如何用 Secrets 安全托管凭据、监控运行状态与排查失败。读完本文，你将掌握一条从权限准备、创建摄取源、调度执行到日志排障的完整闭环，并理解 UI 配置背后 GraphQL API 与调度器的实现原理。

什么是元数据摄取

DataHub 的价值在于帮助团队发现并理解组织内的数据资产。实现这一目标的关键机制就是metadata ingestion（元数据摄取）：由 DataHub 自动从各类数据系统中收集元数据，无需人工登记。UI 摄取可以自动拉取的信息包括：

• 表名与列名：来自各类数据库的结构信息，构成数据集目录的基础；
• 资产血缘（Asset Lineage）：展示信息如何在系统之间流转，支撑影响分析；
• 使用统计（Usage Statistics）：揭示哪些数据集最常被查询、最受欢迎；
• 数据质量信息：包括新鲜度（freshness）与完整性（completeness）；
• 业务上下文：如负责人（ownership）与文档（documentation）。

正因为如此，DataHub 可以轻松对接 Snowflake、BigQuery、dbt 等主流平台，并通过界面编排自动更新计划与安全托管凭据。本文描述的 UI 流程与 YAML 配方在 DataHub 中是同一套执行模型：无论是 UI 表单生成的 recipe，还是手工编写并通过 CLI/GraphQL 上传的 recipe，最终都会交给摄取执行器以 Python 方式运行（详见下文“YAML 高级配置”与 ingestion executor 安全说明）。

前置条件与权限

要在 DataHub 中管理元数据摄取，首先需要具备相应权限。权限体系分为“平台级管理权限”与“资源级策略”两种授予方式。

方式一：管理员级别访问

为获得全部摄取源的完整管理权限，用户需要被授予以下平台特权（platform privileges）：

授予途径有两种：

1. Admin 角色分配：被分配到Admin Role的用户默认即拥有上述两项特权；
2. 自定义策略授予平台特权：创建 自定义策略，将Manage Metadata Ingestion与Manage Secrets两项平台特权授予特定用户或用户组。

⚠️仅授予可信操作者：Manage Metadata Ingestion意味着你可以在 摄取执行器 上定义并运行 recipe。这些 recipe 会以 Python 形式运行在该进程中（包括自定义 source 类型、transformer、Kafkaoauth_cb回调，以及在非锁定镜像上安装额外 pip 包）。因此请把该特权视同“可在执行器上执行代码”的能力，而不仅仅是“创建一个 Snowflake 数据源”。

方式二：资源级策略（细粒度控制）

需要更细粒度控制时，管理员可以创建仅针对Ingestion Sources（摄取源）生效的 自定义策略，让不同用户拥有不同层级的访问能力：

• View（查看）：查看摄取源配置与运行历史；
• Edit（编辑）：修改摄取源配置（即执行器将要运行的 recipe）；
• Delete（删除）：删除摄取源；
• Execute（执行）：按需运行摄取源。与Edit组合时，等同于Manage Metadata Ingestion的代码执行能力，但作用范围被限定在这些摄取源上。

启用前置条件：

• DataHub Core：开启VIEW_INGESTION_SOURCE_PRIVILEGES_ENABLED特性开关（feature flag）；
• DataHub Cloud：联系客户成功团队开通该特性。

⚠️重要提醒：一旦启用该特性开关，任何作用于“All（全部）”资源类型的策略都将把 Ingestion Sources 纳入范围，包括默认的只读策略。这会让 Ingestion 页签可见，并可能根据所应用的特权产生可操作能力。如果你的环境中存在不应暴露“数据源页面”的纯查看策略，请谨慎启用此开关。

创建 Ingestion Source（摄取源）

获得相应权限后，进入 DataHub 的Ingestion页签。页面会列出当前所有处于启用状态的Ingestion Sources。这里的“摄取源”代表一个已配置好的、通往外部数据系统的连接——DataHub 正是通过它抽取元数据。初次使用时列表为空，接下来四步即可创建第一个摄取源。

从前端源码 IngestionSourceBuilderModal.tsx 可以看出，整个向导被组织为四个步骤组件：SelectTemplateStep（选择数据源）→DefineRecipeStep（配置连接）→CreateScheduleStep（同步计划）→NameSourceStep（命名完成），与下述操作一一对应。

第 1 步：选择数据源

点击+ Create source开始创建。随后选择要连接的数据源类型，DataHub 为热门平台提供了预置模板（pre-built templates）：

• 数据仓库（Data Warehouses）：Snowflake、BigQuery、Redshift、Databricks
• 数据库（Databases）：MySQL、PostgreSQL、SQL Server、Oracle
• 商业智能（BI）：Looker、Tableau、PowerBI
• 流式（Streaming）：Kafka、Pulsar
• 以及其他更多平台……

选择与你的数据源匹配的模板即可。如果列表中没有你的平台，可以选择Custom（自定义）手动配置 source，但这需要更多的技术知识。

这些模板并非空壳：仓库中的 sources.json 为每个平台预置了可直接运行的 recipe 骨架。例如 BigQuery 模板默认启用表/视图、血缘、使用统计与表级 profiling，并开启状态化摄取：

source: type: bigquery config: include_table_lineage: true include_usage_statistics: true include_tables: true include_views: true profiling: enabled: true profile_table_level_only: true stateful_ingestion: enabled: true

Redshift 模板则给出了坐标（host_port、database）、凭据占位（username: null）、血缘模式（table_lineage_mode: stl_scan_based）等字段，方便直接对照填写。

第 2 步：配置连接详情

选择模板后，需要配置 DataHub 如何连接并抽取元数据，界面会以用户友好的表单呈现：

• 名称与负责人（Name and Owners）：为摄取源起一个便于团队识别的描述性名称；可指定Users和/或Groups作为该摄取源的负责人。默认情况下，创建者本人会被设为负责人，创建后可随时增改；
• 连接信息（Connection Information）：按表单填写连接详情，具体字段因平台而异，通常包括：
  • 主机/服务器地址与端口；
  • 数据库或项目名称；
  • 认证凭据。
• 资产过滤器（Asset Filters）：配置要抽取的元数据范围：
  • 纳入哪些数据库、schema 或表；
  • 排除某些数据的过滤选项。
• 摄取设置（Ingestion Settings）：配置 profiling、过期元数据处理以及其他运行设置。默认值对大多数场景而言即为最佳实践。

用 Secrets 管理敏感信息

生产环境中，密码、API Key 等敏感信息应当通过 DataHub 的Secrets（密钥）功能安全存储。创建 Secret 的步骤：

1. 进入 Ingestion 界面中的Secrets页签；
2. 点击Create new secret；
3. 提供一个描述性名称（例如BIGQUERY_PRIVATE_KEY）；
4. 输入敏感值；
5. 可选：添加描述；
6. 点击Create。

创建完成后，在摄取配置表单的凭据字段处，可通过下拉菜单直接引用这些 Secret。前端的 Secret 创建界面位于 SecretBuilderModal.tsx，而sources.json中大量模板采用${MYSQL_PASSWORD}、${MCD_TOKEN}这类占位符写法，正是为了在表单中替换为已注册的 Secret。

🔒安全说明：DataHub 默认安全。GMS 会设置SECRET_SERVICE_CALLER_GUARD_MODE=ENFORCE，从而阻止浏览器会话和用户个人访问令牌（PAT）通过 GraphQL 调用getSecretValues。拥有Manage Secrets特权的用户仍可创建、更新、删除 Secret，但无法通过 API 读取明文值——除非管理员放宽该守卫（例如分阶段上线时设置为AUDIT）。

当计划任务中的 UI 摄取源运行时，Secret 由可信工作进程解析：OSS 版中是 datahub-actions（使用系统客户端凭据），DataHub Cloud 中则是内嵌执行器（使用 Remote Executor 访问令牌）。UI Secret 在服务端解密后，会在任务执行时通过 DataHub API（TLS）发送给该工作进程。对安全敏感的场景，建议改用 本地 Secret 后端 而非 DataHub UI Secrets。

测试连接

继续之前，务必验证 DataHub 能否成功连到数据源。大多数摄取源表单都提供Test Connection（测试连接）按钮，用于校验：

• 到数据源的网络连通性；
• 认证凭据是否正确；
• 是否具备元数据抽取所需的权限。

如果连接测试失败，请检查：

• DataHub 与数据源之间网络是否可达；
• 凭据是否正确且具备足够权限；
• 防火墙规则是否放行该连接。

高级设置（Advanced Settings）

需要更多控制力时，可在 Advanced Settings 区域配置：

• CLI Version：指定用于执行摄取的 DataHub CLI 具体版本；
• Environment Variables：为摄取进程设置自定义环境变量；
• Extra pip packages：运行时安装额外的 Python 包（在锁定执行器镜像上不可用）；
• Executor ID：按需配置远程执行；
• Debug Mode：启用详细日志以便排障。

其中“额外 pip 包”与镜像的关系值得展开：仓库 ingestion-executor-security.md 说明，*-locked锁定镜像基于预构建的捆绑虚拟环境（DATAHUB_BUNDLED_VENV_PATH，默认/opt/datahub/venvs），运行时镜像中已移除pip与uv，并将默认包索引 URL 指向不可用的 localhost 端点作为纵深防御。因此在锁定镜像上无法运行时pip install，新增连接器需用捆绑 venv 构建器（BUNDLED_VENV_PLUGINS、BUNDLED_CLI_VERSION）重新构建镜像，详见 捆绑摄取虚拟环境。

第 3 步：同步计划（Sync Schedule）

配置 DataHub 从数据源同步元数据的频率。可以通过开关启用或禁用计划执行（推荐启用），从而在无需人工干预的情况下保持元数据最新。如果你更倾向手动或按需运行，也可以完全跳过调度步骤。

第 4 步：审查并保存

审查全部配置无误后，有两种保存方式：

• Save：仅保存摄取源配置，不立即执行；
• Save and Run：保存并立即执行首次摄取。

运行与监控摄取

执行摄取源

创建完成后，点击摄取源上的Play（播放）按钮即可运行。稍等片刻，摄取源的Last Status（最近状态）列会变为Running，表示 DataHub 已成功将摄取任务入队。摄取成功后，状态会以绿色显示Success。

查看运行历史（Run History）

Run History页签展示所有摄取运行的完整历史，你可以：

• 查看全部运行：浏览所有摄取源的全部执行记录；
• 检查近期活动：运行记录按时间倒序排列，最新在前；
• 按源过滤：使用下拉框筛选某个特定摄取源的运行记录；
• 从 Sources 页签进入：点击任一源的Last Run状态，或从源菜单选择View Run History。

这让你可以持续追踪摄取表现，并在问题发生时及时排查。

查看摄取结果

摄取成功后，可查看被抽取实体的详细信息：

1. 点击完成运行的Success状态按钮；
2. 选择View All查看被摄取实体的列表；
3. 点击单个实体校验抽取出的元数据。

取消正在运行的摄取

如果某个摄取运行耗时过长或疑似卡住，可点击运行中任务上的Stop（停止）按钮取消它。这在以下场景尤其有用：

• 网络超时；
• 摄取源自身缺陷（bug）；
• 资源受限。

排查失败的摄取

常见失败原因

运行失败时，源列表中会出现失败状态指示。常见失败原因包括：

1. 配置错误：连接详情不正确、必填字段缺失或参数值非法；
2. 认证问题：凭据错误、令牌过期或权限不足；
3. 网络连通性：DNS 解析失败、防火墙拦截或数据源不可达；
4. Secret 解析问题：引用的 Secret 不存在或名称写错；
5. 资源限制：内存限制、超时或处理能力不足。

查看详细日志

要诊断失败原因，点击运行历史中的状态（Failed、Aborted）即可查看并下载完整的摄取运行日志。日志提供了：

• 连接尝试与错误；
• 认证失败信息；
• 数据抽取进度；
• 错误消息与堆栈轨迹（stack traces）。

已开启认证的 DataHub 实例

如果你的 DataHub 实例启用了 Metadata Service Authentication，则需要在配置中提供Personal Access Token（个人访问令牌）。

YAML 高级配置：超越 UI 表单

UI 表单足以覆盖大多数常见摄取场景，但高级用户可能仍需要直接编写 YAML 配置，典型场景包括：

• UI 中未提供的自定义摄取源；
• 复杂转换管道（transformation pipelines）；
• 高级过滤与处理逻辑；
• 与外部系统的集成。

需要再次强调信任边界：YAML recipe 同样以 Python 形式在摄取执行器上运行，自定义source.type、transformer 以及 Kafkaoauth_cb等回调都可以导入执行器上已有的代码。请只将Manage Metadata Ingestion（或 Edit+Execute）授予可信操作者——参见 Ingestion executor 安全。

关于 YAML 配置的完整语法与示例，请参阅 Recipe Overview 指南。

通过 CLI 部署 Recipe

可以使用 CLI 上传摄取 recipe（ingest deploy子命令详见 CLI 文档）：

datahub ingest deploy --name "My Test Ingestion Source" --schedule "5 * * * *" --time-zone "UTC" -c recipe.yaml

该命令的参数与 UI 表单一一对应：--name指定摄取源名称，--schedule为 Quartz 风格 cron 表达式（上例为每小时的第 5 分钟执行），--time-zone指定时区，-c指向本地 recipe 文件。

通过 GraphQL 创建摄取源

也可以直接使用 DataHub 的 GraphQL API 的createIngestionSourcemutation 创建摄取源：

mutation { createIngestionSource( input: { name: "My Test Ingestion Source" type: "mysql" description: "My ingestion source description" schedule: { interval: "*/5 * * * *", timezone: "UTC" } config: { recipe: "{\"source\":{\"type\":\"mysql\",\"config\":{\"include_tables\":true,\"database\":null,\"password\":\"${MYSQL_PASSWORD}\",\"profiling\":{\"enabled\":false},\"host_port\":null,\"include_views\":true,\"username\":\"${MYSQL_USERNAME}\"}},\"pipeline_name\":\"urn:li:dataHubIngestionSource:f38bd060-4ea8-459c-8f24-a773286a2927\"}" version: "0.8.18" executorId: "mytestexecutor" } } ) }

注意：通过 GraphQL 传递时，recipe 必须进行双引号转义（如上例中的\"）。

源码视角：摄取源的创建与调度

从实现层面看，UI、CLI 与 GraphQL 最终都汇聚到同一套后端流程：

• GraphQL resolver：createIngestionSource与updateIngestionSource均注册在 GmsGraphQLEngine.java，由 UpsertIngestionSourceResolver.java 统一处理。它首先通过IngestionAuthUtils.canManageIngestion校验MANAGE_INGESTION特权；创建新源时会生成 UUID 作为DataHubIngestionSourceKey，再以 Metadata Change Proposal（MCP）的形式把DataHubIngestionSourceInfo（类型、名称、recipe、CLI 版本、executorId、调试模式、额外参数与调度信息）写入实体图；
• Cron 校验与转换：resolver 在保存调度信息前，会先用 Spring 的CronExpression校验 cron 合法性，并用ZoneId.of校验时区；由于 Spring 只支持 6 段 cron，5 段 cron（Quartz 风格）会被自动加上前缀0（即秒位）——该逻辑与 IngestionScheduler.java 中的调整逻辑保持一致，两个入口对调度的语义完全统一；
• 调度执行：计划任务的运行由ingestion-scheduler模块负责，它从 GMS 轮询各摄取源的调度信息，按 cron 表达式在对应时区触发执行请求。

常见问题（FAQ）

为什么在 Docker 环境中摄取会报 "Failed to Connect" 错误？

如果你使用datahub docker quickstart运行 DataHub 且遭遇连接失败，可能是网络配置问题——摄取执行器无法触达 DataHub 的后端服务。尝试将摄取配置中的连接地址改为Docker 内部 DNS 名称（例如用datahub-gms等服务名代替localhost），而不是宿主机的localhost。

状态显示为短横线（-）是什么意思？如何修复？

如果摄取源状态一直显示-且从未变为Running，可能意味着：

1. 该源从未被触发运行——点击 "Play" 按钮执行即可；
2. datahub-actions 执行器未运行或不健康（仅 DataHub Core 用户）。

如果点击 "Play" 仍不生效，DataHub Core 用户应诊断 actions 容器：

1. 用docker ps检查容器状态；
2. 用docker logs <container-id>查看执行器日志；
3. 必要时重启 actions 容器。

何时应该用 CLI/YAML 而不是 UI 摄取？

考虑改用 CLI 摄取的情况：

• 数据源无法从 DataHub 所在网络触达（DataHub Cloud 场景可使用 remote executors）；
• 需要 UI 模板不具备的自定义摄取逻辑；
• 摄取过程需要访问本地文件系统；
• 希望将摄取任务分散到多个环境执行；
• 需要复杂转换或自定义元数据处理。

更多资源

• Recipe 文档：完整的 YAML 配置参考，覆盖所有 source 类型与配置项；
• 执行器安全：Ingestion executor 安全与加固，了解锁定镜像、包索引控制与信任边界；
• 远程执行器：设置远程摄取执行器，适用于数据源与 DataHub 网络隔离的场景；
• CLI 命令：datahub CLI 文档，其中ingest deploy支持从命令行上传 recipe。

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