企业官网建设流程全解析

接到这个任务的时候，我第一反应是确认Kettle的HBase插件还活着。项目标题写得很简洁——“kettle MongoDB数据迁移至Hbase”，但做过这类迁移的人都知道，真正的工程量不在“Kettle”三个字上，而在MongoDB里的数据长什么样、HBase那边表怎么设计、两边的类型怎么对齐、写入速度能不能让人接受。这篇文章把我整个实操过程、踩过的坑、最后沉淀下来的方案全部拆开，给正准备做类似迁移的朋友一个可以直接抄作业的参考。

适合看这篇内容的人，大致有这三类：一是公司有现成Kettle环境、临时接到MongoDB迁移到HBase任务的数据工程师；二是正在选型批量数据迁移方案、想了解Kettle到底行不行的技术负责人；三是想搞清楚HBase Rowkey设计、批量写入优化这些细节的进阶学习者。我会从方案选型、环境准备、转换配置、性能调优、问题排查五个层面完整展开，全程用实际遇到的情况说话。

1. 项目背景与方案选型思路

1.1 为什么要把数据从MongoDB搬到HBase

我遇到这个项目的起因，是某数据平台的核心业务库开始撑不住了。MongoDB本身是个很优秀的文档数据库，读写性能、开发效率都没得说，但随着单表数据量跨过亿级，几个比较难受的问题接踵而至：全表分析查询慢、聚合管道经常把CPU打满、横向扩容之后数据分布不均导致某些分片持续热点，更重要的是业务方开始产生大量按Key范围扫描和OLAP类需求，MongoDB并不是这类场景的最佳选择。

而HBase的优势正好互补。它是列式存储，天然支持海量结构化数据，按Rowkey做随机读写和范围扫描都很快，扩展性也好。于是需求就变成了：把MongoDB里积累的历史业务数据，迁移到HBase上，作为后续实时查询和批量分析的基础数据层。

有一点要提前说清楚：这不只是一个搬运数据的活儿。MongoDB是文档模型，HBase是宽表模型，两者之间有模型转换、字段映射、Rowkey设计、写入策略等多层问题，任何一个环节想不清楚，后面都会在性能或数据质量上翻车。

1.2 为什么选Kettle而不是写脚本或上Spark

确定要从MongoDB往HBase导数据之后，团队内部其实有过一轮方案讨论。当时摆在桌上的选择大概有三个：自己写Java/Python脚本、上Spark批量任务、用Kettle（PDI）做ETL。

写脚本看起来最自由，但实际评估下来有个大问题：团队当时没有一套成熟的调度和重跑机制，脚本写出来容易，跑挂了恢复、按断点续传、数据对账这些全都要自己搞。而且一次性脚本维护成本极低，但也意味着一切都得重新造轮子。

Spark方案最“高大上”，性能也确实最强，但为了一个历史数据迁移任务去额外维护一套Spark任务开发和部署链路，对当时团队来说投入产出比不高。况且数据量还没到非Spark不可的量级。

最后选了Kettle。理由有三点：第一，团队里有人已经在用Kettle做日常数据清洗，有存量工程经验；第二，Kettle是图形化配置，转换流程、每一步在做什么完全透明，后续人员交接、审计、修改都很方便；第三，Kettle对MongoDB和HBase都有现成插件，虽然细节上有不少坑，但整体路径是通的，比从零写客户端代码省很多事。

选型这件事，我的经验是：不要盲追求某个工具听起来多厉害，要看团队现状、任务规模、后续可维护性。Kettle在这个项目里就是“够用、有人会、能落地”的选项。

1.3 整体迁移流程怎么设计

整个迁移方案最终设计成一条主线加两个分支。主线是Kettle的转换流程：MongoDB读取数据 -> 字段清洗与类型转换 -> 拼接Rowkey -> 写入HBase。两个分支分别是：目标端HBase表结构设计与预分区规划、源端MongoDB读取策略（全量或增量）设计。

流程上我建议分三步走：

1. 先拿一个集合的小样本数据做全链路打通，确认字段映射和类型转换逻辑没问题。
2. 再跑一批中等量级数据，压一下写入性能，针对性调优。
3. 最后才放开全量任务，并通过Job机制做断点续跑和失败重试。

这样看起来慢，实际上是最快的。第一版直接全量灌下去，大概率会撞上各种类型报错和性能瓶颈，前面省的时间后面会加倍还回来。

2. 源端与目标端的关键细节拆解

2.1 MongoDB端：连接认证与数据读取方案

Kettle读取MongoDB靠的是MongoDB Input步骤。这个步骤的连接配置本质上就是构造一个MongoDB客户端URI，所以很多连接问题其实是对应到MongoDB本身的连接规则上。

常见的连接串形式是：

mongodb://user:password@host:27017/admin?authSource=admin

有几个细节容易被忽略。一是认证库和业务库经常不是同一个，比如账号是在admin库下创建的，但数据在business库里，连接串里数据库名写了business，Kettle连接测试可能通过，真正读取数据时反而报认证失败。这里最稳妥的做法是：数据库名指向认证库，然后在步骤的Database配置里单独填目标库名，或者在URI里明确用authSource参数。

二是Kettle自带的MongoDB驱动版本可能很老，连接新版MongoDB（比如4.x之后的版本）会出现加密协议或认证机制不兼容。我在排查阶段遇到过一个典型的握手失败，换了新版驱动jar到Kettle的lib目录之后就好了。

读取数据时，MongoDB Input步骤支持填Query JSON，也支持填Aggregation JSON。这个一定要用起来，别把全表数据拉到Kettle里再过滤。MongoDB的优势就是可以把过滤、字段裁剪、嵌套字段展开等操作下推到库端执行，能用聚合管道完成的尽量用聚合管道，比如：

[ { "$match": { "event_time": { "$gte": "2023-01-01 00:00:00" } } }, { "$project": { "_id": { "$toString": "$_id" }, "user_id": "$user_id", "action": "$action", "event_time": { "$toLong": "$event_time" }, "source": "$extra_info.source", "device": "$extra_info.device" }} ]

这里面有几个小技巧：用$toString把ObjectId转成字符串，避免后面在Kettle里处理对象类型；用$toLong把日期转成时间戳，HBase里排序和范围查询都好用；嵌套文档直接在聚合阶段$project展开成平铺字段，比拉到Kettle再解析JSON省太多事。

2.2 HBase端：Rowkey设计、列族与预分区

HBase的表设计直接决定迁移之后的可用性，这是整个项目里最值得花时间研究的部分。

先看Rowkey设计。HBase存储时按Rowkey字典序排列，查询时按Rowkey精确Get或范围Scan。这个项目里的核心查询需求是按user_id查一段时间段内的记录，所以我设计的Rowkey格式是：

MD5(user_id).substring(0,4) + "_" + user_id + "_" + Long.MaxValue - event_time

前4位是盐值。为什么要加盐？如果直接用user_id开头，user_id相同的记录会连续写在一起，如果某个用户的记录特别多，就会形成Region热点，写入和查询都卡在那一个Region上。加盐之后数据可以相对均匀地分布在多个RegionServer上。后面的Long.MaxValue - event_time是让时间倒序排列，这样最新记录排在最前面，Scan起来很方便，按时间范围查询也能很快定位。

再来看列族设计。HBase不建议设计多个列族，因为不同列族的数据会落在不同文件里，跨列族查询会付出额外代价。除非不同数据有完全不同的访问频率和TTL需求，否则一个列族就够了。这里统一用cf作为列族名，业务字段都作为列限定符放在这个列族下。

创建表的时候必须预分区。如果等数据写进去之后再手动切分Region，数据已经倾斜了，后面还要做Region split，代价很大。我建表的语句类似：

create 'ods_user_action', {NAME => 'cf', COMPRESSION => 'SNAPPY'}, SPLITS => ['a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v','w','x','y','z']

盐值取值范围是0000到ffff，所以按十六进制字符拆出来的预分区可以保证写入初期不会全部挤在前几个Region上。这里只列了26个字母分区，实际可以根据数据量和RegionServer数量拆分得更细。

2.3 字段类型映射：BSON到底怎么落进HBase

MongoDB（BSON）和HBase的数据类型差异，是迁移中最容易踩坑的部分。HBase一切列值都是字节数组，不存在所谓“字段类型”的概念，Kettle从MongoDB读出来的字段类型五花八门，直接往HBase写经常报类型不匹配，核心解法是在中间步骤把类型统一成字符串或字节。

我整理了一份常用映射表：

这里特别提醒一点：HBase里存字符串数字和存二进制数字的范围排序结果完全不一样。比如字符串"100"会排在"99"前面，因为它是按字节逐位比较的"1"和"9"。如果后面对这个字段做范围查询或排序，必须把数字统一成定长字符串，或者直接存二进制Long。我们最终把时间、时长、金额这类字段全部转成Long类型二进制存储，避免了一堆排序问题。

3. 实操：从建表到跑通一个迁移转换

3.1 环境准备与插件版本选型

动手之前先把环境理顺。我当时的版本组合是：Kettle 8.2、MongoDB 4.4、HBase 2.1。Kettle 8.2自带的HBase插件对HBase 2.x的支持有点勉强，好在可以通过替换插件包解决。如果你用的是更新版本，比如Kettle 9.x或10.x，情况会好一些，但依然建议先建一个小的测试环境验证通道。

有几个前置工作必须做：

1. 确认Kettle的lib目录下有MongoDB驱动jar，没有就下载对应版本的mongodb-driver-core等jar包放进去，然后重启Spoon。
2. 确认Kettle里HBase插件已经加载成功。在Spoon左侧“Big Data”分类下能看到HBase相关的连接选项。
3. 确认HBase的REST服务可用。Kettle的HBase插件默认通过HBase REST API连接，需要确保HBase集群上启动了REST服务。这个点很容易漏，我当时就卡了半天。

REST服务启动命令是：

hbase rest start

验证方式很简单，浏览器访问http://hbase-rest-host:8080/version，能返回版本信息就说明服务正常。

3.2 在HBase上创建目标表

我是在HBase Shell里直接创建的表。表名用了ods_user_action_daily，按日期分区管理，每个分区对应一天的数据，这样后续如果要清理过期数据，直接下线某个日期范围的分区就行，不需要走删除接口。

建表时同时设置了压缩和预分区：

create 'ods_user_action_daily', {NAME => 'cf', COMPRESSION => 'SNAPPY', VERSIONS => 1}, {NUMREGIONS => 45, SPLITALGO => 'HexStringSplit'}

数据量预期在千万级别，所以45个预分区足够用。如果预期几十亿行，Region数量就得重新算，经验值是每个Region期望承载10-20GB数据，根据数据总量反推Region数。

3.3 配置Kettle转换：MongoDB Input到HBase Output

在Spoon里新建一个Transformation，整体步骤链路是：

1. MongoDB Input
2. Select Values（字段重命名和类型调整）
3. Concat Fields（拼接盐值、user_id、时间戳生成Rowkey）
4. 两个字段设置步骤（补全列名和标记）
5. HBase Output

MongoDB Input的配置里，连接名选择之前建好的MongoDB连接，数据库和集合名认真填好，Query JSON/Haggregation JSON这一栏把聚合管道放进去。注意Chekck输出字段，点“Get Fields”让Kettle自动读取字段列表，然后手动把类型调整成String、Long等。

Select Values步骤重点做两件事：把MongoDB输出中体积大、用不到的字段删掉；把时间字段从Date类型转成Long类型。这里可以用“Calculator”组件算一个event_time_long的字段，公式填event_time.getTime()，或者直接用“Modified Java Script Value”写：

var eventTimeLong = new java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse(event_time_str).getTime();

说实话，Java Script组件灵活但性能一般，每条记录跑一次解析器，在千万级数据量下会有明显开销。我后来优化时把时间转换全部下沉到MongoDB聚合管道的$toLong，Kettle这边直接拿到Long类型的字段，省掉了这层计算。

HBase Output的配置是整个转换的核心。先建立HBase Connection，指向REST服务地址和HBase集群名，然后新建一个Mapping，配置：

• Rowkey来源字段：选择拼接好的rowkey字段。
• Rowkey类型：由于我们Rowkey是字符串形式，这里选String。
• 列族和列映射：列族cf，列名action对应字段action，列名event_time对应字段event_time_long，以此类推。

这里有个很容易犯的错：HBase Output的列映射里，如果填了一个HBase物理列，但该列在映射配置里没有定义，运行时才会报“Family not found”错误，排查起来非常痛苦。所以Mapping里所有用到的列族和列都要预先配置齐全。

3.4 用Job做调度和断点续跑

单条Transformation跑起来容易，但线上执行不能靠人盯。我外面套了一个Job：先创建一个“Get previous result”步骤，读取一个参数文件里记录的last_run_time，然后作为动态参数传给MongoDB Input的聚合管道，再执行Transformation，最后把本次运行的max(event_time_long)写回参数文件。

这样每次跑的时候，只迁移新增部分。断点续跑也是一样的思路，如果某次跑到一半挂了，重启Job时会从上次记录的位置继续，不需要把已写入的数据清理掉重跑。

但注意一点：记录断点的时机要放在Transformation成功完成之后，不能放在SQL查询之后。否则数据已经写入一部分但断点还没更新，下次重跑会重复写一批数据，HBase是覆盖写，重复写入通常不会产生坏数据，但会影响统计精确性。我们最终的方案是迁移任务里带一个批次号，每个批次结束后做一次数据对账，确保行数一致。

3.5 跑通第一版：先看到数据再说优化

第一版我完全没有做任何性能优化，目的只有一个：看数据能不能通。大概花了两个小时完成配置，跑了几万条数据，用HBase Shell检查：

scan 'ods_user_action_daily', {LIMIT => 10}

看到数据正常落进去，字段顺序和类型都符合预期，才继续投入做性能提升。如果这一步都出问题，后面再快也没有意义。

4. 性能优化实录：从每小时几万行到每分钟几十万行

4.1 第一轮：直接跑，发现瓶颈

第一版全量任务上线，预期一小时迁移百万行，实际跑下来每小时只有几万行，慢得让人怀疑人生。我当时先做了个分段测速：单独把MongoDB Input接一个“Write to log”步骤跑一遍，发现MongoDB读取速度可以达到每秒几千行，说明源端没问题；单独读一个静态文件再写HBase Output，发现HBase写入端每秒只有几十行，瓶颈基本锁定了。

HBase写入慢的原因很快找到了：Kettle默认的HBase输出是每条记录即时提交到REST服务，相当于每次Put都是一次网络请求，不仅没有批量写，而且开启着WAL（Write Ahead Log），每行都要落一次日志。这在HBase里等于故意拿最差的写入路径在跑。

4.2 第二轮：批量提交、并发数与JVM

针对瓶颈依次做了几个调整：

首先是HBase Output的“Write buffer size”调大。把每次提交的大小从默认值调整到8MB，让Kettle先在内存里攒一批Put，再一次性提交。这一项改动效果立竿见影，写入速度直接提了几个数量级。原理是减少了网络往返和HBase端RegionServer写WAL的次数。

其次是控制并发。我一开始以为并发越大越快，把Transformation复制了6份同时跑，结果HBase端RegionServer CPU被打满，反而更慢。后来改成两个并发任务，每个任务处理不同的日期分片，整体吞吐量提升反而更明显。并发数不是越大越好，要看目标端的处理能力和Rowkey分布的分散程度。

第三是调整Kettle自身JVM参数。Kettle默认的堆内存可能只有1G或2G，在批量写缓冲调大之后，很容易出现GC频繁甚至OOM。我修改了Spoon启动脚本里的PENTAHO_JAVA_OPTIONS，把它调整成：

-Xms4096m -Xmx8192m

同时关闭了Kettle的预览面板等无关功能，减少内存占用。

这一轮优化之后，每小时数据量从几万行提升到百万行级别，白天跑的话基本能跟上业务增量了。

4.3 第三轮：HBase端配置与Rowkey热点

到了这个阶段，又遇到一个新问题：写入吞吐量不低，但HBase监控面板上看到有个别RegionServer的写请求量明显高于其他节点，出现了热点Region。

排查后确认是Rowkey盐值分布不均匀导致的。我最初用的盐值是取user_id字符串哈希后截取前4位，但业务数据里user_id有大量相同前缀，导致部分盐值出现频率远高于其他值。修复方式是把盐值来源改成对整个user_id做MD5后取前4位，而不是截取前缀。改完Rowkey格式之后，重新创建了表，再把数据重导了一遍，热点分布均匀了，RegionServer负载也平了。

HBase端还做了两个配置调整：一是关闭了非必要的WAL，对纯离线导入场景来说，允许异常情况下丢一部分数据是可以接受的，直接设了setWriteToWAL(false)；二是把MemStore刷新大小调大，让Region在内存里攒更多数据再落盘，减少小文件产生。

这两个操作在Kettle的HBase Output里不一定直接暴露，如果需要精细控制，可以走HBase Shell对表做动态参数调整。我们是直接在HBase端用Shell设置的。

4.4 最终效果与资源参考

调完以后的最终效果：单任务每分钟写入量达到了几十万行，整个全量迁移任务（几千万条历史数据）在预计6到8小时内完成，后续每日增量跑分钟级就结束。这个性能对这个场景来说完全够用。

资源参考是这样：Kettle所在服务器8核16G，HBase集群3台RegionServer（16核32G），源MongoDB 3节点副本集。Kettle任务并发数控制在2，JVM堆内存8G，HBase侧写缓冲8MB。想抄作业的朋友可以参考这个配置去估算自己的集群。

5. 常见问题与排查技巧实录

5.1 MongoDB连接失败与认证问题

问题表现：Kettle里点击“Test”连接成功，但是运行时总是报Authentication failed或者Command failed with error 18。原因基本都在认证库上。Kettle连接串里的数据库名被同时用来做认证和连接，如果业务库和认证库不是同一个，就会出现测试连通但不放行的现象。解决方式就是把URI改成mongodb://user:pass@host:27017/business?authSource=admin这样的形式，确保认证库明确指定为admin。

如果连接新版本MongoDB报Unknown command 'hello'这类错误，基本可以断定是驱动版本太老。解决方式是下载与MongoDB版本匹配的驱动jar，放入Kettle的lib目录，替换掉自带的旧版本。

5.2 ObjectId和嵌套文档的坑

MongoDB的_id字段默认是ObjectId类型。Kettle把ObjectId读出来之后，如果直接写入HBase，类型会变得不可控，有时是二进制串，有时是对象字符串。建议在MongoDB聚合管道里用$toString提前转成字符串，或者干脆忽略_id字段，用业务唯一ID做Rowkey。

嵌套文档是最麻烦的。早期版本我试过直接把整个document塞给HBase，结果写入的是一长串Java对象toString后的内容，完全没法用。后来改成MongoDB聚合管道里用$project展开或者$unwind打平，只有个别确实需要保留完整JSON的字段才用JSON字符串存储。一个经验：能展开的绝不存JSON，因为下游查询JSON字段时，HBase本身没有解析能力，还得拉回业务层处理。

5.3 HBase输出报错：TableNotFound与FamilyNotFound

Kettle的HBase Output报Table not found时，先确认HBase连接指向的集群是正确的，再确认REST服务是否连着同一个HBase集群。如果REST服务连的是A集群，你的表建在B集群，连接测试也能通过，但运行时就找不到表。

报Family not found则通常是Mapping里列族配置不全。HBase Output的Mapping配置里有列族映射，某个字段用到的列族没有显式添加，运行到这条记录时才报错。排查方式是把Mapping开的配置里“Add column family”全部检查一遍，确保所有列族都填了实际存在的列族名。

5.4 中文乱码问题

Kettle写的HBase数据读出来全是????，大概率是Kettle自身默认字符集问题。Windows环境下Spoon经常用的是GBK，写入时把UTF-8字符串以GBK编码写到字节数组，读出时就乱了。解决方式有两种：在Kettle启动参数中加入-Dfile.encoding=UTF-8；或者保证HBase映射配置中字符集为UTF-8。另外在HBase Shell里查询数据时，尽量用scan 'table', {FORMATTER => 'toString'}查看。

5.5 内存溢出与任务卡死

跑了大几个小时之后Kettle突然卡死，控制台报OutOfMemoryError: Java heap space。原因多是写缓冲调得过大、并发复制太多、以及Kettle步骤里缓存了大量字段值。解决方式是先把JVM堆内存调大，再把批量提交大小降低到一个合理范围。8MB写缓冲虽然对HBase友好，但多条并发复制会同时占用大量内存，建议并发数和写缓冲乘积控制在堆内存的四分之一以内。

如果任务本身处理海量历史数据，不建议单条Transformation里从头跑到尾，可以拆成多个日期范围子任务，放到Job里串行或并行执行，这样单任务内存压力小，失败重跑的成本也低。

5.6 快速排查速查表

写在最后的一点个人体会

这个项目做完之后，我最大的感受是：数据迁移的难点从来不在工具本身，而在数据模型的对齐和存取模式的匹配。Kettle提供了一个可视化的管道，把MongoDB的数据搬到HBase只是第一步；真正的价值在于你在搬之前有没有想清楚HBase那边Rowkey怎么设计、字段以什么形式存储、后续查询能不能高效命中。

我在这个项目里就是因为一开始轻视了Rowkey盐值的分布，导致后期数据倾斜、性能反复，白白浪费了大半天时间重新建表回灌。后来再接到类似任务，第一件事永远是找下游要查询场景：按什么Key查、查什么范围、要不要排序、对一致性要求多高。这些确认清楚了，再回头建表、配Kettle脚本，基本就是水到渠成的事情。

另外一个小建议：做完迁移之后，别忘了做一个简单的数据对账脚本，比如对比MongoDB源集合的总行数和HBase目标表的总行数，或者抽样对比某几个Rowkey的字段值。这一步很笨，但能兜住大多数隐蔽的类型转换错误和漏数问题，对一次性大批量迁移来说尤其重要。希望这篇内容能帮你在做类似项目的时候少走一些弯路。