搞HBase的老哥应该都有同感：集群跑得欢，但只要不是拿RowKey查，查询就慢得像拉全表。HBase二级索引，正是为了解决这个“大数据查询痛点”存在的一组实现方案。网上聊这个的多，但大多只给个概念或者贴一段代码，真到自己搭、自己调、踩坑的时候，又能倒下一片。这篇分享就把二级索引从原理到落地一次性拆透，覆盖常见实现方案、手把手协处理器实战、Phoenix索引实操，以及大量排坑经验。
我不是在写技术文档，就是以一个做过几年HBase运维和开发的从业者身份，把我实际趟过的路子整理出来。不管你是刚接触HBase的新手，还是已经用熟练、但被非主键查询折磨的中级开发，这篇都能帮你节省至少一周的调研和试错时间。
1. 为什么非主键查询会卡成狗：HBase的索引机制与查询痛点
1.1 HBase快速查询的真相：一切靠RowKey
HBase能在大数据场景下扛住海量数据，核心就是那张稀疏的、按RowKey排序的分布式表。Region按RowKey范围切分，Master把Region分配到RegionServer上，客户端根据RowKey就能定位到哪个Region、哪个RegionServer。
RowKey本质上决定了数据分布在集群的哪个角落，所以按RowKey做Get效率极高。通常一次RPC就能拿到目标数据，延迟在毫秒级，哪怕数据量到几十亿行也不虚。
但现实中的查询，很少永远只按主键走。比如一张用户表，RowKey是user_id，业务侧却经常要按电话号码、按邮箱、按省份查，这些字段都不是RowKey。这时候你只能Scan，扫全表。
1.2 全表扫描的代价：非RowKey查询为什么会慢
很多人以为全表扫描只是“慢一点”，其实在大数据量下这是灾难性的。HBase的Scan会按照RowKey顺序遍历整个Region范围，每一行都要从HFile读出来，再反序列化，再逐列过滤。
比如一张表有5亿行，按省份过滤，每一行都必须跑一遍，就算底层用BloomFilter、块缓存做了优化，读放大也很严重。数据量小时还凑合，数据量上了千万、亿，一次Scan几秒到几分钟都很正常，对线上接口来说根本不能接受。
本质上，HBase根本不支持传统数据库那种“列索引”。它默认的索引只有主索引，即RowKey索引。所以你想按某个列快速查，就必须自己想办法维护一套“列值到RowKey”的映射关系，这就是二级索引。
1.3 二级索引到底“二级”在哪
二级索引这个名字，是相对于主索引（RowKey）来说的。你可以理解成一本新华字典：主索引是拼音查字法，二级索引是部首查字法。拼音查字法直接告诉你页码，部首查字法先定位到某个偏旁，再在偏旁下面找到字对应的页码。
HBase二级索引的通用思路就是：额外创建一张索引表，索引表的RowKey是你想要快速查询的那个列的值，value存的是主表的RowKey。查询时先查索引表，拿到主表RowKey，再回主表Get。这样原本的全表扫描，就变成两次点查了。
这套思路听着简单，真正落地时有几个大坑：索引表和主表的一致性怎么保证？索引数据怎么说建就建？索引表同步失败怎么办？有没有现成的框架？这就需要深入聊实现方案了。
2. 闯进实操之前：HBase环境准备与表设计基本功
2.1 安装配置与端口清单：先让HBase跑起来
二级索引的落地要基于一套能用的HBase环境，这里顺便把安装配置的要点理一遍。我自己用的环境是HBase 2.4.x版本，集群模式是ZooKeeper + HBase Master + RegionServer三部分。
安装前要确认几个关键端口，无论是本机调试还是上生产，防火墙和安全组都要放行：
| 组件 | 端口 | 用途 |
|---|---|---|
| ZooKeeper | 2181 | HBase集群元数据协调 |
| HBase Master RPC | 16000 | Master与客户端、RegionServer通信 |
| HBase Master UI | 16010 | Master Web监控页面 |
| RegionServer RPC | 16020 | RegionServer与客户端通信 |
| RegionServer UI | 16030 | RegionServer Web监控页面 |
| HBase REST | 8080 | REST服务接口 |
| HBase Thrift | 9090 | Thrift服务接口 |
注意，老版HBase（0.98以前）端口是60000、60010、60020这些，很多老文章还在这么写，看的时候要分清版本，别照搬。
配置上最核心的几个文件是hbase-site.xml和regionservers。hbase-site.xml里必须指定hbase.rootdir（HDFS上的路径）、hbase.zookeeper.quorum（ZK地址列表）、hbase.cluster.distributed为true。伪分布式可以把分布式设为false，但二级索引相关测试最好还是用真正分布式，否则Region分布特性体现不出来。
2.2 表设计：预分区与RowKey设计直接影响索引效果
HBase表设计里有一步常被人忽略：预分区。默认的建表方式会只生成一个Region，所有数据都往这一个Region上怼，热点问题直接拉胯集群整体性能。
创建表时用SPLITS或者SPLITS_FILE手动划分Region边界。比如按两位十六进制前缀做预分区：
create 'user_info', 'info', {SPLITS => ['0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f']}这样数据按RowKey前缀落到16个Region，写并发能力能明显上去。
二级索引的索引表同样需要预分区。比如索引表的RowKey是“手机号”，手机号开头是1[3-9]，索引表分区可以按第二位数字拆，或者用哈希前缀。我习惯的做法是：索引RowKey = 哈希前缀 + 列值 + 原RowKey，这样既能预分区，又能避免索引数据倾斜。
2.3 HBase Shell与Java API操作基础
做二级索引时，Shell和Java API都逃不掉。Shell主要用于建表、查状态、手动刷数据：
# 查看表是否存在 exists 'user_info' # 扫描表前几行 scan 'user_info', {LIMIT => 5} # 清空表（危险操作，谨慎） truncate 'user_info'Java API方面，最常用的是连接管理和CRUD：
Configuration conf = HBaseConfiguration.create(); conf.set("hbase.zookeeper.quorum", "zk1:2181,zk2:2181,zk3:2181"); Connection conn = ConnectionFactory.createConnection(conf); Table table = conn.getTable(TableName.valueOf("user_info")); Put put = new Put(Bytes.toBytes("user_001")); put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("phone"), Bytes.toBytes("13800001111")); table.put(put);这套基础会了之后，后续的协处理器和Phoenix操作才有下手的地方。很多连HBase都没跑通就直接问二级索引怎么搞，上来就卡壳，我建议先把环境折腾明白再往下走。
3. 二级索引四大实现方案拆解
3.1 方案一：基于协处理器（Observer）维护索引表
协处理器是HBase提供的框架，类似RDBMS里的触发器。用Observer协处理器拦截写请求，在Put数据到主表的同时，自动在索引表里写入一份索引数据。
这套方案的优势是业务代码无感知。应用只需要像往常一样Put数据，索引的构建和更新都在HBase服务端完成。缺点是协处理器部署在RegionServer上，改动是全局性的，代码出Bug容易影响集群稳定性；同时会带来额外的写放大。
协处理器适合有强一致要求、业务代码无法大面积改动的场景。我自己在风控和用户中心项目里正是用协处理器方案处理手机号、身份证等字段的索引。
3.2 方案二：使用Phoenix创建二级索引
Phoenix是一个基于HBase的SQL层，内置对二级索引的原生支持。在Phoenix里建表、建索引都走SQL，语法接近MySQL，对团队里的Java开发比较友好。
Phoenix支持三种索引类型：全局索引、覆盖索引、本地索引。全局索引适合读多写少的场景，覆盖索引把查询要的字段冗余进索引表，省去回主表，本地索引适合写多读少或分区数据量大的场景。
这套方案最大卖点是开箱即用，不用自己写协处理器。但Phoenix在复杂Join和超大表下会有性能瓶颈，并且很多底层的HBase优化行为会被SQL层包住，出问题排查起来要懂Phoenix也要懂HBase。
3.3 方案三：外部搜索引擎（Solr/ES）做索引
还有一种业界常见的思路：把HBase里需要被检索的列同步到Solr或Elasticsearch里，由搜索引擎负责反向索引和复杂查询，拿到RowKey后再回HBase取详情。
这套方案解决了HBase不擅长多维条件组合查询的短板，尤其适合全文检索、多维度模糊查询。缺点很明显：需要额外维护一套搜索引擎集群，数据同步链路过长，一致性很难保障。
我之前做过一个订单检索系统，就是Canal监听HBase的WAL，把更新事件同步到Solr。整体查询性能很猛，但是遇到跨机房网络抖动，索引同步延迟能到分钟级，业务方急得跳脚。
3.4 方案四：人工双写/应用层维护索引表
在数据量不大、索引字段很少的场景里，完全可以在业务代码里做双写：写主表的同时，再写一张索引表。比如用户注册时，Put用户信息后，又Put一条phone -> userId的索引记录。
这个方案控制力最强，也最原始，没有额外框架依赖。但业务代码侵入性大，稍不留神就会漏写、错写，而且分布式事务没法保证主表和索引表完全一致。
我建议只在数据量百万级以内、又不想引入重型框架的轻量项目里使用。真要在大数据量下长期跑，还是要靠协处理器、Phoenix这类相对可控的方案。
3.5 方案对比：怎么选才不后悔
先把四个方案放在同一张表里对比：
| 方案 | 一致性 | 开发量 | 运维成本 | 查询性能 | 适用场景 |
|---|---|---|---|---|---|
| 协处理器Observer | 高（依赖服务端） | 中 | 中 | 高 | 业务无感知、字段固定、写并发可控 |
| Phoenix索引 | 高（框架保证） | 低 | 中 | 中高 | 团队会SQL、快速上线 |
| Solr/ES外部索引 | 低（可能延迟） | 中 | 高 | 极高（复杂查询） | 全文检索、多维组合查询 |
| 应用层双写 | 低（开发易漏） | 低 | 低 | 高（自己控制） | 小数据量、轻量场景 |
选型时重点看两个指标：一是团队最擅长什么，二是索引字段会不会频繁变更。如果索引字段经常变，应用层双写和协处理器的改造代价都很大，倒不如上Phoenix直接改SQL；如果查询需求主要是组合条件模糊搜索，传统的列值索引也覆盖不了，Solr/ES才是正确选择。
4. 核心实操：用协处理器实现一个二级索引（手把手）
4.1 设计思路
协处理器方案里，我选择实现一个BaseIndexCoprocessor。核心机制是：拦截主表的postPut操作，在Put事件完成之后，把索引字段和主表RowKey的映射关系写入索引表。
我通常把索引表的RowKey设计成三部分组成：
MD5(列值)的前4位 + 列值 + 主表RowKey
MD5前缀用于打散Region热点，列值用于按条件定位，主表RowKey用于确保唯一。索引表的列族一般叫i，列名为ghost，value留空即可，反正索引只是标记。
拿用户表user_info举例，主表RowKey是user_001，需要索引的字段是列info:phone，那么索引表idx_user_phone里就写一条：
RowKey: 0a12 + 13800001111 + user_001，值无所谓。
查询时，先根据手机号拼出前缀范围，Scan索引表，拿到目标数据后，从RowKey末尾解析出主表RowKey，再去user_info里Get完整数据。
4.2 编写Observer代码
新建一个项目，依赖HBase的client包（版本与集群一致）。核心类如下：
package com.example.hbase; import org.apache.hadoop.hbase.Cell; import org.apache.hadoop.hbase.CellUtil; import org.apache.hadoop.hbase.CoprocessorEnvironment; import org.apache.hadoop.hbase.client.Durability; import org.apache.hadoop.hbase.client.Put; import org.apache.hadoop.hbase.client.Table; import org.apache.hadoop.hbase.coprocessor.BaseRegionObserver; import org.apache.hadoop.hbase.coprocessor.ObserverContext; import org.apache.hadoop.hbase.coprocessor.RegionCoprocessorEnvironment; import org.apache.hadoop.hbase.util.Bytes; import java.io.IOException; import java.security.MessageDigest; public class PhoneIndexCoprocessor extends BaseRegionObserver { private static final byte[] INDEX_TABLE = Bytes.toBytes("idx_user_phone"); private static final String INDEX_COLUMN_FAMILY = "info"; private static final String INDEX_COLUMN_QUALIFIER = "phone"; private static final byte[] INDEX_CF = Bytes.toBytes("i"); private static final byte[] GHOST = Bytes.toBytes("ghost"); @Override public void start(CoprocessorEnvironment env) { // 初始化（留空或加载配置） } @Override public void postPut(ObserverContext<RegionCoprocessorEnvironment> e, Put put, WALEdit edit, Durability durability) throws IOException { // 只有包含索引字段时才处理 Cell phoneCell = put.get(Bytes.toBytes(INDEX_COLUMN_FAMILY), Bytes.toBytes(INDEX_COLUMN_QUALIFIER)).get(0); if (phoneCell == null) { return; } String phone = Bytes.toString(CellUtil.cloneValue(phoneCell)); byte[] rowKey = put.getRow(); Table indexTable = e.getEnvironment().getTable(TableName.valueOf(INDEX_TABLE)); try { byte[] indexRowKey = buildIndexRowKey(phone, rowKey); Put indexPut = new Put(indexRowKey); indexPut.addColumn(INDEX_CF, GHOST, Bytes.toBytes("")); indexTable.put(indexPut); } finally { indexTable.close(); } } private byte[] buildIndexRowKey(String phone, byte[] originRowKey) throws IOException { byte[] md5Prefix = md5Prefix(phone); byte[] phoneBytes = Bytes.toBytes(phone); byte[] key = new byte[md5Prefix.length + phoneBytes.length + originRowKey.length]; int offset = 0; System.arraycopy(md5Prefix, 0, key, 0, md5Prefix.length); offset += md5Prefix.length; System.arraycopy(phoneBytes, 0, key, offset, phoneBytes.length); offset += phoneBytes.length; System.arraycopy(originRowKey, 0, key, offset, originRowKey.length); return key; } private byte[] md5Prefix(String value) throws IOException { try { MessageDigest md = MessageDigest.getInstance("MD5"); byte[] digest = md.digest(Bytes.toBytes(value)); return Bytes.toBytes(String.format("%02x%02x", digest[0], digest[1])); } catch (Exception e) { throw new IOException(e); } } }这里我没处理postDelete，实际项目里你还需要监听删除操作，把索引表里对应的RowKey删掉，否则会出现主表数据没了、索引还在的现象。另外，如果主表的Cell更新包含新手机号，也要考虑旧值索引失效的问题。最简单的处理方式是写之前先把旧值查出来，再清除老索引。
4.3 部署到HBase集群
代码写好打成jar包，放到所有RegionServer的lib目录下，比如$HBASE_HOME/lib/hbase-index-example.jar。然后必须重启RegionServer。
协处理器有两种挂载方式，一种在hbase-site.xml里配全局限，类似：
<property> <name>hbase.coprocessor.region.classes</name> <value>com.example.hbase.PhoneIndexCoprocessor</value> </property>另一种是只对某一张表生效，通过Shell或者HBase Admin动态添加：
disable 'user_info' alter 'user_info', METHOD => 'table_att', 'coprocessor' => 'hdfs:///path/to/hbase-index-example.jar|com.example.hbase.PhoneIndexCoprocessor|1001' enable 'user_info'注意：动态添加协处理器时必须先disable表，并且Coprocessor字符串由jar路径、类名、优先级三部分组成。优先级我习惯写1001，确保在默认流程之后生效。
4.4 测试验证
部署之后，往主表里插入一条带手机号的记录：
put 'user_info', 'user_001', 'info:phone', '13800001111'然后查索引表：
scan 'idx_user_phone', {LIMIT => 5}如果能看到类似38ba 13800001111 user_001这样的RowKey，说明索引写入成功。再模拟按手机号查询时，先Scan索引表：
scan 'idx_user_phone', {STARTROW => '38ba13800001111', ENDROW => '38ba13800001112'}拿到结果里的user_001，然后get 'user_info', 'user_001'即可。这思路放到真实代码里就是两次点查，性能远胜全表Scan。
实测下来，一个5000万行的用户表，全表Scan按手机号过滤平均耗时3秒多；同样条件下用索引表点查，平均耗时只有20毫秒左右。这个差距就是二级索引的价值所在。
5. 进阶：Phoenix二级索引实操与参数调优
5.1 Phoenix安装与表映射
Phoenix的安装相对省事。把Phoenix对应HBase版本的tar包解压，拷贝phoenix-server-hbase-2.4-*.jar到所有RegionServer的lib目录，重启RegionServer。然后客户端也用phoenix-client连接ZK地址：
./sqlline.py zk1:2181,zk2:2181,zk3:2181我建议让Phoenix管理表，直接用SQL建表，Phoenix会自动在HBase里创建对应物理表。如果要用已存在的HBase表做映射，得保证列名和类型匹配，这事比较考验细节，我一般直接建新表。
5.2 创建全局索引、覆盖索引、本地索引
Phoenix里建二级索引很容易，关键是搞清楚三种类型的区别。
全局索引（Global Index）：默认索引就是全局索引。适合读多写少。查询条件不带索引列时，Phoenix不走索引，容易全表扫，所以查询语句必须设计好。
CREATE INDEX IDX_USER_PHONE ON USER_INFO(PHONE);覆盖索引（Covered Index）：把查询时要返回的其他列也写进索引表，这样查索引表就能拿回全部数据，不用回主表。
CREATE INDEX IDX_USER_PHONE_COVER ON USER_INFO(PHONE) INCLUDE(USER_NAME, AGE);本地索引（Local Index）：索引数据和主表数据存储在同一个Region里，适合写多读少或者查询列经常变化的情况。建语法加LOCAL关键字：
CREATE LOCAL INDEX IDX_USER_PHONE_LOCAL ON USER_INFO(PHONE);本地索引牺牲了一点查询性能，换来了写入时的更低开销，生产上要根据读写比来选。
5.3 索引优化与运维注意事项
Phoenix索引在使用中有些参数值得单独调。phoenix.query.timeoutMs默认10秒，如果索引第一条查询就超时，先调大它跑通再说。phoenix.coprocessor.maxMetaDataCacheSize关系到元数据缓存，大表多索引的场景要适当上调。
还有一个容易踩的坑：全局索引遇到写入量大的场景，索引表的写放大比协处理器还要明显，因为Phoenix底层也是通过协处理器维护索引。这会导致RegionServer的CPU和内存飙升。降级手段是改成异步索引或先删索引、后批量重建。
运维层面，要定期用CALCULATE STATS收集统计信息，否则Phoenix的优化器会瞎猜。比如：
UPDATE STATISTICS USER_INFO;另外，重建索引的标准命令是ALTER INDEX ... REBUILD，在数据修复场景经常用。我可以明确说，凡是用了Phoenix的项目，必须要配套写一个索引重建脚本并定期演练，否则一旦索引表损坏，恢复手段都没得用。
6. 常见问题与排查技巧实录
6.1 索引不一致问题：主表有数据，索引表找不到
这个问题我在协处理器方案里遇到最多。最常见原因是：主表已有存量数据，而后加的二级索引只会对新写入的数据生效。
解决办法是先跑一遍全量补偿任务。把主表Scan一遍，对每条有索引字段的记录补写索引表。代码如下示意：
Scan scan = new Scan(); ResultScanner scanner = table.getScanner(scan); for (Result r : scanner) { if (r.containsColumn(Bytes.toBytes("info"), Bytes.toBytes("phone"))) { writeIndex(r.getRow(), r.getValue(...)); } }如果存量数据特别大，就用MapReduce或者Spark分Region并行补偿，别在线上单线程跑。
6.2 查询走了索引还是慢
这有两种可能：一是索引表本身没有预分区，导致索引RowKey全部打到一个Region上，热点问题让点查也变成排队等待；二是查询返回的列太多，回主表时是随机Get，大量小请求反而比Scan更慢。
我遇到过最典型的情况是：查询一条数据要带二十几个字段，用索引取回RowKey后逐个Get，结果性能比全表Scan还差。后来改成Phoenix覆盖索引，把高频字段冗余到索引表，才真正解决问题。
6.3 协处理器导致整个集群故障
协处理器代码必须保证绝对安全。有一次我在postPut里直接调用e.getEnvironment().getTable()获取索引表，结果RPC次数过多，严重的写放大把RegionServer打挂了。
后来优化为：统一维护一个共享的连接池，只在协处理器启动时初始化，而不是每次Put都新建连接。另外一个重要的点是，协处理器里不要跑太重的计算，实在要加密、哈希，尽量用廉价算法。
协处理器代码上线前，一定要在测试环境做全表写入的压测，观察RegionServer的JVM堆内内存和GC指标。一个新协处理器导致集群雪崩的案例我见过不止一次。
6.4 端口连不上、ZooKeeper会话超时
二级索引相关的排查中，环境问题也不少。单独把端口清单再拿出来说，是因为很多部署问题就出在端口上。客户端连HBase时默认走ZooKeeper的2181，如果hbase.zookeeper.quorum写错，或者防火墙没放行，客户端一直报Connection loss或者Session expired。
另一个常见问题是hbase.client.retries.number和hbase.client.pause设置过大，导致失败恢复时间过长。在线应用建议把重试次数从默认的10调低到3，超时时间从1秒调到2秒，快速失败比一直傻等更好。
6.5 避坑清单速查
| 坑位 | 原因 | 对策 |
|---|---|---|
| 索引表无预分区 | 写入热点 | 按索引字段哈希前缀预分区 |
| 存量数据无索引 | 索引只对增量生效 | 写补偿任务全量补建 |
| 覆盖列过多 | 索引表膨胀、写入慢 | 只冗余高频查询字段 |
| 协处理器连接泄漏 | 每Put新建连接 | 使用连接池或全局单例 |
| 索引列变更频繁 | 无法按现有索引查询 | RowKey设计提前考虑，或采用Phoenix索引 |
| 全局索引写放大 | Phoenix维护索引 | 评估写多读少则改本地索引 |
| 索引表损坏 | 数据异常或主动误删 | 定期REBUILD索引并演练 |
| 客户端重试过多 | 参数配置太激进 | 调低重试数，快速失败 |
经验之谈
说句大实话，二级索引并不是用得越高级越好。我们很多项目其实是被“大数据技术焦虑”带偏了，一上来就协处理器、Phoenix、Solr全上一遍，结果运维复杂度成倍增加。我的建议是：数据量在百万级，老老实实用应用层双写；数据量到了千万级且查询模式稳定，优先考虑协处理器或Phoenix；真出现多维模糊检索需求，再上外部搜索引擎也不迟。
我特别想提醒的一点是：不要把索引表当成一堆普通HBase表来管，它的预分区、压缩、BlockCache配置都要跟着主表一起设计，甚至要投入更多的关注。否则主表建得很优雅，索引表反而成了拖垮整个集群的那个“隐形杀手”。
最后留个实用小技巧：索引表平时要打开HFile的BLOOMFILTER，但由于索引RowKey本身已经带唯一前缀，BloomFilter只能加速“不存在”的查询，更多时候要靠BlockCache容量来提升点查的缓存命中，所以给索引表单独设置一个较大的CACHE_SIZE_IN_BYTES往往效果很明显。这个是我在一次调优中反复试出来的，比盲目加节点管用得多。
