--- title: "OBKV-HBase 弱读和就近读 - OceanBase 数据库 V4.4.2 | OceanBase 文档中心" description: OBKV-HBase 弱读和就近读 OBKV-HBase 支持弱一致性读和就近机房读特性，本文档介绍了弱读和就近读的原理、支持版本、路由策略、使用方法。 传统强一致性读模式，容易导致高并发或低延迟场景下的性能瓶颈。为此，OBKV-HBase 支持弱一致性读（Weak Read，下文简称弱读）和就近机房读（Near R… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库KV 型 - V 4.4.2 LTS # OBKV-HBase 弱读和就近读 更新时间：2026-07-23 19:56:22 [编辑](https://github.com/oceanbase/oceanbase-kv/edit/V4.4.2/zh-CN/200.obkv-hbase/700.obkv-hbase-reference/600.obkv-hbase-weak-read.md) OBKV-HBase 支持弱一致性读和就近机房读特性，本文档介绍了弱读和就近读的原理、支持版本、路由策略、使用方法。 传统强一致性读模式，容易导致高并发或低延迟场景下的性能瓶颈。为此，OBKV-HBase 支持弱一致性读（Weak Read，下文简称弱读）和就近机房读（Near Read，下文简称就近读），帮助用户更灵活地平衡数据一致性与访问效率。 ## 原理 想象一个场景，你的数据库部署在多个机房（比如北京、上海、广州），数据会复制多份。 ![弱读和就近读示例图](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer/kv/V4.4.2/%E5%BC%B1%E8%AF%BB%E5%92%8C%E5%B0%B1%E8%BF%91%E8%AF%BB%E7%A4%BA%E4%BE%8B%E5%9B%BE.png) 如果是传统强一致性读模式，客户端会优先选择主副本（Leader）进行读取，这样会导致两种问题： - Leader 压力大，容易成为性能瓶颈。且如果 Leader 故障，会导致整个机房不可用。 - 广州和上海的用户读取数据，也要经过北京机房，导致网络延迟增加。 因此，我们引入了弱读和就近读的方式来解决这个问题： - 弱读：允许客户端从非主副本（如 Follower 或 Replica）读取数据。此模式下读取数据会产生略微延迟，但能够提升读取性能和系统可用性。 - 就近读：客户端优先选择与自身地理位置或网络距离最近的机房副本读取数据，降低网络延迟，提高访问速度与用户体验。 ## 支持版本 使用本功能需要满足 OceanBase 集群、ODP 和 OBKV-HBase 客户端版本要求： | 组件 | 支持版本 | | --- | --- | | ObServer | 4.4.2.0 及以上 | | ODP | 4.3.6.2 | | OBKV-HBase | 2.5.0 | ## 直连模式使用步骤 ### 步骤一：配置 OceanBase 集群 IDC 使用 `root@sys` 登录 OceanBase 集群，按照以下步骤配置 OceanBase 集群的机房信息。假设集群包含三个 Zone，每个 Zone 下有一个 OBServer 节点，示例中每个 Zone 的 IP 分别为 10.0.0.1、10.0.0.2、10.0.0.3： 1. 设置 `z1` 的地区。`REGION` 参数用于指定 Zone 所在的地域信息，建议使用城市名（大小写敏感）。 ```sql ALTER SYSTEM MODIFY ZONE "z1" SET REGION = "SHANGHAI"; ``` 2. 设置 `z1` 的机房。`IDC` 参数用于指定 Zone 所在的机房信息，建议使用机房名（小写）。 ```sql ALTER SYSTEM MODIFY ZONE "z1" SET IDC = "zue"; ``` 完成后，集群部署情况如下表所示： | OBServer 节点 IP | Zone | IDC | Region | | --- | --- | --- | --- | | 10.0.0.1 | z1 | zue | SHANGHAI | | 10.0.0.2 | z2 | xue | SHANGHAI | | 10.0.0.3 | z3 | yue | HANGZHOU | ### 步骤二：配置客户端弱读参数 #### 参数说明 设置弱读的关键参数如下表所示： | 参数 | 类型 | 是否大小写敏感 | 可选值 | 默认值 | 说明 | | --- | --- | --- | --- | --- | --- | | hbase.htable.read.consistency | String | 否 | "strong"、"weak" | "strong" | - 一致性级别，用于控制是否开启弱读。 - 参数值为 "weak" 时，代表开启弱读。 - 弱读只对 get（包括 list）、scan 等读取接口生效，数据插入、更新、删除等不生效。 | | hbase.htable.client.idc | String | 否 | 实际机房名 | "" | - 客户端所在机房名 - ODP 模式无需配置此参数 - 如果设置了客户端所在机房，**弱读选择副本的优先级为：同机房 > 同地区 > 其他地区** | | hbase.htable.client.route.policy | String | 否 | "follower_first"、"follower_only" | "follower_first" | - 路由策略 - ODP 模式无需配置此参数 - "follower_first"：优先选择 follower 进行读取，如果没有 follower 可以读取，则选择 leader 读取。 - "follower_only" ：只选择 follower 进行读取，如果没有 follower 可以读取，则抛出异常。这种方式可以强制分流，保护主副本不被读取压力打垮，但可能会导致读取性能下降。 | 参数设置优先级说明：目前 OBKV-HBase 支持全局参数和语句级别参数两种优先级，**优先级为：语句级别参数 > 全局级别参数**。以下列出支持的几种具体设置方式。 #### 在配置文件中设置弱读全局参数 此方法适用于从原生 HBase 平滑迁移到 OBKV-HBase，且无需修改已有业务代码。你只需在 `hbase-site.xml` 或 `core-site.xml` 配置文件中设置弱读全局参数，便可实现弱读能力。 如下示例，通过在 `hbase-site.xml` 文件中设置 "hbase.htable.read.consistency" 为 "weak"，"hbase.htable.client.idc" 为 "idc1"，"hbase.htable.client.route.policy" 为 "follower_first"，即可让查询操作优先路由到 "idc1" 机房的 follower 副本进行读取。 ```xml hbase.htable.read.consistency weak hbase.htable.client.idc idc1 hbase.htable.client.route.policy follower_first ``` #### 在代码中设置弱读全局参数 此方法适用于需要修改代码的业务，你只需在代码中设置弱读全局参数，便可实现弱读能力。如下示例，通过在 `configuration` 中设置 "hbase.htable.client.idc" 为 "idc1"，"hbase.htable.client.route.policy" 为 "follower_first"，"hbase.htable.read.consistency" 为 "weak"，即可让查询操作优先路由到 "idc1" 机房的 follower 副本进行读取。 ```java import static com.alipay.oceanbase.hbase.constants.OHConstants.*; Configuration config = HBaseConfiguration.create(); config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // 设置客户端机房信息 config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // 设置路由策略 config.set(HBASE_HTABLE_READ_CONSISTENCY, "weak"); // 设置一致性级别 ``` #### 在代码中设置语句级别弱读参数 此方法适用于需要修改代码的业务，你只需在代码中设置语句级别弱读参数，便可实现弱读能力。 这里给出几个不同场景的使用示例： get 示例 list 示例 scan 示例 如下示例先在 `configuration` 中设置了 "hbase.htable.client.idc" 为 "idc1"，"hbase.htable.client.route.policy" 为 "follower_first"；然后在 get 操作中，通过 setAttribute 设置 "hbase.htable.read.consistency" 为 "weak"。这样，在执行 get 操作时，会优先路由到 "idc1" 机房的 follower 副本。 ```java String tableName = "test"; Configuration config = HBaseConfiguration.create(); config.set(HBASE_HTABLE_CLIENT_IDC, "idc1"); // 设置客户端机房信息 config.set(HBASE_HTABLE_CLIENT_ROUTE_POLICY, "follower_first"); // 设置路由策略 Connection hbaseConnection = ConnectionFactory.createConnection(config); Table table = hbaseConnection.getTable(TableName.valueOf(tableName)); String family = "cf1"; String rowkey = "k1"; Get get = new Get(rowkey.getBytes()); get.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // 设置语句级别读一致性 get.addColumn(family.getBytes(), "q1".getBytes()); Result result = table.get(get); ``` 如下示例先在 `configuration` 中设置了 "hbase.htable.client.idc" 为 "idc1"，"hbase.htable.client.route.policy" 为 "follower_first"；然后在 `list` 操作中，通过 setAttribute 设置 "hbase.htable.read.consistency" 为 "weak"。这样，在执行 `list` 操作时，会优先路由到 "idc1" 机房的 follower 副本。 List gets = new ArrayList<>(); String family = "cf1"; String rowkey1 = "k1"; // 同一批 get 中必须设置全部弱读，不支持部分弱读 Get get1 = new Get(rowkey1.getBytes()); get1.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // 设置语句级别读一致性 get1.addColumn(family.getBytes(), "q1".getBytes()); String rowkey2 = "k2"; Get get2 = new Get(rowkey2.getBytes()); get2.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // 设置语句级别读一致性 get2.addColumn(family.getBytes(), "q2".getBytes()); gets.add(get1, get2); Result[] res = table.get(gets); ``` 示例先在 `configuration` 中设置了 "hbase.htable.client.idc" 为 "idc1"，"hbase.htable.client.route.policy" 为 "follower_first"；然后在 scan 操作中，通过 setAttribute 设置 "hbase.htable.read.consistency" 为 "weak"。这样，在执行 scan 操作时，会优先路由到 "idc1" 机房的 follower 副本。 String family = "cf1"; String rowkey = "k1"; Scan scan = new Scan(); scan.withStartRow(rowkey.getBytes()); scan.setAttribute(HBASE_HTABLE_READ_CONSISTENCY, "weak".getBytes()); // 设置语句级别读一致性 scan.addColumn(family.getBytes(), "q1".getBytes()); ResultScanner resultScanner = table.getScanner(scan); Result result; while ((result = resultScanner.next()) != null) { byte[] value = result.getValue(family.getBytes(), "q1".getBytes()); } ``` ## ODP 模式使用步骤 ### 步骤一：配置 OceanBase 集群 IDC 使用 `root@sys` 登录 OceanBase 集群，按照以下步骤配置集群的机房与地区信息。假设集群包含三个 Zone，每个 Zone 下有一个 OBServer 节点，以下以 z1 的配置为例： 1. 设置 z1 的地区。`REGION` 参数用于指定 Zone 所在地域信息，建议设置为城市名（大小写敏感）。 ``` 2. 设置 z1 的机房。`IDC` 参数用于指定 Zone 所在机房信息，建议设置为机房实际名称（小写）。 ``` 完成后，集群部署信息如下表所示： ### 步骤二：配置 ODP 弱读参数 1. 通过设置 `proxy_idc_name` 参数，可以指定 ODP 在 LDC 体系中所属的机房，结合实际部署，可以让弱读流量更优地路由到对应机房的副本。比如，将所有弱读请求优先路由至 z1 所在的机房，可参考如下配置： ```sql ALTER PROXYCONFIG SET proxy_idc_name = 'zue'; ``` 2. 通过设置 `proxy_route_policy` 参数，可以进一步指定副本路由策略。下例为优先读取 Follower 副本： ```sql ALTER PROXYCONFIG SET proxy_route_policy = 'follower_first'; ``` ### 步骤三：配置客户端弱读参数 参考 `直连模式使用步骤-步骤二：配置客户端弱读参数` 中的示例，设置弱读参数。 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线