企业官网建设流程全解析

OpenMetadata MySQL 连接器完整指南：权限配置、四种认证方式与元数据/血缘/用量摄取实战

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata

本篇技术指南以 OpenMetadata 官方 MySQL 连接器文档为主体，结合仓库源码（连接处理、摄取实现、JSON Schema 与集成测试）进行纵深解读，覆盖从最小权限账号创建、INFORMATION_SCHEMA访问授权，到 Lineage & Usage 所需的general_log/slow_log配置、Profiler 与数据质量测试的权限准备，以及连接详情中每个配置项的含义与取值建议。读完本文，你将掌握在 OpenMetadata 中正确创建并调优 MySQL 数据库服务的完整链路，并能对照源码理解底层认证策略与连接诊断机制。

一、连接器概述与支持范围

MySQL 连接器用于将 MySQL 实例中的数据库、Schema、表、视图、存储过程等元数据抽取到 OpenMetadata 的 Database Service 层级中。从 服务规格定义 可以看到，该连接器由一个完整的ServiceSpec组织：

• 元数据摄取：MysqlSource（metadata.py）
• 血缘摄取：MysqlLineageSource（lineage.py）
• 用量摄取：MysqlUsageSource（usage.py）
• 连接管理：MySQLConnection（connection.py）

版本要求：OpenMetadata 支持 MySQL 版本8.0.0及以上。连接驱动使用 SQLAlchemy 的mysql+pymysqlscheme（由 mysqlConnection.json 中的mySQLScheme枚举固定）。

二、元数据摄取的最小权限要求

要抽取元数据，连接所使用的用户必须能够访问INFORMATION_SCHEMA。默认情况下，MySQL 用户只能看到INFORMATION_SCHEMA中与其访问权限对应的对象行，因此需要显式授权。以下是官方推荐的授权 SQL：

-- 创建用户。若省略 <hostName>，则默认使用 '%'（允许任意主机连接） -- 更详细的语法参见 MySQL 官方 CREATE USER 文档（8.0 参考手册） CREATE USER '<username>'[@'<hostName>'] IDENTIFIED BY '<password>'; -- 授予对某个数据库的 SELECT 权限 GRANT SELECT ON world.* TO '<username>'; -- 授予对某个数据库的 SELECT 权限 GRANT SELECT ON world.* TO '<username>'; -- 授予对某个具体对象的 SELECT 权限 GRANT SELECT ON world.hello TO '<username>';

说明：原文档中第二条GRANT SELECT ON world.* TO '<username>';与第一条重复，实际使用中按需保留一条即可；按库授权（db.*）与按对象授权（db.table）可组合使用，实现从粗粒度到细粒度的权限控制。

在源码层面，连接器测试连接时会通过 connection.py 中的MySQLChecks依次执行check_access（ping）、get_schemas、get_tables、get_views、get_queries五项检查，其中get_tables/get_views会跳过information_schema、performance_schema、mysql、sys这四个 MySQL 8 系统库（见SYSTEM_SCHEMAS常量）。若用户权限不足，测试连接会给出对应错误码诊断（详见后文"连接诊断"小节）。

三、Lineage（血缘）与 Usage（用量）摄取配置

要抽取血缘与用量，需要开启 MySQL 的查询日志，并且连接用户需要对mysql.general_log表拥有 SELECT 权限：

-- 开启日志记录 SET GLOBAL general_log='ON'; SET GLOBAL log_output='table'; -- 授予对日志表的 SELECT 权限 GRANT SELECT ON mysql.general_log TO '<username>'@'<host>';

启用后，usage.py 中的MysqlUsageSource与血缘源MysqlLineageSource会通过 queries.py 中定义的MYSQL_SQL_STATEMENT从{query_history_table}（默认mysql.general_log）查询command_type = 'Query'且位于start_time/end_time区间内的语句，并按event_time desc排序、以resultLimit限制返回条数。查询会过滤掉 OpenMetadata 自身与 dbt 写入的带注释语句（argument NOT LIKE '/* {"app": "OpenMetadata", ...} */%'），避免自指污染。

使用慢日志（slow log）作为日志来源

连接配置中提供两个与查询历史相关的开关（定义于 mysqlConnection.json）：

• useSlowLogs（布尔值，默认false）：置为true时改用慢日志提取血缘与用量；
• queryHistoryTable（字符串）：自定义查询历史表名，设置后将覆盖默认的mysql.general_log（或启用慢日志时的mysql.slow_log）。自定义表必须提供与所选日志路径兼容的列。

对应实现位于 query_parser.py：useSlowLogs为真时使用MYSQL_SQL_STATEMENT_SLOW_LOGS（读取sql_text列），否则使用MYSQL_SQL_STATEMENT（读取argument列）；同时支持通过filterCondition追加额外过滤条件。

四、Profiler 与数据质量（Data Quality）权限准备

执行 Profiler 工作流或数据质量测试时，需要用户具备以下权限：

• 对将要执行 Profiler/测试的表或 Schema 拥有SELECT权限；
• 允许查看数据库中所有对象的tables信息。

即与元数据摄取的权限要求一致（至少INFORMATION_SCHEMA访问 + 目标对象SELECT），但范围应扩大到所有需要做数据画像和质量断言的对象。具体工作流搭建可参考仓库中的数据质量与 Profiler 相关实现（如 profiler 模块 与 data_quality 模块）。

五、连接详情（Connection Details）逐项解读

以下参数与官方文档的$$section定义一一对应，均可在连接服务的 UI 表单或 YAML 配置中设置。

Scheme

SQLAlchemy 驱动 scheme 选项。当前仅支持mysql+pymysql（默认值）。若不确定，直接使用默认值即可。

Username

连接 MySQL 的用户名。该用户需能访问INFORMATION_SCHEMA以抽取元数据；其他工作流（血缘、用量、Profiler、数据质量）可能需要额外权限，参见上文各节。

Auth Config（authType）

认证配置支持以下类型（对应 mysqlConnection.json 中authType的oneOf）：

• Basic Auth：使用密码认证；
• IAM based Auth：使用 AWS IAM 认证连接 AWS 相关服务（如 RDS）；
• Azure Based Auth：使用 Azure AD 认证连接 Azure 相关服务；
• GCP CloudSQL Config（源码已支持）：通过 Cloud SQL Python Connector 建立安全隧道连接 GCP Cloud SQL 实例。

密码（Basic Auth 下的 Password）

连接 MySQL 的密码。

IAM 认证配置（IAM Auth Config）

使用 IAM 认证时，官方要求额外添加如下连接参数以启用 SSL：

"ssl": {"ssl-mode": "allow"}

即写入 Connection Arguments。各字段说明如下：

• AWS Access Key ID：访问 AWS 时用于标识身份的安全凭证之一，形如AKIAIOSFODNN7EXAMPLE。访问密钥由两部分组成：Access Key ID 与 Secret Access Key，二者必须同时使用才能完成认证；
• AWS Secret Access Key：与 Access Key ID 配对的密钥，形如wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY；
• AWS Region：AWS 在每个地理区域独立部署数据中心，需要指定目标服务所在区域。注意：Region 是配置连接时唯一必填的 AWS 参数，其余 AWS 配置可通过编程方式从凭证链中解析；
• AWS Session Token：使用临时凭证访问服务时提供。此时除 Access Key ID 与 Secret Access Key 外，还需附带 Session Token；
• Endpoint URL：以编程方式访问 AWS 服务时使用的入口 URL。AWS SDK 与 CLI 默认使用各区域的标准端点，也可为 API 请求指定备用端点；
• Profile Name：AWS CLI 命名配置文件。若希望使用default以外的配置文件，在此填写名称；
• Assume Role ARN：跨账户或账户内角色切换时使用的目标角色 ARN。使用AssumeRole的用户需由账户管理员附加允许调用AssumeRole的策略；若需角色扮演，此项必填；
• Assume Role Session Name：假定角色会话的标识符，用于在多个主体以不同原因扮演同一角色时唯一区分会话。默认值为OpenMetadataSession；
• Assume Role Source Identity：调用AssumeRole操作的主体所指定的源身份，可用于在 CloudTrail 日志中追溯是谁以该角色执行了操作；
• Bucket Name：数据湖中用于组织与存储对象的唯一标识，类似"文件夹名"但服务于对象存储；
• Prefix：数据路径的前缀部分，用于标识数据的来源或归属，帮助在容器内组织与分类数据。

从源码看，IAM 认证由 connection.py 中的_IamStrategy实现：它基于hostPort解析出主机与端口，使用RdsIamAuthTokenManager生成 RDS IAM 令牌，并通过 SQLAlchemy 的do_connect事件监听器在每次新建连接时注入最新令牌——这是因为 IAM 令牌有效期约 15 分钟，长时运行的摄取任务不能复用过期令牌。同时，RDS IAM 要求 TLS，策略会自动为未显式配置ssl的连接注入{"check_hostname": True}。

Azure 认证配置（Azure Auth Config）

• Client ID：服务账号的唯一标识。在服务账号密钥文件中查找client_id键对应的值；
• Client Secret：客户端密钥。获取步骤：登录 Azure 门户 → 搜索App registrations并进入 → 选择本次连接使用的 Azure AD 应用 →Manage下选择Certificates & secrets→Client secrets下选择New client secret→ 在弹窗中填写描述并选择过期时间后Add→ 在Client secrets区复制新建密钥Value列的内容；
• Tenant ID：租户 ID。获取步骤：登录 Azure 门户 →App registrations→ 选择使用的 Azure AD 应用 → 在Overview区复制Directory (tenant) ID；
• Storage Account Name：存储账号名称；
• Key Vault Name：密钥保管库名称；
• Scopes：为让 OpenMetadata 使用 Azure AD 应用调用认证 API，需要添加 scope：登录 Azure 门户 →App registrations→ 选择使用的应用 → 在Expose an API区复制Application ID URI→ 确保 URI 以/.default结尾（否则手动追加）。

源码实现中，_AzureStrategy通过get_azure_access_token获取访问令牌，并将该令牌作为密码注入一个深拷贝的连接配置中（connection.py），因此不会改动调用方持有的原始service_connection，且每次构建引擎都会获取新令牌，规避令牌过期问题。

Host Port

MySQL 实例的主机与端口，格式为hostname:port，例如localhost:3306。

注意：若 OpenMetadata 摄取服务运行在 Docker 中而目标 MySQL 部署在宿主机localhost上，则应使用host.docker.internal:3306作为取值。

另外，当使用 GCP CloudSQL 认证时，hostPort需填写实例连接名，格式为project_id:region:instance_name（见 mysqlConnection.json 中hostPort的描述）。

Database Name

OpenMetadata 中 Database Service 的层级结构为：

Database Service > Database > Schema > Table

MySQL 本身没有"Database Service 之下的数据库"这一层概念。若希望数据展示在default之外命名的数据库下，可在此字段指定名称。

Database Schema

可选参数。设置后，元数据读取将被限制为仅读取该值对应的单个数据库（Schema）；留空时 OpenMetadata 会扫描所有数据库。

SSL 相关参数

• SSL CA：用于 SSL 校验的 CA 证书（对应驱动参数ssl_ca）；
• SSL Certificate：用于客户端认证的 SSL 证书（ssl_cert）；
• SSL Key：与该 SSL 证书关联的私钥（ssl_key）。

在 JSON Schema 中，SSL 配置通过sslConfig引用 verifySSLConfig.json 的sslConfig定义统一管理。

Connection Options

附加连接选项，用于构建发送给服务端的连接 URL（如驱动级参数）。

Connection Arguments

附加连接参数，例如安全或协议配置，会在连接时发送给服务。典型的用法即上文 IAM 认证所需的"ssl": {"ssl-mode": "allow"}。

过滤模式（Filter Patterns）

连接器支持四类基于正则的过滤模式，includes列表匹配即包含、excludes列表匹配即排除：

• Default Database Filter Pattern（databaseFilterPattern）：正则匹配数据库名，仅包含/排除匹配的数据库；
• Default Schema Filter Pattern（schemaFilterPattern）：正则匹配 Schema 名。注意其默认值为includes: []、excludes: ["^information_schema$", "^performance_schema$"]，即默认排除两个系统库（见 mysqlConnection.json）；
• Default Table Filter Pattern（tableFilterPattern）：正则匹配表名；
• Default Stored Procedure Filter Pattern（storedProcedureFilterPattern）：正则匹配存储过程名。

需要说明的是，在摄取实现中（metadata.py），存储过程抽取由get_stored_procedures通过MYSQL_GET_ROUTINES查询information_schema.ROUTINES完成（仅当includeStoredProcedures开启），并会逐一应用is_stored_procedure_filtered过滤；抽取到的存储过程/函数代码会被包装为CreateStoredProcedureRequest，映射其语言与类型（见STORED_PROC_LANGUAGE_MAP、STORED_PROC_TYPE_MAP）。

六、源码级实现原理：认证策略与连接构建

EngineStrategy 模式

connection.py 中MySQLConnection._engine_strategy()根据authType分发到四种策略：

其中 CloudSQL 策略要求安装cloud-sql-python-connector（pip install 'cloud-sql-python-connector[pymysql]>=1.0.0,<2.0.0'），并在close()/__del__中释放连接器，保证失败路径不留存活资源。

连接诊断：MySQL 错误码映射

MYSQL_ERRORS将常见 MySQL 8 错误码映射为可读的诊断信息，测试连接失败时直接提示用户：

这一映射说明：多数连接失败的本质是权限或网络问题，测试连接功能会把这些错误翻译成可直接执行的修复建议。

七、连接验证与测试

仓库提供了集成测试 test_mysql_connection.py，展示了编程方式构建连接的最小样例：

from metadata.generated.schema.entity.services.connections.database.common.basicAuth import ( BasicAuth, ) from metadata.generated.schema.entity.services.connections.database.mysqlConnection import ( MysqlConnection, ) from metadata.ingestion.source.connections import get_connection, get_test_connection_fn service_connection = MysqlConnection( username=mysql_container.username, authType=BasicAuth(password=mysql_container.password), hostPort=f"localhost:{mysql_container.get_exposed_port(3306)}", ) engine = get_connection(service_connection) _test_connection_fn = get_test_connection_fn(service_connection) _test_connection_fn(metadata)

可见连接对象只需hostPort与username两个必填字段（authType为 Basic 时补充password），这也是 mysqlConnection.json 中required数组的约束。测试连接函数会依次执行MySQLChecks中的 ping、列 Schema、列表、列视图、查询历史可访问性五项检查。

八、实战检查清单

在 OpenMetadata 中成功配置 MySQL 服务，可按以下顺序自检：

1. 版本：确认 MySQL ≥ 8.0.0；
2. 元数据权限：连接用户可访问INFORMATION_SCHEMA，并对目标库/对象拥有SELECT；
3. 血缘与用量（如需要）：开启SET GLOBAL general_log='ON'; SET GLOBAL log_output='table';，并授予mysql.general_log（或改用useSlowLogs+mysql.slow_log）的 SELECT 权限；
4. Profiler / 数据质量（如需要）：对被测表/Schema 授予SELECT，并确保能查看tables信息；
5. 认证方式：按部署环境选择 Basic、AWS IAM（记得配置"ssl": {"ssl-mode": "allow"}）、Azure AD 或 GCP CloudSQL；
6. 主机与端口：Docker 摄取访问宿主机服务时使用host.docker.internal:3306；
7. 过滤模式：利用四类 Filter Pattern 控制摄取范围，默认已排除information_schema与performance_schema；
8. 测试连接：运行 Test Connection，依据错误码诊断信息逐项修复。

完成上述配置后，即可通过元数据摄取 Pipeline 将 MySQL 中的库表结构、视图、存储过程纳入 OpenMetadata 的统一数据目录，并在此基础上开启 Profiler、数据质量、血缘与用量分析，为数据治理与 AI 上下文构建提供可信的基础。

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata