企业官网建设流程全解析

• 数据目录
• 数据治理
• 数据血缘
• 后端
• 前端
• 数据工程
• 数据集成

为什么需要专门搭建 HMS 3.x 多 Catalog 测试环境？

随着 Hive 3.0 引入原生 multi-catalog 能力（默认hivecatalog，可扩展spark_catalog、iceberg_catalog等），企业中同一套 Hive Metastore（HMS）后端可能同时托管 Spark、Iceberg、Hive 等多种表格式的元数据。DataHub 的hive-metastore连接器需要验证：能否正确识别多 catalog 命名空间、同名表在不同 catalog 下是否被正确隔离、URN 生成是否受 catalog 影响。

本指南聚焦 DataHub 仓库中专门为 HMS 3.x 多 catalog 场景搭建的集成测试环境（hms3 测试目录），完整介绍其快速启动步骤、测试数据模型、两个关键配置项（catalog_name与include_catalog_name_in_ids）的用法与 URN 生成规则，并深入源码级原理与测试用例，帮助你在本地复现多 catalog 元数据摄取验证。

读完本文，你将掌握：用 Docker 一键拉起 HMS 3.x、用脚本灌入多 catalog 测试数据、通过环境变量控制测试执行方式、理解 catalog 名称如何影响数据集 URN，并能基于 golden file 机制对摄取结果做回归校验。

HMS 3.x 测试环境快速启动

前置条件

• Docker 与 Docker Compose（用于拉起 HMS 3.x 容器）
• Python 3 虚拟环境（仓库推荐venv，路径为metadata-ingestion/venv）
• pymetastore与thriftPython 库（测试与数据灌入脚本依赖）
• 已安装metadata-ingestion包（pip install -e .或按 metadata-ingestion 开发文档 安装）

启动与运行全流程

按官方文档，整个流程分为四步：

# 1. 启动 HMS 3.x（在 metadata-ingestion 目录下执行） cd tests/integration/hive-metastore docker compose -f docker-compose.hms3.yml up -d # 2. 等待 HMS 就绪（约 60-90 秒），然后灌入测试数据 cd ../../.. source venv/bin/activate python tests/integration/hive-metastore/hms3/setup-catalogs.py # 3. 运行集成测试（HMS3_EXTERNAL=1 跳过 docker-compose 启动，HMS3_SKIP_SETUP=1 跳过灌数脚本） HMS3_EXTERNAL=1 HMS3_SKIP_SETUP=1 pytest tests/integration/hive-metastore/test_hive_metastore_catalog.py -v # 4. 测试完成后清理 docker compose -f tests/integration/hive-metastore/docker-compose.hms3.yml down -v

要点说明：

• 第 3 步的两个环境变量是"短路开关"：HMS3_EXTERNAL=1表示 HMS 已由你手动启动（或已存在于外部环境），测试不再执行docker compose up；HMS3_SKIP_SETUP=1表示测试数据已手动灌好，测试跳过 setup 脚本。两者可以同时使用。
• 第 4 步的-v会连带删除名为hms3-data的命名卷，保证下次启动是全新环境。

Docker Compose 环境构成

docker-compose.hms3.yml 是这套测试环境的核心编排文件，关键设计如下：

services: hive-metastore-hms3: image: apache/hive:3.1.3 # 官方 Apache Hive 3.1.3 镜像，内嵌 Derby 元数据库 container_name: hive-metastore-hms3 environment: SERVICE_NAME: metastore # 以 metastore 模式启动 ports: - "9084:9083" # 宿主机 9084 -> 容器 9083，避开其他 HMS 实例 volumes: - hms3-data:/opt/hive/data - ./hms3/setup-catalogs.py:/opt/setup-catalogs.py:ro # 灌数脚本挂载进容器 healthcheck: test: ["CMD-SHELL", "nc -z localhost 9083 || exit 1"] interval: 10s timeout: 5s retries: 30 start_period: 90s # 与"约 60-90 秒就绪"一致

设计意图可从测试需求反推：

• 端口 9084：HMS 原生 Thrift 端口是 9083，测试特意映射到宿主机 9084，避免与开发者本机已有的其他 HMS 实例冲突。
• 命名卷hms3-data：持久化/opt/hive/data（含内嵌 Derby 数据库），保证多轮测试数据可复用。
• 健康检查：容器内用nc探测 9083 端口，start_period: 90s恰好对应 README 中"连接被拒约 60-90 秒"的提示——HMS 3.x 首次启动要初始化元数据库，这是"Connection refused"问题的最常见原因。

测试数据模型：多 Catalog 与命名空间隔离

setup-catalogs.py 通过 HMS 3.x Thrift API 灌入三层测试数据（catalog → database → table）。README 中的测试数据总览：

其中刻意设计了一处"陷阱"：users表同时存在于hive与spark_catalog，且字段完全不同，用于验证命名空间隔离。

灌数脚本的核心逻辑

脚本按顺序执行以下步骤（对应run_setup函数，setup-catalogs.py）：

1. 连接 HMS：connect_to_hms封装了带重试的连接逻辑（MAX_RETRIES = 30，每次间隔 2 秒，总计约 60 秒），解决 HMS 启动慢的问题。
2. 探测 catalog 能力：调用client.get_catalogs()列出已有 catalog，验证 HMS 3.x 是否开启多 catalog。
3. 创建 catalog：通过CreateCatalogRequest创建spark_catalog与iceberg_catalog。
4. 创建数据库：在三个 catalog 中分别建库，注意test_db在每个 catalog 中都有——这是命名空间隔离测试的关键。
5. 创建表：
   • hive.test_db.users：四列（id/name/email/created_at）
   • hive.test_db.events：四列 + 分区键event_date
   • spark_catalog.test_db.users：三列（user_id/username/active），与 hive 中的 users 字段完全不同，表属性带spark.table.version: 2.0
   • iceberg_catalog.test_db.transactions：三列，EXTERNAL_TABLE+table_type: ICEBERG
6. 验证：遍历所有 catalog 打印库表清单，确认数据就绪。

脚本支持--host与--port参数（默认localhost:9084），既可在宿主机直接运行，也被测试 fixture 以模块导入方式复用。

HMS 3.x 的 Catalog 访问协议细节

从 hive_thrift_client.py 可以看到连接器如何与多 catalog HMS 交互：

• 列出某 catalog 下的数据库：使用@{catalog_name}#模式调用get_databases（HMS 3.x 约定），如@spark_catalog#；
• 精确获取表：使用get_table_req并携带catName=catalog_name字段；
• 取某 catalog 内指定库的表：使用@{catalog_name}#{db_name}模式。

这些 API 封装（见HiveThriftClient的get_all_databases、get_table、get_fields等方法）是连接器支持多 catalog 的底层基础，与测试数据模型一一对应。

配置项：catalog_name 与 include_catalog_name_in_ids

配置文件示例（源自 README）

source: type: hive-metastore config: host_port: localhost:9084 catalog_name: spark_catalog # 可选，默认 'hive' include_catalog_name_in_ids: true # 是否把 catalog 名编入 URN

两个配置项在源码中的定义

在 hive_metastore_config.py 中：

注意catalog_name的取值语义：配置为spark_catalog时，连接器只摄取该 catalog 下的库表；未配置时回退到默认hivecatalog（这一回退逻辑见 hive_metadata_processor.py 的_get_db_name，优先级依次为catalog_name→metastore_db_name→database→ 兜底"hive"）。

catalog_name 在数据获取链路上的作用

catalog_name并非只影响 URN，它直接决定"读哪些元数据"。在 hive_thrift_fetcher.py 中，_get_catalog_name()返回该配置值，并被传入get_all_databases、iter_table_rows、iter_view_rows、iter_schema_rows、iter_table_properties_rows等全部数据获取方法；每个方法再透传给HiveThriftClient中带 catalog 语义的 Thrift 调用。也就是说，catalog_name在"连接器 → Thrift 客户端 → HMS API"整条链路上生效。

URN 生成规则

README 给出的两组 URN 对照：

• 不含 catalog：urn:li:dataset:(urn:li:dataPlatform:hive,test_db.users,PROD)
• 含 catalog：urn:li:dataset:(urn:li:dataPlatform:hive,spark_catalog.test_db.users,PROD)

include_catalog_name_in_ids还影响数据集标识符的解析。在 hive_metastore_source.py 的get_db_schema中：

• 开启时，标识符按catalog.db.table三段解析，取前两段分别作为 catalog 与 db；
• 关闭时，标识符按db.table两段解析，catalog 段被忽略。

对应地，hive_metadata_processor.py 在组装数据集平台实例等 aspect 时同样以该配置决定是否拼接 catalog 前缀。整体效果是：开启后 catalog 成为数据集标识的一部分，从而在 URN 层面把不同 catalog 中的同名表区分开。

集成测试与 Golden File 校验

测试文件概览

test_hive_metastore_catalog.py 是本环境的集成测试入口，包含三组场景：

1. 默认 catalog 摄取（test_ingest_default_catalog）：不配置catalog_name，验证摄取hive.test_db的 users/events，URN 不含 catalog 前缀。
2. 显式 catalog 摄取（test_ingest_spark_catalog）：catalog_name: spark_catalog+include_catalog_name_in_ids: false，URN 仍为test_db.users。
3. 含 catalog 的 URN 摄取（test_ingest_spark_catalog_with_catalog_ids）：include_catalog_name_in_ids: true，URN 变为spark_catalog.test_db.users。

另有test_urn_without_catalog_name/test_urn_with_catalog_name两个纯 URN 断言测试，直接检查输出 MCE 文件中是否包含（或不包含）spark_catalog.test_db.users字样。

此外还有两个直接针对 Thrift API 的测试：test_catalog_api_list_catalogs验证三个 catalog 都存在；test_catalog_api_namespace_isolation用get_table_req分别取hive.test_db.users与spark_catalog.test_db.users，断言二者列集合不同（hive 版含email，spark 版含active），从 API 层证明命名空间隔离真实生效。

Golden File 机制

三个摄取测试各自对应一份 golden 文件（MCE 快照），位于 hms3 目录：

• hive_metastore_hms3_default_catalog_mces_golden.json
• hive_metastore_hms3_spark_catalog_mces_golden.json
• hive_metastore_hms3_spark_catalog_with_ids_mces_golden.json

测试通过mce_helpers.check_golden_file将本次摄取结果与 golden 文件逐字段比对。由于时间戳、文件统计类属性每次运行都会变化，测试定义了IGNORE_PATHS（针对 old format 的transient_lastDdlTime、numfiles、totalsize、create_date）与IGNORE_PATHS_V2（对应 v2 路径的lastModified、created、COLUMN_STATS_ACCURATE等）进行豁免。

从 golden 文件可以看到摄取产物的形态：容器级containerProperties（name 为 catalog 名、customProperties 含 platform/env/database）、dataPlatformInstance、subTypes等 aspect 依次 UPSERT，且所有 MCE 的runId与测试名一一对应（如hms3-spark-catalog-ids-test）。这意味着新增表结构或调整配置后，只要输出与 golden 不符，测试即失败——这是对连接器行为的强回归保障。

测试默认跳过机制

该测试模块默认在 CI 中不执行：pytestmark中设置了skipif，仅当设置了HMS3_EXTERNAL=1或RUN_HMS3_TESTS=1才运行（见 test_hive_metastore_catalog.py）。原因是 HMS 3.x 的 Docker 环境存在平台兼容性问题（部分架构下apache/hive:3.1.3镜像无法正常运行）。本地复现时务必显式设置其中一个环境变量。

测试还依赖两个 fixture：

• hms3_runner：通过docker_compose_runner启动 Compose 文件，并用wait_for_port等待 9083 端口就绪（超时 180 秒）；
• loaded_hms3：以importlib动态加载setup-catalogs.py模块并调用run_setup(host="localhost", port=9084)，把灌数逻辑直接复用进测试生命周期（若HMS3_SKIP_SETUP=1则跳过）。

故障排查

README 给出的排障表：

结合源码可补充两点：

• Connection refused 的等待策略：setup-catalogs.py内置 30 次 × 2 秒的重试，总等待约 60 秒，通常足以覆盖 HMS 启动窗口；若仍失败，用docker compose -f tests/integration/hive-metastore/docker-compose.hms3.yml logs -f hive-metastore-hms3观察容器日志确认 metastore 是否完成初始化。
• 依赖缺失：pymetastore与thrift是灌数脚本与部分测试直接 import 的库；建议在metadata-ingestion的虚拟环境中一并安装，避免与系统 Python 冲突。

将测试配置迁移到真实摄取场景

理解了测试环境后，可以很容易地把同样能力用于生产摄取。一个对照示例：

source: type: hive-metastore config: connection_type: thrift # 多 catalog 仅支持 thrift 连接 host_port: your-hms-host:9083 use_kerberos: false # 若启用 Kerberos，参考 kerberos_service_name 等参数 catalog_name: spark_catalog # 只摄取 spark_catalog include_catalog_name_in_ids: true # 让同名表在 URN 层相互独立 database_pattern: allow: ["^test_db$"] # 与测试一致的正则过滤

几点来自源码的注意事项：

• catalog_name与include_catalog_name_in_ids均标注为"仅 thrift 连接类型"相关能力（前者明确只对 thrift 生效）；SQL 直连模式（connection_type: sql）不提供多 catalog 支持。同时 validate_thrift_settings 规定 thrift 模式只能使用mode: hive。
• include_catalog_name_in_ids一旦开启，现有 URN 会改变，会对下游引用产生连锁影响；从单 catalog 迁移到多 catalog 时建议先在测试环境验证 URN 变化，再决定是否开启。

结语

HMS 3.x 多 catalog 是混合数据湖表格式场景下的关键能力。通过metadata-ingestion/tests/integration/hive-metastore这套可复现的测试环境，你可以快速验证 DataHub 的hive-metastore连接器在多 catalog 下的元数据摄取正确性，理解catalog_name与include_catalog_name_in_ids的完整语义，并借助 golden file 机制保障行为回归。相关可深入研读的仓库文件：

• hms3 README：测试环境使用说明
• setup-catalogs.py：多 catalog 测试数据灌入实现
• docker-compose.hms3.yml：HMS 3.x 容器编排
• test_hive_metastore_catalog.py：集成测试与 URN 断言
• hive_metastore_config.py：连接器全部配置项定义
• hive_thrift_client.py：带 catalog 语义的 Thrift 调用封装

• 数据目录
• 数据治理
• 数据血缘
• 后端
• 前端
• 数据工程
• 数据集成