数据治理 OpenMetadata

第一章：OpenMetadata 概述

1.1 什么是 OpenMetadata

概念名称	说明	注意事项
OpenMetadata	开源的元数据管理平台，统一管理技术、业务和操作元数据，支持数据发现、血缘、数据质量、分类标签等功能。	需与商业元数据工具（如 Collibra、Alation）区分，OpenMetadata 强调开源、可扩展和深度集成。
元数据（Metadata）	描述数据的数据，如表名、字段类型、所有者、数据来源、更新频率等。	元数据本身也是数据，需被有效管理和治理。
统一元数据平台	OpenMetadata 的核心目标是将分散在不同系统中的元数据集中管理，打破数据孤岛。	需确保各数据源的连接器可用，并定期同步。
开放架构	基于开放标准和 API 优先设计，支持广泛集成和自定义扩展。	社区活跃度高，插件和连接器持续增加，建议关注官方发布版本。

1.2 核心架构与组件

组件名称	说明	注意事项
OpenMetadata Server	核心服务，提供 REST API 和 Web UI，负责元数据存储、查询和管理。	必须保持高可用，建议生产环境使用集群部署。
Metadata Database	存储所有元数据，默认使用 MySQL 或 PostgreSQL。	生产环境建议使用独立、高可用的数据库实例。
Elasticsearch	提供全文搜索能力，支持快速检索表、字段、描述等。	必须与 OpenMetadata Server 版本兼容，否则可能导致搜索失败。
Airflow / Ingestion Pipeline	用于执行元数据摄取任务，可通过 Airflow 或独立 Python 脚本运行。	Airflow 是推荐方式，便于调度和监控。
connectors（连接器）	支持多种数据源（如 MySQL、Snowflake、Kafka）的元数据采集。	每个连接器需配置认证信息，部分需网络可达。
UI（Web 前端）	提供可视化界面，用于浏览、搜索、管理元数据和血缘。	依赖后端服务正常运行，前端不存储数据。

1.3 元数据分类：技术、业务、操作元数据

元数据类型	说明	注意事项
技术元数据（Technical Metadata）	描述数据的技术属性，如数据库名、表结构、字段类型、分区信息、数据血缘等。	是数据发现和血缘分析的基础，通常通过自动摄取获取。
业务元数据（Business Metadata）	描述数据的业务含义，如字段业务术语、数据所有者、数据分类、敏感等级、数据质量规则等。	需要业务人员参与维护，可通过 UI 或 API 手动添加。
操作元数据（Operational Metadata）	描述数据的操作行为，如数据更新时间、ETL 作业执行记录、查询频率、访问日志等。	用于监控数据健康度和使用情况，部分来自系统日志或外部工具集成。

1.4 典型应用场景与优势

应用场景	说明	注意事项
数据发现（Data Discovery）	用户可通过搜索快速找到所需数据表及其详细信息。	需确保元数据完整性和准确性，否则影响搜索效果。
数据血缘（Data Lineage）	展示数据从源头到消费端的流转路径，支持影响分析和问题溯源。	自动血缘依赖解析 SQL 或日志，手动血缘可通过 API 补充。
数据治理与合规	通过分类标签（如 PII、GDPR）标记敏感数据，支持合规审计。	需建立标签管理规范，避免标签滥用或遗漏。
数据质量监控	集成数据质量测试，监控关键字段的完整性、唯一性等指标。	测试需定期执行，结果可用于告警或报表。
协作与知识共享	支持添加描述、标签、关注者，促进团队协作。	鼓励团队成员主动维护元数据，形成数据文化。
优势：开源与可扩展	社区驱动，代码透明，支持自定义实体和插件开发。	需投入一定开发资源进行定制和维护。
优势：统一平台	集成多种功能（发现、血缘、质量、治理），避免工具碎片化。	初期部署复杂度较高，需合理规划。

第二章：安装与部署

2.1 环境要求与依赖

依赖项	要求	注意事项
Java	JDK 11 或 17	OpenMetadata Server 基于 Java 开发，必须安装对应版本。
Python	3.7 - 3.11	用于运行摄取管道（Ingestion Pipeline）。
Docker	20.10+	推荐使用 Docker 快速部署，需启用 Docker Compose。
Kubernetes	1.21+	如使用 Helm 部署，需准备 K8s 集群。
MySQL	8.0+ 或 PostgreSQL 12+	作为元数据后端存储，需提前准备数据库实例。
Elasticsearch	7.15+ 或 8.x	用于全文搜索，版本需与 OpenMetadata 兼容。
内存	至少 4GB 可用内存	Docker 环境下建议分配 4GB 以上内存。
网络	数据源可访问	摄取服务需能连接目标数据库、数据仓库等。

2.2 使用 Docker 快速部署

方法名称	语法	用途	代码示例	注意事项
启动 Docker Compose	docker-compose up -d	启动 OpenMetadata 及依赖服务（MySQL、Elasticsearch）	docker-compose -f docker-compose.yml up -d	确保当前目录包含正确的 docker-compose.yml 文件
查看服务状态	docker-compose ps	检查各容器是否正常运行	docker-compose ps	所有服务状态应为 “Up”
查看日志	docker-compose logs [service]	排查启动失败问题	docker-compose logs openmetadata-server	关注 openmetadata-server 和 elasticsearch 日志
停止服务	docker-compose down	停止并移除容器	docker-compose down	数据将保留在卷中，除非使用 -v 删除卷

2.3 使用 Kubernetes 部署（Helm）

方法名称	语法	用途	代码示例	注意事项
添加 Helm 仓库	helm repo add open-metadata https://helm.open-metadata.org	添加 OpenMetadata Helm 仓库	helm repo add open-metadata https://helm.open-metadata.org	仅需执行一次
更新 Helm 仓库	helm repo update	同步最新 Chart	helm repo update	部署前建议执行
安装 OpenMetadata	helm install [RELEASE_NAME] open-metadata/openmetadata --namespace [NAMESPACE]	部署 OpenMetadata 到指定命名空间	helm install openmetadata open-metadata/openmetadata --namespace openmetadata	需提前创建命名空间
自定义配置安装	helm install ... -f values.yaml	使用自定义 values.yaml 覆盖默认配置	helm install om open-metadata/openmetadata -f my-values.yaml	推荐用于生产环境
升级部署	helm upgrade [RELEASE_NAME] open-metadata/openmetadata	升级到新版本	helm upgrade openmetadata open-metadata/openmetadata	注意备份和版本兼容性
卸载部署	helm uninstall [RELEASE_NAME]	删除 OpenMetadata 发布	helm uninstall openmetadata	数据是否保留取决于持久化配置

2.4 配置文件详解（openmetadata.yaml）

配置项	说明	注意事项
database.hostname	元数据数据库主机地址	可为本地或远程数据库，需确保网络可达
database.port	数据库端口，默认 3306（MySQL）或 5432（PostgreSQL）	根据实际数据库类型设置
database.name	元数据数据库名称	建议使用专用数据库，如 openmetadata_db
database.user / password	数据库访问凭证	生产环境建议使用密钥管理工具，避免明文
elasticsearch.hosts	Elasticsearch 地址列表	格式为 ["http://host:9200"]，支持多个节点
elasticsearch.auth	认证配置（如启用）	可配置用户名密码或 API Key
clusterName	Elasticsearch 集群名称	若使用 AWS OpenSearch 等托管服务需设置
pipelineServiceClientConfiguration	摄取管道客户端配置	包括 Airflow 或 Standalone 模式设置
authenticationConfiguration	认证方式配置（JWT、LDAP 等）	决定用户如何登录系统
authorizerConfiguration	授权配置，定义角色和权限	与认证方式配合使用
customOauth2Configuration	自定义 OAuth2 配置	用于集成企业 SSO

2.5 启动与验证服务

方法名称	语法	用途	代码示例	注意事项
检查容器状态	docker-compose ps	确认 openmetadata-server 是否运行	docker-compose ps	状态应为 “Up”
查看服务日志	docker-compose logs openmetadata-server	检查启动是否成功	docker-compose logs openmetadata-server	等待出现 “OpenMetadata server is UP”
访问 Web UI	http://localhost:8585	打开 OpenMetadata 前端界面	浏览器访问 http://localhost:8585	首次启动需等待 1-2 分钟
调用健康检查 API	curl http://localhost:8585/health	检查服务健康状态	curl http://localhost:8585/health	返回 {"status":"UP"} 表示正常
登录系统	使用默认账号 admin / admin	首次登录并修改密码	Web 页面输入账号密码	建议首次登录后立即修改密码
验证 Elasticsearch	curl http://localhost:9200	检查搜索服务是否就绪	curl http://localhost:9200	确保 ES 正常运行，否则搜索功能失效

第三章：用户与权限管理

3.1 用户、团队与角色模型

概念名称	说明	注意事项
用户（User）	系统的使用者，通过认证后登录 OpenMetadata，可查看、编辑或管理元数据。	每个用户有唯一邮箱标识，支持本地账户或外部身份源同步。
团队（Team）	用户的组织单元，用于权限继承和资源归属管理，支持多级嵌套（如 org > dept > team）。	建议按企业组织结构创建团队，便于权限批量管理。
角色（Role）	定义一组权限的集合（如 DataConsumer、DataSteward），不直接绑定用户，而是通过策略（Policy）关联。	角色是静态权限模板，OpenMetadata 提供默认角色，也支持自定义。
策略（Policy）	将角色与用户/团队关联的规则，实现”谁在什么资源上拥有什么权限”。	是权限分配的核心机制，需谨慎配置避免越权。
资源（Resource）	被保护的对象，如表、服务、分类、管道等元数据实体。	权限可作用于全局、服务级或具体实体。
所有者（Owner）	某个元数据实体（如表）的负责人，通常具有管理权限，并可在 UI 中展示。	所有者可以是用户或团队，用于明确数据责任归属。

3.2 创建用户与团队

方法名称	语法	用途	代码示例	注意事项
创建团队（UI）	Web UI > Settings > Teams > Create	通过界面创建新团队	无	需管理员权限，支持设置团队描述、父级团队
创建团队（API）	POST /api/v1/teams	使用 API 创建团队	{ "name": "data-engineering", "displayName": "Data Engineering", "teamType": "Department" }	teamType 可为 Group、Department、BusinessUnit 等
创建用户（UI）	Web UI > Settings > Users > Invite	邀请用户（发送邮件）	无	仅支持启用认证的环境（如 JWT、LDAP）
创建用户（API）	POST /api/v1/users	通过 API 创建用户	{ "name": "alice", "email": "alice@company.com", "firstName": "Alice" }	通常用于与外部系统同步用户
添加用户到团队	PUT /api/v1/teams/{id}/users	将用户加入指定团队	{ "users": [ { "id": "user-id-123", "type": "user" } ] }	需团队管理权限
设置实体所有者	PUT /api/v1/tables/{id}/owner	为表等资源设置所有者	{ "owner": { "id": "user-or-team-id", "type": "user" } }	所有者将收到通知，可在 UI 查看归属

3.3 角色与权限配置（Policy & Role）

方法名称	语法	用途	代码示例	注意事项
查看角色列表	GET /api/v1/roles	获取所有可用角色	curl http://localhost:8585/api/v1/roles	默认角色包括 Admin、DataConsumer、DataSteward 等
创建自定义角色	POST /api/v1/roles	定义新角色	{ "name": "Analyst", "permissions": [ "viewTable", "viewDashboard" ] }	目前权限粒度由系统预定义，不可任意组合
创建策略（Policy）	POST /api/v1/policies	创建权限策略	{ "name": "Analyst Policy", "policyType": "AccessControl", "rules": [ { "effect": "allow", "actions": ["View"], "resources": ["table"], "condition": { "attribute": "team", "value": "analytics", "operator": "eq" } } ] }	策略配置复杂，建议通过 UI 操作
启用/禁用策略	PUT /api/v1/policies/{id}	更新策略状态	{ "enabled": false }	禁用策略立即生效，用于临时权限回收
关联角色与用户/团队	在 Policy 的 rules 中指定 principal	将角色分配给主体	"principals": [ { "id": "team-id-123", "type": "team" } ]	推荐按团队分配，便于批量管理
权限继承	团队层级自动继承	子团队继承父团队权限	无	需合理设计团队结构，避免权限泄露

3.4 认证方式：JWT、SAML、LDAP、OAuth2

认证方式	说明	注意事项
JWT（默认）	基于本地用户数据库和 JSON Web Token 认证，适用于测试和简单场景。	默认开启，admin 用户使用 admin 密码登录，生产环境建议替换为外部认证。
LDAP / Active Directory	支持通过 LDAP 协议集成企业目录服务，统一用户管理。	需配置 LDAP 服务器地址、绑定 DN、搜索基等，确保网络可达。
SAML 2.0	支持与 Okta、Azure AD、OneLogin 等 SSO 提供商集成，实现单点登录。	配置较复杂，需在双方系统注册应用并交换元数据。
OAuth2 / OpenID Connect	支持 Google、GitHub、Auth0 等 OAuth2 提供商，适合云环境。	需配置 clientId、clientSecret、授权端点、令牌端点等信息。
认证配置文件	在 openmetadata.yaml 中的 authenticationConfiguration 部分设置	启用并配置外部认证源
多认证源支持	可同时启用多种认证方式	用户可通过不同方式登录
Token 过期时间	可配置 JWT 令牌有效期（默认 24 小时）	提高安全性，减少长期有效令牌风险

第四章：数据源连接与元数据摄取

4.1 摄取工作原理（Ingestion Framework）

概念名称	说明	注意事项
Ingestion Framework	OpenMetadata 的元数据摄取框架，基于 Python 开发，支持多种数据源的元数据提取、转换和加载。	摄取任务可独立运行或集成到 Airflow 等调度系统中。
Metadata Ingestion SDK	提供 Python 包 openmetadata-ingestion，用于构建和运行摄取管道。	需安装对应连接器插件（如 pip install 'openmetadata-ingestion[mysql]'）。
Pipeline（管道）	定义一个摄取任务的配置文件，包含源、处理器、加载器等组件。	配置为 YAML 格式，结构清晰，支持复用。
Source Connector	负责连接具体数据源（如 MySQL），提取原始元数据。	每种数据源有专用连接器，需正确配置认证信息。
Processor	处理器用于过滤、增强或转换元数据（如生成血缘）。	常用处理器包括 metadata-filter、lineage-filter 等。
Stage	可选中间存储（如文件、Elasticsearch），用于调试或备份。	生产环境通常直接加载到 OpenMetadata 服务。
Sink	目标接收器，通常是 OpenMetadata 服务 API，用于写入元数据。	必须确保 OpenMetadata 服务可达且认证通过。
Airflow Integration	支持将摄取管道注册为 Airflow DAG，实现调度和监控。	使用 Ingestion DAG Builder 自动生成 DAG 文件。

4.2 支持的数据源类型概览

数据源类型	支持的数据平台	说明	注意事项
关系型数据库	MySQL、PostgreSQL、Oracle、SQL Server、SQLite	支持提取数据库、表、视图、字段、主键、索引等元数据。	需提供只读账号，避免影响生产性能。
数据仓库	Snowflake、BigQuery、Redshift、Databricks、ClickHouse	支持仓库、模式、表、列、标签、使用统计等。	部分平台（如 BigQuery）支持自动采集查询日志用于血缘。
NoSQL 数据库	MongoDB、DynamoDB	支持集合、文档结构（模式推断）等元数据。	模式动态，元数据可能不完整。
消息系统	Kafka、Pulsar	提取主题（Topic）、分区、生产者/消费者信息。	通常用于构建数据流血缘。
BI 工具	Tableau、Looker、Power BI	提取仪表板、图表、数据源映射关系。	支持反向血缘（从 BI 到表）。
数据编排工具	Airflow、Dagster	提取 DAG、任务、依赖关系。	可构建任务级血缘。
对象存储	S3、GCS、Azure Blob	支持存储桶、文件路径、格式（Parquet、CSV）等。	常用于湖仓一体场景。
其他	Superset、Trino、Presto、Druid、Pinot	广泛支持主流数据平台。	持续增加新连接器，建议查看官方文档确认版本兼容性。

4.3 使用 Ingestion Pipeline 连接数据库（如 MySQL、PostgreSQL）

方法名称	语法	用途	代码示例	注意事项
安装 MySQL 连接器	pip install 'openmetadata-ingestion[mysql]'	安装 MySQL 摄取依赖	pip install 'openmetadata-ingestion[mysql]'	使用方括号语法安装插件
安装 PostgreSQL 连接器	pip install 'openmetadata-ingestion[postgresql]'	安装 PostgreSQL 摄取依赖	pip install 'openmetadata-ingestion[postgresql]'	同上
创建摄取配置文件	config.yaml	定义 MySQL/PostgreSQL 摄取管道	见下方 YAML 示例	必须包含 service connection、sink、pipeline 信息
运行摄取管道	metadata ingest -c config.yaml	执行元数据摄取	metadata ingest -c mysql_ingestion.yaml	确保网络可达数据库
验证摄取结果	查看 OpenMetadata UI	确认表和字段已显示	无	在 Services 下查找对应数据库服务

MySQL 摄取配置文件示例（config.yaml）：

source:
  type: mysql
  serviceName: mysql_service
  serviceConnection:
    config:
      type: Mysql
      hostPort: localhost:3306
      username: user
      password: secret
      databaseName: mydb
sourceConfig:
  config:
    markDeletedTables: true
    includeTables: true
    includeViews: true
sink:
  type: metadata-rest
  config: {}
workflowConfig:
  openMetadataServerConfig:
    hostPort: http://localhost:8585/api
    authProvider: no-auth

4.4 连接数据仓库（如 BigQuery、Snowflake、Redshift）

方法名称	语法	用途	代码示例	注意事项
安装 BigQuery 连接器	pip install 'openmetadata-ingestion[bigquery]'	安装 BigQuery 支持	pip install 'openmetadata-ingestion[bigquery]'	需提供 GCP 服务账户密钥文件
安装 Snowflake 连接器	pip install 'openmetadata-ingestion[snowflake]'	安装 Snowflake 支持	pip install 'openmetadata-ingestion[snowflake]'	需 ACCOUNT、USER、PASSWORD 或 SSO
安装 Redshift 连接器	pip install 'openmetadata-ingestion[redshift]'	安装 Redshift 支持	pip install 'openmetadata-ingestion[redshift]'	类似 PostgreSQL，但需 AWS 凭证
配置 GCP 服务账户	serviceAccountKeyFilePath	指定密钥文件路径	serviceAccountKeyFilePath: /path/to/key.json	推荐使用密钥文件而非环境变量
启用查询日志采集	includeQueryHistory: true	用于 BigQuery/Snowflake 血缘	includeQueryHistory: true	增加 API 调用次数，注意配额
设置项目/账户信息	projectID / account	指定目标项目或账户	projectID: my-gcp-project	必填项
运行数据仓库摄取	metadata ingest -c dw_config.yaml	执行摄取任务	metadata ingest -c snowflake.yaml	确保 OpenMetadata 服务正常

4.5 连接消息系统（Kafka）与 BI 工具（Tableau、Looker）

方法名称	语法	用途	代码示例	注意事项
安装 Kafka 连接器	pip install 'openmetadata-ingestion[kafka]'	支持 Kafka 元数据摄取	pip install 'openmetadata-ingestion[kafka]'	需 Kafka Broker 地址
配置 Kafka 摄取	source.type: kafka	定义 Kafka 源	source: { type: kafka, serviceName: kafka_svc, serviceConnection: { config: { bootstrapServers: localhost:9092 } } }	支持 SASL_SSL 认证
安装 Tableau 连接器	pip install 'openmetadata-ingestion[tableau]'	摄取 Tableau 仪表板元数据	pip install 'openmetadata-ingestion[tableau]'	需 siteName、credentials
配置 Tableau 连接	connectionOptions	指定 Tableau Server 配置	connectionOptions: { env: tableau_prod }	支持多环境
安装 Looker 连接器	pip install 'openmetadata-ingestion[looker]'	摄取 Looker 探索和仪表板	pip install 'openmetadata-ingestion[looker]'	需 API 3.1 凭证
配置 Looker 摄取	clientId / clientSecret	提供 Looker API 凭据	clientId: abc123, clientSecret: xxxxxx	建议使用专用 API 用户
提取 BI 血缘	enableDataSources: true	自动解析 BI 查询对应的数据表	enableDataSources: true	是实现反向血缘的关键

4.6 调度与增量元数据同步

方法名称	语法	用途	代码示例	注意事项
生成 Airflow DAG	metadata generate -c config.yaml --dag-name ingest_mysql	从配置生成 Airflow DAG	metadata generate -c mysql.yaml --dag-name mysql_ingest	生成 Python 文件，放入 Airflow DAGs 目录
调度频率设置	airflowPipelineType	在配置中指定调度类型	airflowPipelineType: Manual/Ingestion/Profiler	Ingestion 可自动调度
增量同步机制	markDeletedTables: true	标记已删除表为已弃用	markDeletedTables: true	下次同步时自动标记不存在的表
全量 vs 增量	默认全量扫描	每次扫描所有对象，对比变化	无	性能随数据量增长而下降
调度器（Airflow）	使用 Airflow Scheduler	定时触发摄取任务	schedule_interval: '@daily'	推荐生产环境使用
手动触发摄取	metadata ingest -c config.yaml	立即执行一次摄取	metadata ingest -c latest.yaml	用于调试或紧急同步
错误重试机制	retry: 3, delay: 30	在 workflowConfig 中配置	workflowConfig: { loggerLevel: DEBUG, ... }	提高摄取稳定性

第五章：元数据浏览与搜索

5.1 服务（Services）、数据库、表、字段的层级结构

层级名称	说明	注意事项
Service（服务）	最顶层容器，代表一个数据源实例（如 MySQL 实例、Snowflake 账户）。	每个服务有唯一名称，需先创建服务才能摄取元数据。
Database（数据库）	服务下的数据库（如 MySQL 中的 DB），逻辑隔离单元。	支持多数据库，如 sales_db、hr_db。
Database Schema（模式）	数据库内的模式（如 PostgreSQL 的 public），包含表和视图。	部分数据库（如 MySQL）模式与数据库同义。
Table / View（表/视图）	数据存储单元，包含字段和数据。	支持分区表、物化视图等特殊类型。
Column（字段）	表的列，包含名称、类型、描述、约束等属性。	字段级元数据支持血缘、分类、测试等。
FQN（完全限定名）	全路径标识符，格式为 service.database.schema.table.column	用于 API 查询和跨系统引用，唯一且稳定。

5.2 使用 Web UI 浏览元数据

操作名称	路径/方法	用途	示例	注意事项
查看服务列表	主页 > Databases / Pipelines / Dashboards	浏览已注册的数据服务	点击 “Mysql Service”	服务状态显示最近摄取时间
展开数据库结构	点击服务 > Database > Schema	逐层查看数据库、模式、表	mysql_svc > sales_db > public	支持折叠/展开
查看表详情	点击具体表名	显示表的 Schema、描述、所有者等	orders_table	可编辑描述和标签
查看字段信息	在表详情页查看 Columns 列表	显示字段名、类型、描述、血缘	order_id, VARCHAR(50)	支持点击字段查看血缘
编辑元数据	点击铅笔图标编辑描述、所有者、标签	手动补充业务元数据	添加 “客户订单主表” 描述	鼓励用户参与维护
查看关联实体	查看 Tables、Dashboards、Pipelines 标签页	发现数据使用场景	查看哪些仪表板使用该表	支持反向依赖分析

5.3 全文搜索与高级过滤

功能名称	语法/操作	用途	示例	注意事项
全局搜索框	顶部搜索栏	快速查找表、字段、仪表板等	输入 “user”	返回包含 user 的表、字段、描述
模糊匹配	支持部分匹配	提高搜索召回率	搜 “order” 可得 “orders”, “order_items”	基于 Elasticsearch 实现
高级过滤	使用 filter: 语法	按属性精确过滤	service: mysql_service status: active	支持 service、database、tier、tags 等
字段级搜索	field: 字段名	搜索特定字段	field: customer_email	常用于查找敏感数据
分类搜索	classification: PII	查找标记为 PII 的数据	classification: GDPR	需提前配置分类策略
所有者搜索	owner: alice	查找某人负责的数据	owner: data-team	支持用户或团队

5.4 血缘关系（Data Lineage）查看

功能名称	操作方式	用途	示例	注意事项
查看表级血缘	表详情页 > Lineage Tab	展示表的上下游依赖	查看 fact_orders 的来源和去向	自动解析 ETL 或查询日志生成
查看字段级血缘	点击具体字段 > Field Lineage	展示字段级数据流转	order_id 如何从 staging 映射到 dwd	精度高，依赖 SQL 解析
手动添加血缘	API 或 UI（支持）	补充自动采集缺失的血缘	连接两个无自动血缘的表	用于批处理或外部系统
血缘方向	支持上游（Upstream）和下游（Downstream）	分析影响范围或溯源问题	影响分析：修改表会影响哪些下游？	双向查看更全面
血缘层级	可展开多层	查看深层依赖关系	从报表一直追溯到原始日志	层级过多可能影响性能
血缘来源	显示血缘采集方式	判断血缘可信度	来自 Airflow DAG 或 BigQuery 查询	自动 > 手动 > 推断

5.5 表详情页：Schema、Owners、Queries、Usage

信息模块	说明	注意事项
Schema	显示表的所有字段，包括名称、类型、描述、是否为主键/分区键等。	支持点击字段查看详细信息和血缘。
Owners	显示数据所有者（个人或团队），可编辑。	所有者可接收通知，建议明确责任人。
Description	表的业务描述，支持 Markdown 格式。	鼓励填写，提高数据可理解性。
Tags	业务或合规标签，如 PII、GDPR、Finance。	可用于搜索和访问控制。
Lineage	图形化展示上下游数据流。	支持拖拽和缩放，操作流畅。
Queries	显示近期查询该表的 SQL 语句（来自查询日志）。	帮助理解数据使用方式，需启用查询日志采集。
Usage	展示访问频率统计（如 7天、30天查询次数）。	用于识别热门或冷门表，优化资源。
Followers	关注该表的用户列表。	促进协作，更新时可通知关注者。
Related Dashboards	显示使用该表的 BI 仪表板。	实现数据到消费端的闭环。
Edit 按钮	允许有权限用户编辑描述、所有者、标签等。	需分配 DataSteward 或 Owner 角色。

第六章：数据质量与数据测试

6.1 数据质量模块概述

概念名称	说明	注意事项
数据质量（Data Quality）	OpenMetadata 提供内置的数据质量模块，用于定义、执行和监控数据测试，确保数据的准确性、完整性、一致性等。	需与摄取框架集成，支持多种数据源。
测试定义（Test Definition）	描述一个测试的通用逻辑，如”非空检查”、“唯一性检查”。	系统预定义，用户不可修改。
测试用例（Test Case）	基于测试定义创建的实例，绑定到具体表或字段，包含参数（如列名）。	用户可创建多个用例，用于不同场景。
测试执行（Test Execution）	定期运行测试用例，生成结果（通过/失败/错误）。	可通过 Airflow 或独立任务调度。
结果存储	测试结果存储在 OpenMetadata 元数据库中，可通过 API 或 UI 查询。	支持历史结果查看，便于趋势分析。
断言规则（Assertion Rules）	测试用例中的条件逻辑，如 nullCount == 0 表示不允许空值。	由测试类型决定可用规则。

6.2 创建数据质量测试（Test Cases）

方法名称	语法	用途	代码示例	注意事项
创建测试用例（UI）	表详情页 > Profiler & Data Quality > Tests > Add Test	通过界面创建测试	无	需有表的编辑权限
创建测试用例（API）	POST /api/v1/dataQuality/testCases	使用 API 创建测试用例	{ "name": "orders_order_id_not_null", "testDefinition": { "id": "not-null-test-id", "type": "notNull" }, "entityLink": "<#E::table::mysql_service.sales_db.orders>", "parameterValues": [ { "name": "column", "value": "order_id" } ] }	entityLink 必须为 FQN 格式
获取测试定义列表	GET /api/v1/dataQuality/testDefinitions	查看支持的测试类型	curl http://localhost:8585/api/v1/dataQuality/testDefinitions	常见类型：notNull、unique、acceptedValues 等
绑定到字段	在 parameterValues 中指定 column	为特定字段创建测试	"parameterValues": [ { "name": "column", "value": "email" } ]	支持字段级粒度
启用/禁用测试	PATCH /api/v1/dataQuality/testCases/{id}	更新测试状态	{ "enabled": false }	禁用后不再执行

6.3 配置测试用例与断言规则

测试类型	参数名称	用途	示例值	注意事项
notNull	column	检查字段是否无空值	”user_id”	适用于主键或必填字段
unique	column	检查字段值是否唯一	”email”	常用于唯一标识符
acceptedValues	column, acceptedValues	检查字段值是否在允许列表中	”status”, [“active”,“inactive”]	适用于枚举类型
columnValueMinToBeBetween	column, minValue, maxValue	检查字段最小值是否在范围内	”age”, 0, 150	数值范围校验
columnValueMaxToBeBetween	column, minValue, maxValue	检查字段最大值是否在范围内	”score”, 0, 100
columnValueMeanToBeBetween	column, minValue, maxValue	检查字段均值是否在范围内	”price”, 10.0, 1000.0
columnValueMedianToBeBetween	column, minValue, maxValue	检查字段中位数是否在范围内	”income”, 30000, 80000
columnValueStdDevToBeBetween	column, minValue, maxValue	检查字段标准差是否在范围内	”height”, 0.1, 2.0
tableRowCountToBeBetween	min, max	检查表行数是否在范围内	1000, 100000	用于监控数据量异常
tableRowCountToEqual	value	检查表行数是否等于某值	5000
columnValuesToBeUnique	column	同 unique，语义相同	”transaction_id”
columnValuesToNotMatchRegex	column, regex	检查字段值不匹配正则表达式	”phone”, ”^\d{3}-\d{3}-\d{4}$“	用于格式校验
columnValuesToMatchRegex	column, regex	检查字段值匹配正则表达式	”email”, ”^.+@.+..+$“

6.4 执行测试与查看结果

方法名称	语法	用途	代码示例	注意事项
执行测试（CLI）	metadata test -c test_case.yaml	运行测试用例	metadata test -c orders_not_null.yaml	需配置正确的测试用例文件
执行测试（Airflow）	使用 Data Quality DAG	在调度中自动执行	由 ingestion pipeline 自动生成	推荐生产环境使用
查看测试结果（API）	GET /api/v1/dataQuality/testCaseResult	获取测试执行结果	curl http://localhost:8585/api/v1/dataQuality/testCaseResult?testCaseFQN=...	支持分页和时间范围过滤
查看结果（UI）	表详情页 > Tests > Results	图形化展示历史执行结果	无	显示通过率、失败趋势
测试结果状态	passed / failed / error	执行结果状态	"testCaseStatus": "Failed"	error 表示执行异常
执行时间	timestamp	记录每次执行时间	"timestamp": 1728000000000	用于监控执行频率
失败详情	computePassedFailedRowCount	显示失败记录数	"failedCount": 5	帮助定位问题数据

6.5 集成 CI/CD 与告警机制

集成方式	配置方法	用途	示例	注意事项
CI/CD 集成	在 CI 流水线中运行 metadata test	在代码合并前验证数据质量	在 GitHub Actions 中执行测试	防止劣质数据模型上线
Slack 告警	配置 Webhook	测试失败时发送通知	https://hooks.slack.com/services/...	需在 OpenMetadata 配置告警服务
Email 告警	配置 SMTP	发送邮件通知	需提供 SMTP 服务器信息	适用于关键数据表
Airflow 告警	使用 Airflow Alert	任务失败时触发告警	在 DAG 中设置 on_failure_callback	与调度系统深度集成
自定义 Webhook	POST 到任意 HTTP 端点	集成企业内部告警系统	发送到企业微信或钉钉	需开发接收端
失败策略	failPipeline: true	测试失败时中断管道	workflowConfig: { ... failPipeline: true }	谨慎使用，避免阻塞

第七章：数据血缘与影响分析

7.1 血缘数据模型

概念名称	说明	注意事项
Lineage（血缘）	描述数据实体（表、字段）之间的依赖关系，表示数据的来源和去向。	支持有向图模型，可表示复杂流转。
Entity Reference	血缘中的节点，代表一个元数据实体（如表、字段）。	使用 FQN 唯一标识。
Edge（边）	表示两个实体之间的依赖关系，带有方向（上游 → 下游）。	可包含额外属性，如转换类型。
Process（过程）	血缘中的中间节点，代表一个数据处理任务（如 ETL Job、SQL 查询）。	可选，用于增强血缘可读性。
Field-level Lineage（字段级血缘）	精确到字段的映射关系，如 A.order_id → B.order_key。	依赖 SQL 解析，精度高。
Table-level Lineage（表级血缘）	表之间的依赖关系，不涉及具体字段。	易于生成，但信息较粗。
Lineage Source	血缘来源，如 Airflow DAG、Query Log、手动输入。	影响血缘可信度和完整性。

7.2 手动与自动血缘采集

采集方式	说明	注意事项
自动采集（Query Log）	解析数据库查询日志（如 BigQuery Audit Log），自动提取表依赖。	需启用日志采集，支持 Snowflake、BigQuery 等。
自动采集（Airflow）	解析 Airflow DAG 中的任务依赖和 SQL 语句，生成血缘。	需集成 Airflow，使用 OpenMetadataOperator。
自动采集（Databricks/Spark）	解析作业日志中的输入输出表信息。	依赖日志格式和解析能力。
手动创建（UI）	在表详情页通过”Add Lineage”按钮手动连接上下游。	适用于无自动采集能力的场景。
手动创建（API）	调用 API 提交血缘关系	用于批量导入或外部系统集成
血缘解析器	内置 SQL 解析器（如 sqlglot），用于从 SQL 提取字段映射。	支持多种方言，但复杂 SQL 可能解析失败。

7.3 展示表级与字段级血缘

功能名称	操作方式	用途	示例	注意事项
表级血缘图	表详情页 > Lineage Tab	查看表的上下游依赖	查看 fact_sales 的来源表	图形化展示，支持缩放
字段级血缘图	点击具体字段 > Field Lineage	查看字段映射路径	customer_name 如何从源系统转换	更精确，用于数据映射审计
展开/折叠节点	点击血缘图中的 + 号	查看深层依赖	从报表展开到原始日志表	避免图形过于复杂
高亮路径	鼠标悬停	查看特定路径的详细信息	高亮从 A 到 C 的路径	增强可读性
血缘方向切换	上游 / 下游 视图	分析影响或溯源	下游视图：修改表会影响哪些？	双向分析更全面
血缘来源标识	图中显示图标或标签	区分自动/手动血缘	显示 “Auto (BigQuery)“	帮助判断可信度

7.4 使用 API 提交血缘关系

方法名称	语法	用途	代码示例	注意事项
创建血缘边	PUT /api/v1/lineage/add	添加两个实体之间的血缘关系	{ "edge": { "fromEntity": { "id": "table-a-id", "type": "table" }, "toEntity": { "id": "table-b-id", "type": "table" } } }	id 为 UUID，需先获取
使用 FQN 提交	POST /api/v1/lineage	推荐方式，使用 FQN 标识实体	{ "description": "ETL Job", "pipeline": { "id": "job-id", "type": "pipeline" }, "upstreamEdges": [ { "fromEntity": { "fqn": "service.db.schema.table_a" }, "toEntity": { "fqn": "service.db.schema.table_b" } } ] }	FQN 更稳定，避免 ID 问题
删除血缘	DELETE /api/v1/lineage/{from}/{to}	移除血缘关系	DELETE /api/v1/lineage/table-a-id/table-b-id	谨慎操作，影响依赖分析
获取血缘信息	GET /api/v1/lineage/entity/{id}	查询实体的血缘	curl http://localhost:8585/api/v1/lineage/entity/{table-id}	返回完整的血缘图
批量提交	循环调用 API 或使用脚本	导入大量血缘数据	使用 Python 脚本读取 CSV 并调用 API	注意 API 速率限制
认证要求	在请求头中添加 Authorization	确保有权限修改血缘	"Authorization": "Bearer ..."	需管理员或数据管理员权限

7.5 血缘在影响分析中的应用

应用场景	说明	注意事项
变更影响分析	当某表结构变更时，通过下游血缘找出所有受影响的报表、模型、管道。	减少变更带来的数据中断风险。
故障溯源	当下游数据出错时，通过上游血缘追溯问题源头表或字段。	缩短排错时间，提高运维效率。
数据下线评估	计划删除某表时，通过血缘确认是否有活跃下游依赖。	避免误删关键数据资产。
合规审计	检查敏感数据（如 PII）的流转路径，确保符合 GDPR 等法规。	血缘是数据治理的关键证据。
数据可信度评估	通过血缘路径长度和来源多样性评估数据质量。	路径越短、来源越可靠，数据越可信。
成本优化	识别长期无下游依赖的”僵尸表”，建议归档或删除。	降低存储和维护成本。
数据产品设计	基于血缘设计数据分层模型（ODS → DWD → DWS）。	确保数据架构清晰合理。

第八章：分类、标签与数据发现

8.1 分类（Classification）与敏感数据标记

概念名称	说明	注意事项
分类（Classification）	用于定义敏感数据的类别，如 PII（个人身份信息）、GDPR、PCI 等合规标准。	分类是标签的”父类”，用于组织和管理标签层级。
敏感数据识别	标记包含敏感信息的字段（如 email、ssn、credit_card），支持自动扫描和手动标注。	自动识别依赖命名模式或正则表达式。
PII（Personally Identifiable Information）	可用于识别个人身份的数据，是常见的分类类型。	需严格管控访问权限，防止泄露。
分类策略（Classification Policy）	定义自动打标规则，如字段名包含 “email” 则标记为 PII.Email。	可基于字段名、数据类型、值样本等条件。
数据脱敏提示	在 UI 中对已分类字段显示警示图标，提醒用户注意隐私。	不提供自动脱敏功能，需配合其他工具。
合规审计支持	分类信息可用于生成合规报告，证明数据治理符合 GDPR、CCPA 等法规。	建议定期审查分类准确性。

8.2 创建和管理标签（Tags）

方法名称	语法	用途	代码示例	注意事项
创建分类（UI）	Settings > Tags > Create Classification	通过界面创建新分类	无	需管理员权限，设置名称、描述、是否敏感
创建标签（UI）	在分类下点击 “Add Tag”	添加子标签	如在 PII 下创建 Email, Phone	支持多级嵌套（PII.Contact.Email）
创建分类（API）	POST /api/v1/classifications	使用 API 创建分类	{ "name": "Finance", "description": "Financial data", "mutability": "mutable" }	mutability 控制标签是否可编辑
创建标签（API）	POST /api/v1/tags	创建具体标签	{ "name": "PII.Email", "classification": { "id": "cls-id-123", "type": "classification" }, "description": "Email address" }	name 必须唯一
删除标签	DELETE /api/v1/tags/{tagFQN}	移除标签	curl -X DELETE http://localhost:8585/api/v1/tags/PII.Email	谨慎操作，可能影响已有元数据
批量管理	导出/导入标签结构	迁移或备份标签体系	支持 JSON 格式	便于跨环境同步

8.3 自动化标签策略

方法名称	语法	用途	代码示例	注意事项
配置自动打标规则	在 ingestion pipeline 中启用 tagger	摄取时自动添加标签	processor: { type: "metadata-tagger", config: { rules: [ { condition: { field: "columnName", pattern: ".email." }, action: { tagFQN: "PII.Email" } } ] } }	规则基于字段名、类型或值
使用正则表达式匹配	pattern: ".ssn."	识别特定命名模式	pattern: "(?i)password|pwd"
基于数据采样	sampleDataScanner	分析字段值内容判断敏感性	enableSampleDataScan: true	可能影响摄取性能
集成外部扫描工具	自定义 Processor	调用外部 DLP 工具（如 Google DLP）	开发自定义 Python 类继承 TaggerProcessor	高级用法，需开发能力
调度周期	与元数据摄取同步执行	定期更新标签	在 Airflow DAG 中配置	确保策略及时生效
覆盖机制	后续规则可覆盖前序标签	处理冲突	需设计优先级	建议明确规则顺序

8.4 基于标签的数据发现与合规控制

功能名称	操作方式	用途	示例	注意事项
按标签搜索	search query: tags:PII.Email	查找所有标记为 Email 的字段	在全局搜索栏输入 tags:PII.Email	支持精确匹配
高级过滤	filter: tags=PII.*	使用通配符查找所有 PII 类型数据	tags=PII.* status:active	用于合规审查
权限控制集成	结合 Policy 强制访问控制	限制非授权用户访问敏感数据	创建策略：仅 DataSteward 可查看 PII 数据	需在 Authorizer 中启用
数据地图生成	导出带标签的元数据清单	制作数据资产目录或合规报告	导出 CSV 包含表、字段、标签列	支持 API 批量导出
敏感数据仪表板	自定义视图展示 PII 分布	监控敏感数据使用情况	按部门、系统统计 PII 字段数量	提升治理透明度
自动告警	检测未标记的疑似敏感字段	主动发现风险	配置规则：name ~ “token” 但无 PII 标签	需结合监控系统

第九章：API 与 SDK 使用

9.1 OpenMetadata REST API 概述

概念名称	说明	注意事项
REST API	OpenMetadata 提供全面的 RESTful API，覆盖所有元数据操作，遵循 OpenAPI 规范。	API 是自动化和集成的核心入口。
API 版本	/api/v1/	当前主要版本，向后兼容性较好
资源端点	/api/v1/tables, /api/v1/services, /api/v1/users 等	每个实体类型有独立端点
请求格式	JSON	请求体必须为 JSON 格式
响应格式	JSON	包含数据和分页信息（如 paging）
分页支持	limit, offset, after	大量数据时分批获取
排序	sortField, sortOrder	按指定字段排序
FQN（Fully Qualified Name）	推荐用于标识实体，如 service.db.schema.table	比 UUID 更稳定，适合脚本使用

9.2 认证与访问 Token 获取

方法名称	语法	用途	代码示例	注意事项
JWT 认证（默认）	无	本地用户登录后自动获取 token	登录 UI 后从浏览器获取	适用于测试
获取 JWT Token（API）	POST /api/v1/system/login	用户名密码登录获取 token	curl -X POST http://localhost:8585/api/v1/system/login -H "Content-Type: application/json" -d '{ "username": "admin", "password": "admin" }'	返回 { "authToken": "Bearer xxx" }
使用 Bearer Token	Authorization: Bearer ...	在请求头中传递 token	-H "Authorization: Bearer eyJhbGciOi..."	所有 API 请求都需要
Token 过期时间	默认 24 小时	需刷新或重新登录	生产环境建议缩短有效期	设置 jwtTokenExpiryMinutes
OAuth2 / SSO Token	通过 SSO 流程获取 Access Token	集成企业认证系统	获取方式取决于提供商	需配置回调 URL
API Key（未来支持）	X-API-Key: key-here	长期有效的机器账户密钥	尚未广泛支持	关注官方进展

9.3 常用 API：创建实体、查询元数据、提交血缘

API 操作	端点与方法	用途	代码示例	注意事项
创建表	POST /api/v1/tables	添加新表元数据	{ "name": "users", "databaseSchema": { "id": "schema-id", "type": "databaseSchema" }, "columns": [ { "name": "id", "dataType": "INT" } ] }	需先存在数据库 Schema
查询表列表	GET /api/v1/tables	获取所有表	curl "http://localhost:8585/api/v1/tables?limit=5"	支持 service、database 过滤
获取表详情	GET /api/v1/tables/{id} 或 {fqn}	查看具体表信息	/api/v1/tables/mysql_service.sales_db.users	推荐使用 FQN
更新表描述	PUT /api/v1/tables/{id}/description	修改表描述	{ "description": "客户主数据表" }	需提供完整描述内容
添加所有者	PUT /api/v1/tables/{id}/owner	设置表所有者	{ "owner": { "id": "user-id", "type": "user" } }	所有者必须已存在
提交血缘关系	PUT /api/v1/lineage/add	添加上下游依赖	{ "edge": { "fromEntity": { "fqn": "service.db.src_table" }, "toEntity": { "fqn": "service.db.target_table" } } }	使用 FQN 更可靠
搜索元数据	GET /api/v1/search/query	全文搜索	?q=user&index=table_search_index	index 可为 table, topic, dashboard 等
获取血缘信息	GET /api/v1/lineage/entity/{id}	查询实体的血缘图	/api/v1/lineage/entity/{table-id}	返回完整的上游/下游边

9.4 Python SDK 安装与初始化

方法名称	语法	用途	代码示例	注意事项
安装 SDK	pip install openmetadata-ingestion[client]	安装包含客户端的 SDK	pip install 'openmetadata-ingestion[client]'	方括号语法安装额外依赖
初始化客户端	导入并创建客户端实例	连接 OpenMetadata 服务	config = OpenMetadataConnection(hostPort="http://localhost:8585") metadata = OpenMetadata(config)	需处理连接异常
使用 JWT 认证	security_config 参数	传递用户名密码	security_config={"jwtToken": "Bearer xxx"} 或 {"username": "admin", "password": "admin"}	推荐使用 token
测试连接	metadata.health_check()	验证客户端是否连通	if metadata.health_check(): print("Connected!")	初始化后调用
设置超时	timeout 配置	防止请求挂起	config = OpenMetadataConnection(..., connectionTimeoutMS=10000)	根据网络状况调整
清理资源	metadata.close()	关闭客户端连接	在退出或批处理后调用	避免资源泄漏

9.5 使用 SDK 进行元数据操作

操作名称	Python 代码示例	用途	注意事项
获取表信息	table = metadata.get_by_name(entity=Table, fqn="mysql_service.sales_db.users")	根据 FQN 查询表	返回 Table 实体对象
创建表	metadata.create_or_update(table_entity)	新增或更新表元数据	需构造完整的 Table 对象
更新表描述	metadata.patch_description(table.fullyQualifiedName.str(), "new desc")	仅更新描述字段	比完整更新更高效
添加标签	metadata.add_tag_to_table(table.fullyQualifiedName, "PII.Email", classification=False)	为表或字段打标	classification=True 表示分类标签
获取血缘	lineage = metadata.get_lineage_by_id(entity=Table, entity_id=table.id)	获取表的血缘图	返回 LineageDetails 对象
提交血缘	metadata.add_lineage(upstream_fqn="src_table", downstream_fqn="target_table")	添加表级血缘	简化 API 调用
搜索表	results = metadata.search_entities(entity_type=Table, filters={"service": "mysql_service"})	条件搜索	支持复杂过滤
批量处理	for table in tables: update_logic(table)	处理多个元数据实体	建议加入错误重试机制
异常处理	try: ... except Exception as e: logger.error(e)	捕获连接或操作异常	网络不稳定时尤为重要

第十章：自定义元数据与扩展

10.1 自定义实体（Custom Entities）

概念名称	说明	注意事项
自定义实体（Custom Entity）	允许用户定义 OpenMetadata 原生模型之外的元数据类型，如 DataProduct、MLModel、APIEndpoint 等。	需通过 JSON Schema 扩展类型系统。
实体注册	在启动时或运行时注册新实体类型	使用 Type Registry API 或配置文件
实体属性	定义实体的字段（attributes），如 name, displayName, description, customProperties 等	必须继承基础元数据模型（Entity）
展示视图	自定义实体在 UI 中的展示方式（列表、详情页）	需开发前端插件或修改 UI 代码
生命周期管理	支持 CRUD 操作、版本控制、软删除	与原生实体行为一致
关联关系	可定义与其他实体的关系（如 belongsTo, uses, produces）	支持双向引用和血缘集成

10.2 添加自定义属性（Custom Attributes）

方法名称	语法	用途	代码示例	注意事项
添加自定义属性（UI）	表/服务详情页 > Custom Properties > Add	为现有实体添加业务字段	如添加 “businessOwner”, “sla” 字段	需有编辑权限
添加自定义属性（API）	PATCH /api/v1/tables/{id}/customProperties	更新实体的自定义属性	{ "customProperties": [ { "name": "costCenter", "value": { "value": "IT-1001", "type": "string" } } ] }	value 类型需匹配定义
定义属性类型	string, integer, boolean, array, object	指定自定义字段的数据类型	"type": "string"	object 类型可用于结构化数据
批量更新	循环调用 API 或使用 SDK	为多个实体设置相同属性	使用 Python 脚本读取 CSV 并更新	注意速率限制
搜索自定义属性	search query: customAttributes.costCenter:IT-1001	在全局搜索中查找	支持精确匹配和过滤	需确保索引已建立
删除属性	PATCH 设置 value 为 null	移除某个自定义属性值	{ "customProperties": [ { "name": "tempField", "value": null } ] }	不会删除属性定义

10.3 扩展类型系统（Type System Extension）

概念名称	说明	注意事项
Type System	OpenMetadata 使用基于 JSON Schema 的类型系统定义所有元数据模型	存储在 /openmetadata/spec 目录下
添加新类型	创建新的 JSON Schema 文件并注册	如 dataProduct.json
继承机制	新类型可继承现有类型（如 entity）	"allOf": [ { "$ref": "#/definitions/entity" } ]
属性定义	在 schema 中定义 required 和 properties 字段	如 "businessOwner": { "type": "string" }
注册类型	通过 API 或重启加载新类型	POST /api/v1/system/types
版本控制	类型变更应考虑向后兼容性	避免破坏现有数据和集成
验证机制	系统在创建实体时自动验证 schema 合规性	确保数据一致性

10.4 插件机制与开发指南

插件类型	开发方式	用途	注意事项
Ingestion Connector	Python 类继承 Source 接口	连接新数据源（如 ClickHouse、Neo4j）	需实现 get_tables_list, yield_table, close 等方法
Processor Plugin	继承 Processor 类	在摄取管道中处理元数据（如打标、过滤）	可用于自动化标签、数据质量检查
Stage Plugin	继承 Stage 类	将元数据暂存到中间存储（如文件、Kafka）	用于调试或异步处理
Sink Plugin	继承 Sink 类	将元数据写入非默认目标（如 Kafka、S3）	支持多目的地分发
UI Plugin（未来）	React 组件开发	扩展 Web UI 功能	当前社区版需修改源码重建
自定义认证插件	实现 Auth Provider 接口	集成新型 SSO 或 MFA 方案	高级安全需求
开发环境搭建	fork 官方仓库，使用 poetry 或 pipenv	本地开发和测试	建议使用 Docker Compose 启动依赖服务
打包与部署	构建 wheel 包或 Docker 镜像	分发插件	可提交 PR 到官方仓库

第十一章：监控、日志与运维

11.1 系统健康检查

检查项	检查方法	正常状态	异常处理
服务可达性	curl http://localhost:8585/health	返回 { "status": "healthy" }	检查进程是否运行
数据库连接	查看日志中 metadata-store 连接状态	显示 “Connected to MySQL”	验证数据库地址、凭证、网络
ElasticSearch 连接	查看日志中 elasticsearch 连接信息	”Successfully connected to ES”	确保 ES 服务正常，集群健康
缓存服务（Redis）	若启用，检查 Redis 连通性	无连接错误日志	Redis 用于缓存，断开可能影响性能
Airflow 集成状态	访问 Airflow UI 或 DAG 列表	显示 OpenMetadata 相关 DAG	检查 airflow.cfg 和 connection
内部服务状态	GET /api/v1/system/status	返回各组件状态（db, es, auth）	用于全面诊断
端口占用	netstat -an | grep 8585	端口被监听	解决端口冲突

11.2 日志查看与问题排查

日志来源	路径/命令	用途	常见问题与排查
OpenMetadata Server 日志	docker logs openmetadata-server	查看服务启动、API 请求、错误	Connection refused → 检查依赖服务
Ingestion Pipeline 日志	日志输出或 Airflow Task Logs	摄取任务执行详情	Table not found → 检查数据库权限
Airflow Scheduler 日志	docker logs airflow-scheduler	DAG 解析与调度	DAG Import Error → 检查 Python 路径
Airflow Worker 日志	docker logs airflow-worker	任务实际执行日志	ModuleNotFoundError → 缺少依赖
Elasticsearch 日志	docker logs elasticsearch	搜索索引状态	ClusterBlockException → 磁盘满或内存不足
MySQL/Metadata DB 日志	docker logs mysql	元数据存储访问	Too many connections → 调整连接池
关键错误模式	ERROR, Exception, Failed	快速定位问题	使用 grep 过滤
启用 DEBUG 日志	修改 logLevel: DEBUG in config	获取更详细信息	生产环境慎用，日志量大

11.3 监控指标（Prometheus 集成）

指标名称	说明	用途	查询示例（PromQL）
jvm_memory_used_bytes	JVM 内存使用量	监控内存泄漏或不足	jvm_memory_used_bytes{area="heap"}
http_server_requests_seconds_count	HTTP 请求总数	衡量 API 负载	rate(http_server_requests_seconds_count[5m])
http_server_requests_seconds_max	单次请求最大耗时	发现慢请求	http_server_requests_seconds_max > 5
process_cpu_usage	CPU 使用率	监控资源消耗	process_cpu_usage > 0.8
metadata_ingestion_status	摄取任务状态（0=失败, 1=成功）	跟踪数据新鲜度	metadata_ingestion_status == 0
elasticsearch_index_docs	ES 索引文档数	验证元数据同步完整性	elasticsearch_index_docs{index="table_search_index"}
kafka_consumer_lag	Kafka 消费延迟（若使用）	监控消息积压	kafka_consumer_lag > 1000
up (通用)	服务存活状态	基础可用性监控	up{job="openmetadata"} == 0

配置方法：

• 在 openmetadata.yaml 中启用 metrics.exporter: prometheus
• 暴露端口 8080 并配置 Prometheus scrape job
• 使用 Grafana 导入预设 Dashboard（官方提供模板）

11.4 备份与恢复策略

操作类型	方法	工具/命令	注意事项
元数据备份	备份 MySQL/MariaDB 数据库	mysqldump -u user -p openmetadata_db > backup.sql	核心数据，必须定期备份
搜索索引备份	ElasticSearch 快照	Create Snapshot API	确保配置了共享存储仓库
配置文件备份	备份 openmetadata.yaml、ingestion 配置	cp *.yaml /backup/	包括认证、连接器等关键配置
整机镜像备份	Docker Volume 或 VM 快照	docker volume ls, docker commit	快速恢复，但占用空间大
备份频率	每日增量 + 每周全量	cron 定时任务	根据数据变更频率调整
恢复步骤	1. 停止服务 2. 恢复数据库 3. 恢复 ES 索引（可选） 4. 启动服务	docker-compose down/up	恢复后建议重新摄取验证
恢复验证	检查 UI 是否正常，搜索关键表	登录 Web UI	确认元数据完整性和可访问性
灾备方案	异地备份或云存储	AWS S3, GCS	防止本地灾难导致数据丢失

注意事项：

• 避免在摄取任务运行时备份数据库
• 测试恢复流程
• 加密敏感备份文件

第十二章：集成与生态

12.1 与 Apache Atlas 迁移对比

对比维度	OpenMetadata	Apache Atlas	说明
架构设计	微服务架构，模块解耦，支持插件化扩展	基于 Hadoop 生态，强依赖 HBase、Kafka、Solr	OpenMetadata 架构更现代，部署更轻量
数据源支持	广泛支持关系型、NoSQL、消息队列、云数据仓库（Snowflake、BigQuery 等）	主要面向 Hadoop 生态（Hive、HBase、Storm）	OpenMetadata 对云原生和现代数据栈支持更好
元数据覆盖	表、字段、管道、指标、测试、用户、团队、权限、血缘、文档等	以数据资产为核心，支持分类、策略、血缘	OpenMetadata 覆盖更全面，集成数据质量、BI 等
用户界面	现代化 Web UI，交互友好，支持搜索、血缘图、数据质量看板	UI 较基础，功能集中在管理后台	OpenMetadata 用户体验更佳
API 与 SDK	提供完善的 REST API 和 Python SDK，易于集成	REST API 存在，但 SDK 和文档较弱	OpenMetadata 更适合自动化和二次开发
数据质量	内置数据质量模块，支持测试用例、断言、CI/CD 集成	无内置数据质量功能，需外部集成	OpenMetadata 原生支持是显著优势
血缘采集	支持自动（SQL 解析、Query Log）和手动血缘，字段级精度高	支持血缘，但依赖 Hook 机制，配置复杂	OpenMetadata 血缘更易用、精度更高
社区与生态	活跃增长中，与 Airflow、Superset、Great Expectations 深度集成	Hadoop 生态成熟，但增长放缓	OpenMetadata 更贴近现代数据栈
迁移路径	提供导入工具或通过 API 迁移分类、实体、血缘	可作为数据源被 OpenMetadata 摄取	建议逐步迁移，先同步元数据再切换

12.2 与 DataHub 对比

对比维度	OpenMetadata	DataHub	说明
开源协议	Apache 2.0	商业源码可用，核心功能开源	OpenMetadata 完全开源，无功能限制
部署复杂度	中等，依赖 MySQL、Elasticsearch、Airflow（可选）	较高，基于 Kafka、Kafka Connect、ZooKeeper 等	OpenMetadata 依赖更少，部署更简单
默认功能	内置数据质量、数据测试、CI/CD、自动化标签	需通过插件或外部工具（如 DataHub CLI、Acryl Data）实现	OpenMetadata”开箱即用”能力更强
数据质量	原生集成，支持测试用例、断言、结果可视化	需集成外部工具（如 Great Expectations），配置复杂	OpenMetadata 在数据质量方面集成更紧密
血缘支持	强，支持自动解析 SQL、Query Log、Airflow DAG	强，通过 Kafka 消息自动捕获	两者血缘能力接近，OpenMetadata UI 更直观
BI 集成	原生支持 Superset、Tableau、Looker 元数据摄取	支持 Power BI、Tableau、Looker 等	两者在 BI 集成上均表现良好
搜索与发现	基于 Elasticsearch，支持全文搜索、标签过滤、自定义属性搜索	基于 Elasticsearch，搜索功能强大	功能相似，体验接近
权限模型	RBAC（基于角色）和 ABAC（基于属性）结合，支持细粒度权限	RBAC，支持资源级权限控制	OpenMetadata 权限模型更灵活
社区与文档	文档清晰，API 和 SDK 文档完整，社区活跃	文档丰富，企业支持强（Acryl Data）	OpenMetadata 对自建团队更友好
适用场景	中小企业、希望快速落地数据治理的团队	大型企业、已有 Kafka 生态、需要高扩展性的场景	根据技术栈和需求选择

12.3 与 Airflow 集成实现元数据自动上报

集成方式	配置方法	用途	注意事项
Airflow 作为数据源	在 OpenMetadata 中创建 Airflow Service，配置 API 端点和认证	自动摄取 DAG、任务、调度信息	需 Airflow 开启 RBAC 和 API
自动血缘生成	OpenMetadata 解析 DAG 中的 task_sql 或上下游表名	自动生成任务级血缘（上游表 → DAG → 下游表）	建议在任务中明确指定输入输出表
使用 OpenMetadataOperator	在 DAG 中调用 Workflow.execute()	在任务中主动上报元数据或执行测试	可用于自定义逻辑
Profiler & Data Quality	在 ingestion 配置中启用 profiler 和 dataQuality	自动运行数据探查和测试	生成的测试结果可在 UI 查看
事件监听（Event Listener）	配置 Airflow 的 on_success_callback / on_failure_callback	任务成功/失败时通知 OpenMetadata	可用于更新状态或发送告警
DAG 示例	创建 DAG，任务包含 SQL 操作表 sales → report	摄取后自动建立 sales → report 血缘	命名规范有助于解析
认证配置	在 Airflow Connection 中设置 OpenMetadata 的 JWT Token	确保 Airflow 能调用 OM API	Token 需有足够权限
优势	无需代码修改，自动获取调度元数据和血缘	提升元数据覆盖率和准确性	是推荐的生产集成方式

12.4 与 Great Expectations 集成做数据质量

集成方式	配置方法	用途	注意事项
作为数据质量源	在 OpenMetadata ingestion 配置中设置 sourceType: GreatExpectations	从 GX 的 Checkpoint 结果中读取测试结果	需 GX 结果存储在 S3、GCS 或本地
结果同步	OpenMetadata 定期拉取 GX 的 validation_results	将 GX 测试结果展示在 OM UI 的 Tests 标签页	支持通过/失败状态和详情
统一视图	在表详情页查看来自 GX 和 OM 原生测试的结果	集中管理所有数据质量证据	便于审计和监控
配置示例	processor: { type: "great-expectations", config: { resultUrl: "s3://bucket/validation_results/" } }	指定 GX 结果存储位置	确保 OM 有读取权限
优势	复用现有 GX 测试，避免重复定义	保护已有投资，统一展示层	适合已使用 GX 的团队
局限性	仅同步结果，不支持在 OM 中编辑 GX Expectations	GX 仍需独立维护	建议将简单测试迁移到 OM 原生测试
CI/CD 集成	在 CI 流水线中运行 GX 测试，结果由 OM 摄取	实现数据质量门禁	结合 OM 的告警机制

12.5 与 Superset、Tableau 等 BI 工具集成

BI 工具	集成方式	用途	注意事项
Apache Superset	创建 Superset Service，配置 API 或数据库连接	摄取 Dashboard、Chart、Query、Owner 信息	支持血缘：Table → Query → Chart → Dashboard
Tableau	创建 Tableau Service，配置 Server URL、Site、认证	摄取 Workbook、View、Datasource、Owner	需 Tableau Server 或 Online
Looker	创建 Looker Service，配置 API URL 和 Client ID/Secret	摄取 Look、Dashboard、Model、Explore	支持 Looker 3.1+
Power BI	创建 Power BI Service，配置 Tenant ID、Client ID 等	摄取 Report、Dataset、Dashboard、Owner	需 Azure AD 认证
Metabase	创建 Metabase Service，配置 URL 和 API Key	摄取 Question、Dashboard	支持 Metabase 0.40+

集成内容：

• BI 实体元数据（名称、描述、Owner）→ 实现端到端数据溯源，帮助理解数据如何被消费
• 血缘关系（数据源表 → BI 对象）→ 在表详情页的 Lineage 图中显示 BI 对象
• 使用统计（访问次数、收藏）→ 查看数据如何被下游报表使用，增强数据影响分析能力

权限同步： 同步 BI 中的 Owner 和团队信息，统一身份视图（需确保用户在 OM 中已存在）

优势： 打破 BI 工具孤岛，将分析资产纳入统一元数据平台，提升数据发现和治理能力，是数据目录的关键组成部分