最近整理笔记，翻出我维护 HBase 集群这几年用过的高频 Shell 命令，发现真正日常就是那么二三十条，但每条背后都有值得说清楚的细节。比如很多人建表不预分区，写请求全压在一台 RegionServer 上；再比如 drop 之前忘了 disable，被异常砸脸才想起来表还有状态这回事。这篇 HBase Shell 常用命令实战，我按自己的使用习惯串一条完整主线：先确认版本和连接方式，再走命名空间、建表、改表、删表这条 DDL 链路，接着是 put、get、scan 的读写参数，把服务端过滤器单独拎出来讲，最后是 Region 合并、快照备份、归档清理这些运维命令，连同我踩过的几个真实坑。无论你是刚上手 HBase 的开发者，还是需要日常维护集群的工程师，都能直接照着敲一遍。
1. 先摸清家底：版本差异和连接方式决定你能走多远
1.1 客户端与服务端的版本必须同代
HBase Shell 的命令风格看起来都差不多，但 1.x 和 2.x 在细节上差别不小。最典型的是merge_region：1.x 里传两个 region 名就能合并，2.x 里必须带 force 参数，不然命令会一直报错。还有describe的输出，2.x 会把每个 region 的编码名、Start Key、Server 地址都列出来，1.x 相对简单。所以拿到一个集群，第一个动作永远是执行version，确认客户端版本和服务端在同一个大版本内。
客户端版本如果过旧，连 2.x 服务端会出现 RPC 协议不匹配。表面现象是 Shell 能进去，执行list、describe没问题，一旦put或get就抛ProtocolMismatchedException。我自己排查过两次才反应过来，都是客户端机器上的版本太老导致的。换了一个与集群版本一致的客户端包，问题立刻消失。
hbase(main):001:0> version 2.3.7, r123456, Sat Mar 15 04:00:00 CST 20251.2 Shell 的三种进入方式
日常用得最多的是三种：
- 直接在集群节点上执行
hbase shell，进入交互模式。 - 带脚本批量执行：
hbase shell --file /tmp/ops.hbase。 - 通过管道传入命令：
echo "status 'simple'" | hbase shell。
远端连接时要注意，hbase shell本身没有独立的 connect 命令，它依赖客户端配置文件里的 ZooKeeper quorum 地址。也就是说，你在自己笔记本上装一个同版本客户端，改好hbase-site.xml中的hbase.zookeeper.quorum，也能连到集群。但跨网络访问时如果延迟高，Shell 的交互会明显变卡，这不是命令执行慢，而是网络往返变多，排查线上问题别在这上面浪费时间。
1.3 三条基础命令看清集群状态
| 命令 | 作用 | 适合场景 |
|---|---|---|
status | 查看集群整体状态，不传参数返回摘要 | 日常巡检 |
status 'detailed' | 列出每台 RegionServer 上的 region 数 | 判断热点分布 |
whoami | 查看当前连接用户，配合权限排错 | 排查无权限问题 |
list | 列出所有表，支持list 'ns:.*'正则 | 确认表是否存在 |
这些命令都只碰元数据，不触发实际读写，线上随便敲。真正要注意的，是从建表开始的操作——那才是决定后面所有读写效率的分水岭。
2. 命名空间和表结构：建表、改表、删表的完整链路
2.1 命名空间：先规划再动手
命名空间相当于数据库里的 schema，用来隔离业务。默认的命名空间是default，生产环境建议按业务线划分。常用命令：
create_namespace 'order_ns' list_namespace describe_namespace 'order_ns' drop_namespace 'order_ns'注意drop_namespace只允许删除空命名空间，里面有表时直接执行会报错。我习惯在每个命名空间下至少留一张基础元数据表，所以删命名空间的场景反而很少。命名空间规划最好在建项目初期就定下来，后期迁移表的开销远大于当时的规划成本。
2.2 建表：预分区是性价比最高的优化
最简单的建表写法是create 'order_ns:order_detail', 'cf1'，但默认只分配一个 region，所有写入都落在同一台 RegionServer 上，等到数据量上来再想改分区就麻烦了。我建议建表时就按预估的 rowkey 分布预分区：
create 'order_ns:order_detail', {NAME => 'cf1', VERSIONS => 3, TTL => 604800}, {SPLITS => ['10000', '20000', '30000', '40000']}如果不想手动枚举 split 点，可以用算法预分区：
create 'order_ns:order_detail', 'cf1', {NUMREGIONS => 10, SPLITALGO => 'HexStringSplit'}HexStringSplit适合 rowkey 是十六进制字符串的场景，能让数据按前缀均匀散到各个 region。VERSIONS控制每个 cell 最多保留多少个版本，默认是 1，很多人误以为是 3。想要查询历史版本，必须在建表时就把这个值调到需要的数量。
预分区看着简单，但它是整个 HBase 表设计里最能提前避免热点问题的一步。rowkey 设计是开发阶段定的，分区是建表时定的，这两件事都等线上出事以后再回头改，成本极高。
2.3 describe 与 alter：改结构之前先看现状
describe是最有用的查询命令之一，它能看清一张表的列族配置、调整后状态、已分配的 region 数：
describe 'order_ns:order_detail'输出里重点关注VERSIONS、TTL、IN_MEMORY、REPLICATION_SCOPE。如果发现列族的VERSIONS建小了，可以在线调整：
alter 'order_ns:order_detail', NAME => 'cf1', VERSIONS => 5新增列族也可以在线执行：
alter 'order_ns:order_detail', NAME => 'cf2'但删除列族在大部分版本里会要求表先处于禁用状态。我自己的稳妥做法是：所有涉及已有列族属性变更的操作，都在业务低峰期执行disable、alter、enable三步，全程几分钟，换来的是元数据一致性的安心。别嫌麻烦，线上改表结构出问题时的恢复成本，比这几分钟大得多。
2.4 disable、enable、drop 的顺序逻辑
HBase 表是有状态的：enabled才能读写，disabled后不再接受读写请求，此时才能删除表。完整删除链路是：
disable 'order_ns:order_detail' drop 'order_ns:order_detail'少一步都会报TableNotDisabledException。想在保留分区结构的前提下清空数据，用：
truncate_preserve 'order_ns:order_detail'truncate_preserve会保留预分区边界，只清数据；如果分区也可以重新来，直接truncate就行。删除表之前我还会用list_snapshots确认有没有近期快照，没有的话先补一个快照再删——这是给自己留后路。
3. 数据读写实战：put、get、scan 的核心参数
3.1 put 写入：版本和时间戳的关系
写入一条数据：
put 'order_ns:order_detail', '10001', 'cf1:item_name', '机械键盘' put 'order_ns:order_detail', '10001', 'cf1:status', 'PAID'不指定时间戳时，HBase 自动使用当前毫秒时间，同 cell 的多次写入会保留多个版本，版本数上限由列族的VERSIONS决定。手动指定时间戳的场景一般出现在数据回填或者修复时：
put 'order_ns:order_detail', '10001', 'cf1:item_name', '机械键盘Pro', 1712345678900这里有个常见误区：同 rowkey 反复 put，读出来的是最新时间戳的版本，不代表旧版本丢了。只有超过VERSIONS上限的版本才会在写入时被覆盖淘汰。如果列族VERSIONS=1，那同 cell 的旧值每次都会直接覆盖——这也是很多人"数据怎么没了"的真相。
3.2 get 读取：按列族裁剪数据
按 rowkey 读取：
get 'order_ns:order_detail', '10001'只取指定列：
get 'order_ns:order_detail', '10001', {COLUMN => 'cf1:item_name'}取某个列族的最近多个版本：
get 'order_ns:order_detail', '10001', {COLUMN => 'cf1', VERSIONS => 5}get是走 HBase 的 PointGet 路径，所有 RegionServer 并发定位 rowkey 所在 region，延迟很低。Shell 里我经常配合exists判断表、配合count统计行数来验证写入是否成功：
count 'order_ns:order_detail', {INTERVAL => 100000, LIMIT => 1000000}3.3 scan 扫描：范围控制是所有优化的前提
scan是开销最大的读命令，裸 scan 全表在生产环境几乎是禁忌，因为要串所有 region 的所有 HFile。日常排查时至少加LIMIT和起止 rowkey：
scan 'order_ns:order_detail', {LIMIT => 10} scan 'order_ns:order_detail', {STARTROW => '10001', ENDROW => '10010', LIMIT => 20}STARTROW 是包含关系，ENDROW 是排除关系，也就是左闭右开区间。如果有大范围扫描需求，一定要配合BATCH和CACHING控制单次 RPC 返回的数据量：
| 参数 | 控制粒度 | 我的建议 |
|---|---|---|
LIMIT | 返回行数上限 | 交互排查用 10~100 |
CACHING | 单次 RPC 返回的行数 | 默认用集群配置，大 scan 降到 100 |
BATCH | 单次 RPC 返回的 cell 数 | 宽表场景调到 1000，防 RPC 超时 |
scan 'order_ns:order_detail', {COLUMNS => ['cf1:item_name', 'cf1:status']}只查需要的列，HBase 底层可以减少 HFile 的块读取，比全列扫描快不少。Shell 里的 scan 更多是验证数据分布和调试 rowkey 设计，真做大范围数据导出，应该用 Spark 或 MapReduce 任务，而不是在 Shell 里跑大 scan。
4. 让过滤发生在服务端：Shell 里的过滤器组合
4.1 行级过滤器：RowFilter 与 PrefixFilter
Shell 的 scan 支持传递FILTER参数，过滤器在服务端执行，只把符合条件的 cell 返回客户端。最常用的是按 rowkey 前缀过滤：
scan 'order_ns:order_detail', {FILTER => "PrefixFilter('1000')"}等价于STARTROW => '1000', ENDROW => '1001'，但语义更清晰。RowFilter 支持多种比较器和比较运算符：
scan 'order_ns:order_detail', {FILTER => "RowFilter(=, 'regexstring:^1000[0-9]{2}$')"}比较器有binary、binaryprefix、substring、regexstring四种。我实战中最常用的是substring做模糊匹配，regexstring做精确范围匹配。注意正则走的是 Java 正则语法，转义要写双反斜杠，这个细节坑过不少人。
4.2 列与值的过滤：ValueFilter 和 SingleColumnValueFilter
按值过滤：
scan 'order_ns:order_detail', {FILTER => "ValueFilter(=, 'substring:PAID')"}它会扫描所有列的值，适合字段数量少的窄表。如果是按某个指定列的值过滤行，用SingleColumnValueFilter更精准：
scan 'order_ns:order_detail', {FILTER => "SingleColumnValueFilter('cf1', 'status', =, 'binary:PAID')"}这个过滤器的隐藏参数是filterIfMissing。默认情况下，一行数据如果压根没有cf1:status这一列，该过滤器不会决定这行是否被排除，容易在结果里混入预期外的数据。建议显式把它设为 true：
scan 'order_ns:order_detail', {FILTER => "SingleColumnValueFilter('cf1', 'status', =, 'binary:PAID', true, true)"}4.3 FilterList：AND 和 OR 的组合逻辑
多个过滤器要叠加时，用FilterList。它的第一个参数是逻辑关系，后面接过滤器列表：
scan 'order_ns:order_detail', {FILTER => "FilterList(AND, PrefixFilter('1000'), ValueFilter(=, 'substring:PAID'))"}AND 表示全部满足才返回，OR 表示任一满足即返回。需要注意，过滤器的执行顺序会影响性能，我通常把开销最小的条件（比如PrefixFilter）放最前面，让它先把行筛掉一部分，后面的ValueFilter或SingleColumnValueFilter才能少碰数据块。
有一个性能层面的经验：能靠 rowkey 范围解决的问题，就别滥用过滤器。PrefixFilter这类行级过滤器相当于是优化过的范围扫描，开销很低；但ValueFilter本质上要扫描列数据，在列很多的宽表上会很吃力。Shell 里调试过滤器时，先用LIMIT => 10跑通逻辑，再放开全量，是避免一个慢查询把 RegionServer 拖垮的保险做法。
5. 运维级命令：Region 管理、压缩、快照与归档清理
5.1 手动 split 与 merge_region
正常情况 Region 分裂由 HBase 自动处理，但某些场景需要手动干预，比如知道某个热点 rowkey 区间即将涌入大量写入，提前把 region 切小：
split 'order_ns:order_detail', '15000'不带第二个参数时，会对表的每个 region 按各自的 split 点触发分裂。反向操作是合并相邻 region：
merge_region 'region_a_encoded_name', 'region_b_encoded_name', true最后一个 true 就是 HBase 2.x 新增的 force 参数，不传就报错。注意合并只允许相邻 region，两个 region 的编码名从describe的输出里取，那个长串就是。
5.2 compact 与 major_compact 的正确时机
数据删除会产生标记，空间释放要等压缩。日常的compact是轻量合并，开销小；major_compact会重写某个 region 下的所有 HFile，彻底清除删除标记和旧版本：
compact 'order_ns:order_detail' major_compact 'order_ns:order_detail' major_compact 'order_ns:order_detail', 'cf1'我踩过最疼的坑，是在业务高峰期对一张大表执行了major_compact。HFile 重写的 IO 被前台读写一叠加，RegionServer 直接卡到 GC 频繁。现在我的原则是：大表先分 region 批次手动执行，指定 region 名逐个压，或者干脆不开手动 major_compact，让它走 HBase 自带的定时策略。低峰期执行是底线，执行期间盯住 RegionServer 的 IO 指标，超过日常水位立刻想办法停。
5.3 快照：误删恢复的唯一指望
快照是 HBase 里最值得养成习惯的命令，轻量且不阻塞读写。日常操作：
snapshot 'order_ns:order_detail', 'snap_20250601' list_snapshots clone_snapshot 'snap_20250601', 'order_ns:order_detail_debug' restore_snapshot 'snap_20250601' delete_snapshot 'snap_20250601'clone_snapshot可以从快照克隆一张新表出来做数据分析，不影响原表；restore_snapshot会把原表恢复到快照时刻的数据，但前提是表处于禁用状态：
disable 'order_ns:order_detail' restore_snapshot 'snap_20250601' enable 'order_ns:order_detail'说句实在话，我见过不止一次线上误删数据的场景，最后能安全找回的，全是依赖快照。没有快照的表，drop 之后连专业的恢复工具都难救。所以每次大版本变动前一条snapshot，是我雷打不动的习惯。
5.4 集群层面的维护命令
再补几个频繁用的：
flush 'order_ns:order_detail' balancer balance_switch true balancer_enabledflush手动把 MemStore 刷成 HFile，多用在需要观察数据落盘或重启前；balancer触发 Region 均衡，数据倾斜严重时用得上。HBase 2.x 还有一条cleaner_chore，会触发清理hbase:archive目录下未被任何快照引用的归档文件。必须注意，如果表有快照，对应 HFile 就不会被清理，快照删除之后归档文件才会释放，这也是很多人发现集群 HDFS 占用只增不减的隐藏原因。
6. 真实踩坑记录与可复用的 Shell 小技巧
6.1 我踩过的三个典型错误
第一是忘 disable 就 drop。报错信息是TableNotDisabledException，解决方式很简单，先disable再drop。但这其实是状态管理意识的缺失，HBase 表不是简单地删文件，它有一个完整的状态机。
第二是裸 scan 全表。有一次临时排查线上数据，我在一张 10 亿行的表上直接执行scan，不小心带上了ValueFilter做模糊匹配，RegionServer 的计算线程被打满，线上读写延迟飙到几十秒。事后反思，排查问题也应该遵循先LIMIT再放量的原则，任何一次 Shell 操作都要当成一次小查询来设计。
第三是建表VERSIONS=1导致的"历史数据失踪"。业务想查历史操作记录，结果相同 rowkey 的多次 put 都只留了最新值。这个坑用alter也救不回来，因为旧版本在写入时就被覆盖淘汰了。所以建表前确认版本需求，比事后补救重要得多。
6.2 Shell 脚本化：把重复操作变成文件
Shell 交互模式适合临时操作，但批量运维一定要脚本化。HBase Shell 底层是 JRuby，所以脚本文件里可以写简单的逻辑：
# /tmp/ops.hbase puts "batch snapshot start" list 'order_ns:.*' snapshot 'order_ns:order_detail', 'snap_batch_20250601' exit然后执行：
hbase shell /tmp/ops.hbase也可以用管道配合 bash 循环，对多张表做同一操作：
for t in order_detail order_refund order_cancel; do echo "major_compact '$t'" | hbase shell done这里有个细节：脚本里的命令一旦某行执行报错，后续脚本会继续跑，不会自动中断。所以我的脚本第一行永远是puts打印开始时间，最后一行打印结束时间，配合日志就能快速定位是哪条命令出问题。
6.3 我坚持的几条 Shell 使用原则
Shell 是很好的交互排错工具，但它不适合大数据量处理。大批量写入应该走 BulkLoad，大批量读取应该走 Spark，Shell 只负责验证和运维。
关于 rowkey，我见过太多人拿着设计不佳的 rowkey 试图用 Shell 命令补救。rowkey 决定了 scan 的范围效率，过滤器和预分区都救不了随机散列的 rowkey 做范围查询——因为数据根本不在相邻 region。这个设计问题要在表结构阶段解决，Shell 解决不了。
最后一条最朴素也最重要：每次对表做结构性操作前，先敲snapshot。一来快照很轻，开销可以忽略；二来它真的是误操作之后唯一的确定性恢复手段。我自己的习惯是每个季度给核心表打一轮快照，大版本升级前额外补一次，再配上delete_snapshot定期清理不需要保留的快照，避免归档目录被撑爆。Shell 命令再多，能守住数据安全底线的，往往是这些看起来不起眼的习惯。
