HBase 3.0.0 是大版本升级，不应被写成 2.6 的小补丁。官方下载页显示 3.0.0 发布于 2026-08-05，同时 2.6.6 发布于 2026-06-09，2.5.15 被标为 stable release。基础机制仍可用 2.6.6 解释，但 3.0 的部署、客户端连接和 API 兼容边界必须单独处理。

本篇只抓一个核心问题：3.0 相对 2.6 改了什么；哪些工作负载应该选别的数据库。

版本位置图

flowchart TD
  A[HBase 2.6.6 基础机制] --> B[row key / Region / WAL / MemStore / HFile]
  B --> C[2.x 客户端与运维习惯]
  C --> D[HBase 3.0.0 大版本升级]
  D --> E[JDK 17+]
  D --> F[Hadoop 2 移除]
  D --> G[MasterRegistry/RPC bootstrap 默认路径]
  D --> H[deprecated/private API 清理]
  H --> I[Coprocessor/Phoenix/内部 API 风险]

这张图强调一个写作边界：00—18 讲 2.6.6 基础机制，不把 3.0 行为混入基础篇；19 单独讨论大版本差异和选型边界。

3.0 不改变 HBase 的核心模型。表仍按 row key 排序，Region 仍按 key range 切分，写入仍经过 WAL 和 MemStore，flush 仍产生 HFile，compaction 仍控制读放大和空间放大。变化主要在运行时基线、依赖、连接注册、API 清理和兼容承诺。

官方版本事实

事实 来源 写作结论
3.0.0 发布于 2026-08-05 Apache HBase Downloads 可讨论为最新 major release
2.6.6 发布于 2026-06-09 Apache HBase Downloads 本系列基础实验线
2.5.15 标记 stable release Apache HBase Downloads 不把 3.0 自动称为 stable
MasterRegistry 在 3.0 成为默认连接路径 HBase Master 文档 Master 进入连接设置关键路径
Coprocessor protobuf 依赖在 3.0 有变化 Coprocessor 文档 Endpoint 需要重查 shaded protobuf

这里不根据发布日期给 3.0 加“生产稳定”或“不稳定”标签。是否生产采用取决于官方兼容报告、组织内客户端矩阵、Phoenix 或 coprocessor 依赖、回滚方案和压测结果。

运行时和依赖变化

HBase 3.0 的大版本升级首先影响运行时基线。研究阶段确认的要点是：JDK 17+ 成为基础要求，Hadoop 2 支持被移除，日志体系使用 log4j2，Hadoop 3 线路是主要依赖方向。

这些变化不是“安装脚本细节”。它们会改变四类东西：

变化 影响
JDK 17+ 客户端和服务端 JVM 参数、GC、依赖字节码
移除 Hadoop 2 老集群不能只替换 HBase 包
log4j2 日志配置、审计规则、告警采集
deprecated API 清理 旧 client、coprocessor、Phoenix 适配层需要重编译和重测

迁移前应先固定一张依赖表：HBase server、HBase client、Hadoop、ZooKeeper、JDK、Phoenix、coprocessor JAR、MapReduce bulk load 工具、监控 agent。任何一个仍绑定 Hadoop 2 或旧 protobuf 的组件，都可能成为升级阻塞点。

MasterRegistry 的连接边界

2.x 里客户端定位集群和 hbase:meta 的路径经历过从 ZooKeeper registry 到 MasterRegistry 的演进。3.0 文档在 Master 章节明确说明，从 3.0.0 开始，默认连接 registry 基于 master RPC endpoint；至少需要一个 active 或 standby master 完成连接设置；当 meta region 移动时，客户端也需要 master 获取新位置。

这个变化不能写成“Master 开始承载所有读写数据”。Master 不转发普通数据字节，Region 的读写仍在 RegionServer 上完成。准确说法是：Master 进入客户端连接设置和部分重新定位关键路径，Master 可用性要求比旧路径更高。

由此带来三条运维要求。

第一，Master HA 不能只是控制面增强项。3.0 客户端启动连接时需要可用 master endpoint，standby master 的部署、健康检查和告警必须进入读写可用性设计。

第二，客户端超时和重试要按新连接路径校验。只验证已有长连接读写成功，不足以证明新客户端能在 Master 故障时启动。

第三，文档和 runbook 要把 ZooKeeper、MasterRegistry、hbase:meta 分开。ZooKeeper 仍承担协调职责，hbase:meta 仍是路由元数据表，MasterRegistry 是客户端连接发现路径的一部分。

API 与扩展迁移风险

HBase 的 audience annotation 很重要。Public API 才适合作为应用依赖；Private 或 Evolving API 不能按语义版本承诺理解。许多 coprocessor、Phoenix 适配、内部监控工具过去会依赖 HBase 内部类，大版本升级时风险最高。

第 16 篇提到的 Endpoint 是典型例子。HBase 文档说明，HBase 3.0.0 去掉 non-shaded protobuf 依赖后，coprocessor 需要使用 hbase-thirdparty 提供的 shaded protobuf 重新实现。旧 Endpoint 如果直接依赖生成的 protobuf 或 HBase 内部类，升级时必须重编译和运行时验证。

Bulk Load 工具也要重查。2.6 里推荐面向 BulkLoadHFiles 和 HFileOutputFormat2 写；历史上的 LoadIncrementalHFiles 路径存在弃用和替代。迁移时不能只替换命令名，应验证导入文件结构、Region 边界、权限、复制和失败恢复。

客户端迁移要检查四类调用：

调用类型 风险
旧同步 API deprecated 方法可能清理
coprocessor endpoint protobuf 和 private API 风险
管理工具 MasterRegistry、权限和 procedure 行为变化
bulk load 工具类和复制配置变化

最小迁移实验

当前本地没有 HBase 3.0.0 集群，实验为 UNVERIFIED_RUNTIME。实验目标是把“能启动”和“能承载业务路径”分开验证。

检查版本和依赖：

1
hbase version

验证 Master HA 和连接设置：

1
hbase shell

在 shell 中执行最小读写：

1
2
3
4
create_namespace 'lab'
create 'lab:hbase3', 'cf'
put 'lab:hbase3', 'r1', 'cf:q', 'v1'
get 'lab:hbase3', 'r1'

验证 meta 移动或 Region 迁移后的重新定位，观察客户端是否需要 master 获取新位置。这个实验必须在测试集群运行，不应在生产直接制造故障。

Bulk Load 迁移验证：

1
hbase completebulkload /tmp/hbase3-bulk-out lab:hbase3

Coprocessor 迁移验证应使用 MiniCluster 或独立测试集群，加载一个只读 Observer 或 Endpoint，确认 protobuf、依赖 shading、加载权限和卸载路径。

设计边界

HBase 适合的工作负载有清晰形状：按 row key 点查或范围查，写入吞吐高，数据稀疏，列族较少，访问路径可以通过 key 设计提前决定，跨行事务不是核心需求。

不适合的工作负载同样清晰。

需求 更合适的方向 原因
任意 SQL join 关系数据库、湖仓查询引擎、Phoenix 有限场景 HBase 内核没有 join 优化器
跨行强事务 关系数据库、NewSQL HBase 保证行级原子性，不提供任意跨行事务
高维 ad hoc 分析 ClickHouse、Druid、Spark SQL HBase 按 row key 路径优化
多条件二级索引 Elasticsearch、关系数据库、Phoenix 有限场景 索引一致性和回写成本高
小规模低运维 KV Redis、RocksDB、托管 KV HBase 运维面较重

这些边界不是贬低 HBase。HBase 的强项是“可预测 key 路径上的大规模随机读写”。当业务问题不是这个形状，换数据库通常比用 coprocessor、Phoenix、二级索引和复杂补偿把 HBase 改造成另一个系统更简单。

与 2.6 基础机制的关系

00—18 的主线仍然成立：RowKey 决定排序和位置，Region 决定水平切分，WAL 和 MemStore 接住写入，HFile 和 BlockCache 决定读路径成本，compaction 管理 LSM 后台成本，一致性、恢复、复制和运维都围绕这些对象展开。

3.0 需要单独处理的是外壳和契约：运行时基线变了，连接 registry 默认路径变了，旧 API 清理更激进，扩展机制更容易暴露 private API 依赖。基础模型没变，不代表升级没风险。

这也是技术系列的收束点。HBase 不是 HDFS 上的命令集合，也不是关系数据库替代品；它是一个把 Bigtable 模型、LSM 存储路径和 Hadoop 基础设施结合起来的宽列数据库。

失败恢复

3.0 迁移失败时，恢复路径必须在升级前写好。最低要求包括完整备份、snapshot 或备份恢复演练、客户端回滚版本、coprocessor 卸载方案、Phoenix 兼容版本、Master HA 验证和 bulk load 工具回退。

只升级 server 不升级 client 可能失败，只升级 client 不检查 server endpoint 也可能失败。大版本迁移要按“连接、读、写、scan、bulk load、coprocessor、metrics、安全、恢复”逐项验收。

MasterRegistry 相关故障要特别检查 master 可用性。客户端启动失败不一定是 RegionServer 或 ZooKeeper 问题，可能是连接 registry 无法从 master endpoint 获取必要信息。

扩展失败时优先卸载扩展恢复基础读写，再处理业务功能。Coprocessor 和 Phoenix 都不应阻塞 HBase 表的基础恢复路径。

工程迁移

阶段 检查项 证据
依赖盘点 JDK、Hadoop、HBase client、Phoenix、coprocessor 版本矩阵
静态编译 client、bulk load、coprocessor 构建日志
MiniCluster 读写、scan、endpoint、ACL 测试结果
测试集群 Master HA、Region move、snapshot、bulk load 运行记录
灰度 延迟、错误率、compaction、GC、replication 指标对比

模式提炼：大版本升级先查契约，再查功能。Public API、运行时基线、连接路径、数据恢复路径是契约；读写能跑只是功能样例。

常见误解

误解一：3.0 只是换一个包。3.0 是 major release，运行时、依赖和 API 都要按大版本处理。

误解二：MasterRegistry 意味着 Master 处理所有读写。Master 进入连接和重新定位关键路径，不代表普通数据流经 Master。

误解三：2.x 能编译的 coprocessor 到 3.0 一定能用。protobuf shading、private API、deprecated API 清理都会影响扩展。

误解四：Phoenix 能把 HBase 变成通用关系数据库。Phoenix 是重要上层生态，但 SQL 能力受 HBase 数据模型、索引和事务边界约束。

练习

  1. 为一个 2.6 到 3.0 的迁移项目列出依赖矩阵，标出每个组件是否依赖 HBase private API。
  2. 设计一个 Master HA 故障实验，区分“已有连接继续读写”和“新连接启动”两个路径。
  3. 把一个需要跨行事务和任意二级索引的业务需求改写成选型题，判断是否仍应使用 HBase。

系列导航

参考资料

证据等级：发布日期、下载形态、MasterRegistry 和 coprocessor 迁移风险为 VERIFIED_SOURCE；本地未运行 HBase 3.0.0，迁移实验为 UNVERIFIED_RUNTIME。