4.2 连接器实操：从MySQL到搜索可见
4.2 连接器实操：从MySQL到搜索可见
本节摘要：本节用一次完整的 MySQL 接入演示官方连接器的标准操作：写配置、跑摄入、验结果，并把每一步的输出掰开解读——报错长什么样、成功长什么样、到搜索可见要经过几道工序。所有命令与配置可直接搬到你的测试环境。本节是 4.1 模式决策的落地示范，也是 4.3 自定义开发与 4.4 排错实录的基准参照：标准路径都没走通之前，不要急着排错。
准备：理清一次摄入的参与方
动手前先明确四个参与方：源库 MySQL（元数据的产地）、摄入执行器（干活的客户端，可以在任何机器上运行）、GMS（平台写入入口）、前端（验证结果的窗口）。摄入执行器与平台之间的耦合点只有一个——GMS 的服务地址；与源库之间的耦合点也只有一个——连接凭证。这个极简依赖关系意味着：接入失败时，嫌疑范围通常就在这两条连接与配置本身。
各参与方的协作时序如下：执行器读配置后连源库拉取元数据，逐批转换成平台模型，再批量推送给 GMS；GMS 逐批确认，最后执行器汇总输出报告。
第一步：安装摄入工具
摄入执行器是独立的命令行程序，与平台本体分离部署。建议安装在固定的运维机或容器里，不要装在个人电脑上——摄入任务迟早要定时化，从第一天就把它当成服务对待。安装完成后验证版本：官方框架的命令行入口提供版本查询子命令，输出框架版本号即就绪。若后续要接入 MySQL 之外的源（Kafka、BI 工具等），对应的连接器插件按需追加安装，缺插件时的报错很直白：提示找不到对应来源类型，照提示补装即可。
第二步：写摄入配置
配置文件是摄入的灵魂，一份最小可用的 MySQL 配置如下：
source: type: mysql config: host_uri: "10.0.2.15:3306" username: "meta_reader" password: "${MYSQL_META_PWD}" database_pattern: allow: ["sales", "crm"] table_pattern: deny: ["^tmp_.*", "^bak_.*"] profile_patterns: denyl: [] sink: type: datahub-rest config: server: "http://datahub-gms:8080" token: "${DATAHUB_TOKEN}"
逐项拆解。source.type 声明源类型，决定了框架加载哪个连接器插件。host_uri 加账号凭证完成第一条连接——凭证用环境变量占位符注入，明文密码进配置文件是审计红线。database_pattern 与 table_pattern 是覆盖面控制：allow 收白名单，deny 排除临时表与备份表——tmp 与 bak 开头的表占元数据的两三成却毫无治理价值，第一天的配置就该把它们排除。sink.type 声明出口走 REST 直推 GMS，token 是平台的访问凭证（认证体系见 6.3 节）。
一个容易忽略的坑：模式过滤支持多个来源的组合，当你的正则不生效时，先确认写的是列表结构——把正则串直接当字符串赋值，框架不报错但不匹配，表现为"该进来的没进来"。
第三步：执行与读报告
执行摄入只需一条命令，把配置文件路径作为参数交给命令行入口。运行结束后终端输出一份报告，重点是最后几行的统计：分析了多少实体、成功多少、失败多少、耗时多少。读报告是必做动作：失败计数为零才算接入成功；失败不为零时，报告会附每条失败的错误摘要，这正是 4.4 排错树的原材料。
第一次接入建议加调试开关重跑一次：日志会打印每批提交的实体数量与 GMS 的响应码。对照 4.2 开头的时序图看日志，你能清楚看到"拉取、转换、提交"三段各自的耗时——后续性能调优（比如全量接入上万张表太慢）时，先看哪一段占大头：拉取慢查源库负载，提交慢查 GMS 容量。
第四步：到界面上验证
验证分三层，一层比一层严格。存在性：搜索框输入表名，结果里出现即通过。完整性：点开详情页，字段清单、类型、注释齐全；负责人为空是正常的——所有权靠治理流程认领，不靠连接器。关联性：如果同时接了调度系统的血缘，详情页血缘标签页应出现上下游；只有单一源接入时血缘标签为空，这不是故障。
三层全过后，把这个接入固化为定时任务。用系统定时器或调度平台把摄入命令按天编排，再按 4.1 的对账思路加一个最简监控：定时任务退出码非零时告警。到这一步，一个数据源的接入才算工程化完成。
💡 把每个数据源的接入配置与验证标准存进版本库，配置文件带注释说明覆盖面取舍的原因。半年后新同事接手时，这些注释能省掉一轮"为什么当时不接这个库"的考古。
三个初次接入的高频追问
问：报告全绿，但表描述是空的？ 不是故障。结构快照只同步源系统里"确实存在"的注释，源库建表时没写注释，平台上自然没有。补描述是治理动作不是接入动作——按 5.3 的方式组织认领与补全，或推动源库建表规范的落地。
问：时间字段显示的日期差了八小时？ 时区问题。摄入框架按配置的时区解释源系统返回的时间戳，配置缺省值与源库时区不一致时，分区的产出时间、任务的运行时间都会整体偏移。在摄入配置里显式声明与源系统一致的时区，别依赖默认值。
问：能只接部分字段吗？ 连接器层面通常按表整表接入，字段级的收窄靠 column pattern 过滤配置实现。但要想清楚动机：如果是为了隐藏敏感字段，正确的工具是 6.3 的访问策略而不是不接入——不接进去的字段在血缘与合规视图里是盲区，审计时会反而说不清。
扩展到其他源：同一套心智
MySQL 演练的流程是所有 pull 型接入的通用模板：装插件、写 source、写 sink、执行、读报告、三层验证。换成 PostgreSQL 改 source.type 与连接参数；换成 Kafka 换成主题清单拉取；换成 BI 工具拉取的是看板与图表及其依赖的数据集——正是报表层血缘的来源。配置结构完全同构，学会一个等于学会一类。真正的分水岭在两类地方：没有现成连接器的私有系统，转 4.3 自研；连得上但数据不对、血缘缺边，转 4.4 排错。
本节要点回顾
- 四参与方：源库、执行器、GMS、前端；耦合点只有源库凭证与 GMS 地址，排错先查这两条线。
- 配置三要点：凭证环境变量注入、模式过滤收白排 tmp、过滤正则必须写成列表结构。
- 报告必读：失败计数清零才算成功，失败摘要就是排错原料；调试日志对照时序图看三段耗时。
- 验证三层：存在性搜得到、完整性字段齐、关联性血缘现；单人单源血缘为空是正常。
- 固化收尾：定时化、非零退出告警、配置进版本库，工程化完成才算接入结束。
标准路径走通了。如果源系统没有现成连接器怎么办——下一节打开连接器的开发框架，自己写一个。