# HBase 升级
> 贡献者：[xixici](https://github.com/xixici)
当你想要升级时，你不能跳过主要版本。当你从版本 0.98.x 到 2.x 时，你必须首先升级到 1.2.x 再从 1.2.x 升级到 2.x。
回顾 [Apache HBase 配置](#configuration)章节，还有 [Hadoop](https://hadoop.apache.org)，并熟悉 [支持和测试](#hbase_supported_tested_definitions).
## 11\. HBase 版本号和兼容性
### 11.1\. 期望语义版本控制
从版本 1.0.0 开始，HBase 采用 [Semantic Versioning](http://semver.org/)作为版本控制。
对于给定的版本号 MAJOR.MINOR.PATCH，增加如下内容：
MINOR 版本，当您以向后兼容的方式添加功能时
PATCH 版本，当您进行向后兼容的错误修复时
预发布和构建元数据的其他标签可作为 MAJOR.MINOR.PATCH 格式的扩展。
* MAJOR 版本，当你进行不兼容的 API 更改时
* MINOR 版本，当您以向后兼容的方式添加功能时
* PATCH 版本，当您进行向后兼容的错误修复时
* 预发布和构建元数据的其他标签可作为 MAJOR.MINOR.PATCH 格式的扩展。
兼容性维度
除了通常的 API 版本考虑之外，HBase 还有其他需要考虑的兼容性维度。
Client-Server 线协议兼容性：
* 允许不同步更新客户端和服务器。
* 我们只能允许先升级服务器。也就是说，服务器将向后兼容旧客户端，这样新的 API 就可以使用。
* 示例：用户应该能够使用旧客户端连接到升级的群集。
Server-Server 协议兼容性：
* 不同版本的服务器可以共存于同一个群集中。
* 服务器之间的有线协议是兼容的。
* 分布式任务的工作人员（如复制和日志拆分）可以共存于同一个群集中。
* 相关协议（如使用 ZK 进行协调）也不会改变。
* 示例：用户可以执行滚动升级。
文件格式兼容性：
* 支持文件格式向前和向后兼容
* 示例：文件、ZK 编码、目录布局自动升级为 HBase 升级的一部分。用户可以降级到旧版本，并且一切都将继续工作。
客户端 API 兼容性：
* 允许更改或删除现有的客户端 API。
* 在我们更改/删除主要版本之前，API 需要被弃用。
* 修补程序（patch）版本中提供的 API 将在所有后续修补程序版本中提供。但是，可能会添加新的 API，这些 API 在以前的修补程序版本中将不可用。
* 修补程序版本中引入的新 API 只能以源代码兼容的方式添加：即实现公共 API 的代码将继续编译<sup class="footnote">[[1](#_footnote_1 "View footnote.")]</sup>:。示例：使用新废用的 API 的用户不需要使用 HBase API 调用修改应用程序代码，直到下一个主要版本。
* 示例：在下一个主要版本之前，使用新弃用的 API 的用户不需要修改应用程序的 HBase API 调用代码。
客户端二进制兼容性：
* 写入给定修补程序版本中提供的 API 的客户端代码可以运行不变（不需要重新编译），以抵补新的 jar 后续补丁版本。
* 写入给定修补程序版本中提供的 API 的客户端代码可能无法针对早期修补程序版本中的旧 jar 运行。示例：旧编译的客户端代码将在 jar 中保持不变。
* 示例：旧编译的客户端代码将在 jar 中保持不变。
* 如果客户端实现 HBase 接口，则可能需要重新编译升级到较新的次要（minor）版本。
服务器端有限的 API 兼容性（取自 Hadoop）：
* 内部 API 被标记为“稳定（Stable）”，“正在发展（Evolving）”或“不稳定（Unstable）”。
* 这意味着协处理器和插件（可插入类，包括复制）的二进制兼容性，只要这些只使用标记的接口/类。
* 例如：旧编译的协处理器，过滤器或插件代码将在新 jar 中保持不变。
相关性兼容性：
* HBase 的升级除 Apache Hadoop 外，不需要依赖项目的兼容升级，包括运行 Java 时。
* HBase 的升级不需要依赖项目的兼容升级，包括 Java 。
* 示例：将 HBase 升级到支持 _ 依赖兼容性 _ 的版本不需要升级 Apache ZooKeeper 服务。
* 示例：示例：如果当前版本的 HBase 支持在 JDK 8 上运行，则升级到支持 _ 依赖兼容性 _ 的版本也将在 JDK 8 上运行。
> Hadoop 版本
>
> 之前，我们尝试维护基础 Hadoop 服务的依赖兼容性，但在过去几年中，这已经证明是站不住脚的。 虽然 HBase 项目试图维持对旧版本 Hadoop 的支持，但我们删除了次要版本的“受支持”指示符。 此外，Hadoop 项目有自己的一组兼容性指南，这意味着在某些情况下，会破坏指南，也就是必须更新到较新的受支持的次要版本。
操作兼容性：
* 度量标准的更改
* 服务的行为变化
* 通过 `/jmx/` 端点公开的 JMX API
概要
* 修补程序（patch）升级是一种直接替代方案。任何不是 Java 二进制和源代码兼容的更改都将不被允许<sup class="footnote">[[2](#_footnote_2 "View footnote.")]</sup>。在修补程序版本中降级版本可能不兼容。
* 次要（minor）升级不需要修改应用程序/客户端代码。理想情况下，这将是一个直接替换，但如果使用新的 jar，则客户端代码，协处理器，过滤器等可能必须重新编译。
* 主要（major）升级允许 HBase 做出重大改变。
| | Major | Minor | Patch |
| --- | --- | --- | --- |
| 客户端 - 服务器线路兼容性 | N | Y | Y |
| 服务器 - 服务器兼容性 | N | Y | Y |
| 文件格式兼容性 | N <sup class="footnote">[[4](#_footnote_4 "View footnote.")]</sup> | Y | Y |
| 客户端 API 兼容性 | N | Y | Y |
| 客户端二进制兼容性 | N | N | Y |
| 服务器端有限的 API 兼容性 |
| 稳定性（Stable） | N | Y | Y |
| 发展性（Evolving） | N | N | Y |
| 不稳定性（Unstable） | N | N | N |
| 相关性兼容性 | N | Y | Y |
| 操作兼容性 | N | N | Y |
#### 11.1.1\. HBase API
HBase 有很多 API 要点，但对于上面的兼容性矩阵，我们区分了 Client API（客户端 API），Limited Private API（有限的私有 API）和 Private API（私有 API）。HBase 使用 [Apache Yetus Audience Annotations](https://yetus.apache.org/documentation/0.5.0/interface-classification/) 来定义稳定性
* InterfaceAudience ([javadocs](https://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceAudience.html)): 捕捉预期的受众，可能的值包括：
* Public：对于最终用户和外部项目是安全的；
* LimitedPrivate：用于我们期望可插入的内部组件，如协处理器；
* Private：严格用于 HBase 自身内部定义为 IA 的类中，Private 可以用作声明 `IA.LimitedPrivate` 接口的参数或返回值。将`IA.Private`对象视为不透明；不要尝试直接访问其方法或字段。
* InterfaceStability ([javadocs](https://yetus.apache.org/documentation/0.5.0/audience-annotations-apidocs/org/apache/yetus/audience/InterfaceStability.html)): 描述允许接口更改的类型。可能的值包括：
* Stable：接口是固定的，预计不会改变；
* Evolving：界面可能会在未来的 minor 版本中改变；
* Unstable：界面可能随时更改
请记住 HBase 项目中 `InterfaceAudience` 注释和 `InterfaceStability` 注释之间的以下相互作用：
* `IA.Public` 类本质上是稳定的，并坚持我们有关升级类型（主要，次要或修补程序）的稳定性保证。
* `IA.LimitedPrivate` 类应始终使用给定的 `InterfaceStability` 值的其中一个进行注释。如果他们不是，你应该假定他们是 `IS.Unstable`。
* `IA.Private` 类应该被认为是隐含不稳定的，不能保证发布之间的稳定性。
HBase Client API
HBase 客户端 API 由所有标记有 InterfaceAudience.Public 接口的类或方法组成。hbase-client 和依赖模块中的所有主类都有 InterfaceAudience.Public，InterfaceAudience.LimitedPrivate 或 InterfaceAudience.Private 标记。并非所有其他模块（hbase-server 等）中的类都有标记。如果一个类没有使用上述中的一个注释，则它被认为是一个 InterfaceAudience.Private 类。
HBase LimitedPrivate API
LimitedPrivate 注释为接口附带了一组目标使用者。这些使用者是协处理器，phoenix，复制端点实现等。此时，HBase 只能保证修补程序版本之间的这些接口的源和二进制兼容性。
HBase Private API
所有使用 InterfaceAudience.Private 注释的类或没有注释的所有类仅在 HBase 内部使用。接口和方法签名可以随时改变。如果您依赖于标记为 Private 的特定界面，则应打开 jira 以建议将界面更改为 Public 或 LimitedPrivate，或者为此目的公开的接口。
二进制兼容性：
当我们说两个 HBase 版本是兼容的时，我们的意思是这些版本是线（wire）和二进制兼容的。兼容的 HBase 版本意味着客户可以与兼容但不同版本的服务器通话。这也意味着你可以换出一个版本的 jar，并用另一个兼容版本的 jar 替换它们，所有的 jar 都可以工作。除非另有说明，否则 HBase 主要的版本都是二进制兼容的。您可以安全地在二进制兼容版本之间进行滚动升级。例如从 1.2.4 到 1.2.6\.详见:[Does compatibility between versions also mean binary compatibility?] 在 HBase 论坛的讨论。
### 11.2\. 滚动升级
滚动升级是您一次更新服务器群集中的服务器的过程。如果它们是二进制或线路兼容的，则可以跨 HBase 版本进行滚动升级。详见：[Rolling Upgrade Between Versions that are Binary/Wire Compatible](#hbase.rolling.restart) 粗略地说，滚动升级是正常地停止每台服务器，更新软件，然后重新启动。您可以为集群中的每个服务器执行此操作。通常先升级 Master，然后再升级 RegionServers。 查看 [Rolling Restart](#rolling)
例如，下面的 HBase 是 symlinked 实际的 HBase 安装。在升级之前，在群集上运行滚动重启之前，我们将 symlink 更改为指向新的 HBase 软件版本，然后运行：
```
$ HADOOP_HOME=~/hadoop-2.6.0-CRC-SNAPSHOT ~/hbase/bin/rolling-restart.sh --config ~/conf_hbase
```
滚动重新启动脚本将首先正常停止并重新启动主服务器，然后依次重新启动每个 RegionServer。由于 symlink 被更改，所以重新启动时，服务器将使用新的 HBase 版本。随着滚动升级的进行，检查日志中是否有错误。
在兼容二进制/Wire 的版本之间进行滚动升级：
除非另有说明，否则 HBase 指向的版本是二进制兼容的。您可以在 HBase 主要版本之间进行[滚动升级](#hbase.rolling.upgrade)。例如，您可以通过在集群中进行滚动升级，使用 0.94.6 二进制文件替换 0.94.5 二进制文件，从而从 0.94.5 转到 0.94.6。
在次要（minor）版本中，我们调用的版本是有线/协议兼容的，在这种情况下，也可以执行[滚动升级](#hbase.rolling.upgrade)。
## 12\. 版本恢复
当你在试着升级 HBase 的时候，你可能会遇到升级失败的问题，并且想要将其恢复成之前的版本。本节就介绍如何执行 _ 回滚 _ 以将 HBase 恢复为到较早的版本。请注意，这应该只在主要版本和一些次要版本之间需要。您应该始终能够在相同次要版本的 HBase Patch 版本之间进行 _ 降级 _。这些说明可能要求您在开始升级过程之前注意相关的事项，因此请务必事先阅读本节。
### 12.1\. 警告
回滚与降级
本节介绍如何对 HBase 次要版本和主要版本之间的升级执行回滚。在本文档中，回滚指的是采取升级后的集群并将其恢复到旧版本的过程，同时 _ 丢失升级后发生的所有更改 _。相比之下，群集降级会将升级后的群集恢复到旧版本，同时保留升级后写入的任何数据。我们目前仅提供回滚 HBase 集群的说明。此外，只有在执行升级之前遵循这些说明，回滚才有效。
当这些指令谈论回滚与降级的先决条件群集服务（即 HDFS）时，您应该将服务版本与退化的降级案例视为相同。
复制
除非您正在执行全部服务回滚，否则 HBase 群集将会丢失任何配置的对等 HBase 复制。如果您的集群配置为 HBase 复制，那么在按照这些说明[Managing and Configuring Cluster Replication](#hbase.replication.management)进行操作之前，您应该记录所有复制节点。执行回滚之后，您应该将每个记录的对等点添加回群集。另外要注意，自升级后写入群集的数据可能已经或可能未被复制到任何对等方。
数据位置
除非您正在执行全部服务回滚，否则通过回滚过程可能会破坏 Region Server 的所有局部位置。在群集有时间通过紧凑排列恢复数据位置之前，您应该期望性能的降级。或者，您可以强制压缩来加速此过程，但要以生成群集负载为代价。
可配置的位置
以下说明假设 HBase 数据目录和 HBase znode 的默认位置。这两个位置都是可配置的，您应该在继续操作之前验证群集中使用的值。如果您有不同的值，只需将默认值替换为在配置中找到的 HBase 数据目录，它是通过密钥 "HBase" (rootdir) 配置的，并且具有默认的 "/HBase"。* HBase znode 通过密钥'zookeeper.znode.parent'进行配置，默认值为'/ hbase'。
### 12.2\. 所有服务回滚
如果您要执行 HDFS 和 ZooKeeper 服务的回滚，那么 HBase 的数据将在此过程中回滚。
要求
* 能够回滚 HDFS 和 ZooKeeper
升级前
在升级前不需要额外的步骤。作为一项额外的预防措施，您可能希望使用 distcp 将 HBase 数据备份到要升级的群集之外。为此，请本节内容中的按照“HDFS 降级后回滚”的“升级前”部分中的步骤操作，但它是复制到另一个 HDFS 实例，而不是在同一实例中。
执行回滚
1. 停止 HBase
2. 执行 HDFS 和 ZooKeeper 的回滚（HBase 应该保持停止状态）
3. 将安装的 HBase 版本更改为以前的版本
4. 启动 HBase
5. 验证 HBase 内容 - 使用 HBase shell 列出表格并扫描一些已知值。
### 12.3\. HDFS 回滚和 ZooKeeper 降级后回滚
如果您将回滚 HDFS，但通过 ZooKeeper 降级，那么 HBase 将处于不一致的状态。在完成此过程之前，您必须确保集群未启动。
要求
* 能够回滚 HDFS
* 能够降级 ZooKeeper
升级前
在升级前不需要额外的步骤。作为一种额外的预防措施，您可能希望使用 distcp 将 HBase 数据备份到要升级的群集之外。为此，请本节内容中的按照“HDFS 降级后回滚”的“升级前”部分中的步骤操作，但它将复制到另一个 HDFS 实例，而不是在同一实例中。
执行回滚
1. 停止 HBase
2. 执行 HDFS 回滚和 ZooKeeper 降级（HBase 应该保持停止状态）
3. 将安装的 HBase 版本更改为以前的版本
4. 清除与 HBase 相关的 ZooKeeper 信息。警告：此步骤将永久销毁所有复制对等点。
清理 ZooKeeper 中的 HBase 信息
```
[hpnewton@gateway_node.example.com ~]$ zookeeper-client -server zookeeper1.example.com:2181,zookeeper2.example.com:2181,zookeeper3.example.com:2181
Welcome to ZooKeeper!
JLine support is disabled
rmr /hbase
quit
Quitting...
```
5. 启动 HBase
6. 验证 HBase 内容 - 使用 HBase shell 列出表格并扫描一些已知值。
### 12.4\. HDFS 降级后回滚
如果您要执行 HDFS 降级，则无论 ZooKeeper 是否通过回滚、降级或重新安装，您都需要遵循这些指示信息。
要求
* 可以降级 HDFS
* 升级前群集必须能够运行 MapReduce 作业
* HDFS 超级用户访问
* 在 HDFS 中至少有两个 HBase 数据目录的副本空间可以降级 HDFS
升级前
在开始升级过程之前，您必须对 HBase 的支持数据进行完整备份。以下说明介绍了在当前 HDFS 实例中备份数据的过程。或者，您可以使用 distcp 命令将数据复制到另一个 HDFS 群集。
1. 停止 HBase 群集
2. 将 HBase 数据目录复制到备份位置, 方法[distcp command](https://hadoop.apache.org/docs/current/hadoop-distcp/DistCp.html)是使用 distcp 命令作为 HDFS 超级用户 (下面显示在启用安全的群集上)
使用 distcp 备份 HBase 数据目录：
```
[hpnewton@gateway_node.example.com ~]$ kinit -k -t hdfs.keytab hdfs@EXAMPLE.COM
[hpnewton@gateway_node.example.com ~]$ hadoop distcp /hbase /hbase-pre-upgrade-backup
```
3. Distcp 将启动一个 mapreduce 作业来处理以分布式方式复制文件。检查 distcp 命令的输出，以确保此作业成功完成。
执行回滚
1. 停止 HBase
2. 执行 HDFS 的降级和 ZooKeeper 的降级/回滚（HBase 应该保持停止状态）
3. 将安装的 HBase 版本更改为以前的版本
4. 将 HBase 数据目录从升级前恢复为 HDFS 超级用户 (如下所示在启用安全的群集上)。如果您将数据备份到另一个 HDFS 群集而不是本地，则需要使用 distcp 命令将其复制回当前的 HDFS 群集。
恢复 HBase 数据目录：
```
[hpnewton@gateway_node.example.com ~]$ kinit -k -t hdfs.keytab hdfs@EXAMPLE.COM
[hpnewton@gateway_node.example.com ~]$ hdfs dfs -mv /hbase /hbase-upgrade-rollback
[hpnewton@gateway_node.example.com ~]$ hdfs dfs -mv /hbase-pre-upgrade-backup /hbase
```
5. 清除与 HBase 相关的 ZooKeeper 信息。警告：此步骤将永久销毁所有复制对等点。
清理 ZooKeeper 中的 HBase 信息：
```
[hpnewton@gateway_node.example.com ~]$ zookeeper-client -server zookeeper1.example.com:2181,zookeeper2.example.com:2181,zookeeper3.example.com:2181
Welcome to ZooKeeper!
JLine support is disabled
rmr /hbase
quit
Quitting...
```
6. 启动 HBase
7. 验证 HBase 内容 - 使用 HBase shell 列出表格并扫描一些已知值。
## 13\. HBase 升级路径
### 13.1\. 从 1.x 升级到 2.x
在本节中，先前稳定的 HBase 版本相比所发生的重大变化，一定要仔细阅读，然后再进行升级。以免发生意外。
#### 13.1.1\. 变化通告
首先，我们将介绍升级到 HBase 2.0+时可能遇到的部署/操作更改。之后，我们将告知下游应用程序的更改。请注意，协处理器包含在操作部分中。另外请注意，本节并不旨在传达您可能感兴趣的新功能的信息。有关更改的完整摘要，请参阅您计划升级到的版本的源发布工件中的 changes.txt 文件。
更新到 HBase 2.0+的基本最低先决条件
如之前章节所述 [Basic Prerequisites](#basic.prerequisites), HBase 2.0+ 需要依赖 Java 8 和 Hadoop 2.6\. HBase 社区建议在升级您的 HBase 版本之前，确保您已经完成了任何必要的先决条件升级。
HBCK 一定要匹配 HBase 版本
**一定不要**在 HBase 2.0+ 集群上使用 HBase 1.x 版本的 HBCK。 HBCK 是严格绑定 HBase 版本的。 对 hbase 2.0+集群使用早期版本的 hbck 工具将以不可恢复的方式破坏性地改变集群。
从 HBase 2.0 开始， HBCK (也叫做 _HBCK1_ 或 _hbck1_)是一个只读工具，可以报告某些非公共系统内部的状态。您不应该依赖这些内部构件的格式和内容来保持 HBase 版本之间的一致性。
替代品详见： [HBase `HBCK2`](#HBCK2) 和 [Apache HBase Operational Management](#ops_mgt).
配置设置不再位于 HBase 2.0+
下列配置设置不再适用或不可用。有关详细信息，请参阅详细的发行说明。
* hbase.config.read.zookeeper.config (查看 [ZooKeeper configs no longer read from zoo.cfg](#upgrade2.0.zkconfig) )
* hbase.zookeeper.useMulti (HBase 现在使用 ZK’s multi functionality)
* hbase.rpc.client.threads.max
* hbase.rpc.client.nativetransport
* hbase.fs.tmp.dir
* hbase.bucketcache.combinedcache.enabled
* hbase.bucketcache.ioengine 不再支持 'heap' 值.
* hbase.bulkload.staging.dir
* hbase.balancer.tablesOnMaster 严格地说，它并没有被删除，但它的意义已经发生了根本性的改变，用户不应该设置它。详见： ["Master hosting regions" feature broken and unsupported](#upgrade2.0.regions.on.master)
* hbase.master.distributed.log.replay 详见： ["Distributed Log Replay" feature broken and removed](#upgrade2.0.distributed.log.replay)
* hbase.regionserver.disallow.writes.when.recovering 详见： ["Distributed Log Replay" feature broken and removed](#upgrade2.0.distributed.log.replay)
* hbase.regionserver.wal.logreplay.batch.size 详见： ["Distributed Log Replay" feature broken and removed](#upgrade2.0.distributed.log.replay)
* hbase.master.catalog.timeout
* hbase.regionserver.catalog.timeout
* hbase.metrics.exposeOperationTimes
* hbase.metrics.showTableName
* hbase.online.schema.update.enable (HBase 不再支持)
* hbase.thrift.htablepool.size.max
在 HBase 2.0+重命名的配置属性
已重命名以下属性。在运行时设置旧属性将失败。
| 旧名称 | 新名称 |
| --- | --- |
| hbase.rpc.server.nativetransport | hbase.netty.nativetransport |
| hbase.netty.rpc.server.worker.count | hbase.netty.worker.count |
| hbase.hfile.compactions.discharger.interval | hbase.hfile.compaction.discharger.interval |
| hbase.hregion.percolumnfamilyflush.size.lower.bound | hbase.hregion.percolumnfamilyflush.size.lower.bound.min |
在 HBase 2.0+中具有不同默认值的配置
以下配置设置更改了它们的默认值。在适用的情况下，将给出 hbase 1.2 行为的设置值。
* hbase.security.authorization 默认 false. 之前版本的 default 是 true
* hbase.client.retries.number 现在默认 10\. 之前默认 35\.建议下游用户使用 [Timeout settings](#config_timeouts) 所述的客户端超时。
* hbase.client.serverside.retries.multiplier 现在默认 3\. 之前默认 10\.建议下游用户使用 [Timeout settings](#config_timeouts) 所述的客户端超时。
* hbase.master.fileSplitTimeout 默认 10 分钟，之前是 30 秒
* hbase.regionserver.logroll.multiplier 默认 0.5\之前 0.95\. 此更改与下面的块大小加倍有关。结合起来，这两个配置更改应该使 WAL 的大小与 HBase-1.x 中的大小大致相同，但是小块的发生率应该更低，因为在达到块大小阈值之前，我们无法滚动 WAL。
详见： [HBASE-19148](https://issues.apache.org/jira/browse/HBASE-19148)
* hbase.regionserver.hlog.blocksize 默认为 wal dir 的 hdfs 默认块大小的 2 倍。以前它等于 wal dir 的 hdfs 默认块大小。
* hbase.client.start.log.errors.counter 更改为 5,以前是 9
* hbase.ipc.server.callqueue.type 改为“FIFO”。在 HBase 版本 1.0-1.2 中，这是“最后期限”。在之前和之后的 1.x 版本中，它已经默认为“FIFO”。
* hbase.hregion.memstore.chunkpool.maxsize 默认为 1.0, 之前是 0.0. 实际上，这意味着以前当 memstore onheap 时，我们不会使用区块池，现在我们将使用。有关 mslab 区块池的更多信息，请参阅[Long GC pauses](#gcpause)
* hbase.master.cleaner.interval 默认为 10 分钟, 之前是 1 分钟.
* hbase.master.procedure.threads 现在将默认为可用 CPU 数量的 1/4，但不少于 16 个线程。以前，线程数等于 CPU 数。
* hbase.hstore.blockingStoreFiles 现在是 16。以前是 10。
* hbase.http.max.threads 现在是 16。以前是 10。
* hbase.client.max.perserver.tasks 现在是 2。以前是 5
* hbase.normalizer.period 现在是 5 分钟。以前是 30 分钟.
* hbase.regionserver.region.split.policy 现在是步进式分割策略。以前，它增加边界区域策略。
* replication.source.ratio 现在是 0.5。以前是 0.1.
“主托管区域”功能已损坏且不受支持
hbase 1.y 中的“master 充当区域服务器”功能和相关后续工作在 hbase 2.y 中不起作用，不应在生产设置中使用，因为 master 初始化时出现死锁。建议下游用户将相关的配置设置视为实验性的，并将该功能视为不适合生产设置。
相关变更的简要概述：
* 默认情况下，Master 不再承载区域
* hbase.balancer.tablesonmaster 是一个布尔值，默认为 false（如果它包含 hbase 1.x 表列表，则默认为 false）
* hbase.balancer.tablesonmaster.systemtablesonly 是保持用户表远离 master 的布尔值。缺省假
* 那些希望复制旧服务器列表配置的人应该部署一个独立的区域服务器进程，然后依赖于区域服务器组。
“分布式日志回放”功能已中断并已删除
分布式日志重播功能已损坏，已从 hbase 2.y+中删除。因此，所有相关的配置、度量、RPC 字段和日志记录都已被删除。请注意，在运行到 hbase 1.0 时发现此功能不可靠，默认为未使用，当我们开始忽略打开该功能的配置时 ([HBASE-14465](https://issues.apache.org/jira/browse/HBASE-14465))，它在 hbase 1.2.0 中被有效删除。如果您当前正在使用该功能，请确保执行干净的关机，确保完成所有 DLR 工作，并在升级之前禁用该功能。
_prefix-tree_ 编码移除
前缀树编码已从 hbase 2.0.0 中删除([HBASE-19179](https://issues.apache.org/jira/browse/HBASE-19179))。在 HBase-1.2.7、HBase-1.4.0 和 HBase-1.3.2 中已弃用。
此功能被删除，因为它未被积极维护。如果有兴趣恢复这种可以在慢写代价高昂的情况下改善随机读取延迟的功能，可以在 _dev at hbase dot apache dot org_ 上写下 hbase 开发者列表。
升级到 HBase 2.0+之前，需要从所有表中删除前缀树编码。要首先执行此操作，您需要将编码从前缀树更改为 HBase 2.0 中支持的其他内容。之后，您必须主要压缩以前使用前缀树编码的表。要检查哪些列族使用的数据块编码不兼容，可以使用[Pre-Upgrade Validator](#ops.pre-upgrade)
指标变化
以下指标已更改名称：
* 以前以"AssignmentManger" [sic]名称发布的度量现在"AssignmentManager"名称发布。
以下指标改变了其含义：
* 基于每个区域服务器发布的度量“blockcacheevictioncount”不再包括由于其来自的 hfiles 无效（例如通过压缩）而从缓存中删除的块。
* 度量'totalRequestCount'每个请求增加一次；以前它是由请求中携带的`Actions`数量增加的；例如，如果一个请求是由四个 get 和两个 puts 组成的`multi`，那么我们将“totalrequestcount”增加六次；现在，不管怎样，我们都将增加一次。希望在 HBase-2.0.0 中看到该指标的较低值。
* 'readRequestCount'现在对返回非空行的读取进行计数，在较旧的 HBase 中，无论结果是否为，我们都会增加“readrequestcount”。如果请求不存在的行，此更改将使读取请求图的配置文件变平。YCSB 读取繁重的工作负载可以根据数据库的加载方式来实现这一点。
已删除以下指标：
* 与分布式日志重播功能相关的度量不再存在。以前在区域服务器上下文中的名称“replay”下找到了它们。有关详细信息，请参阅 ["Distributed Log Replay" feature broken and removed](#upgrade2.0.distributed.log.replay)
添加了以下指标：
* 'totalRowActionRequestCount'是汇总读和写的区域行操作的计数。
更改日志
HBase-2.0.0 现在使用 [slf4j](https://www.slf4j.org/) 作日志组件.之前是 [log4j (1.2)](http://logging.apache.org/log4j/1.2/). 对于大多数情况，转换应该是无缝的；slf4j 能够很好地解释 _log4j.properties_ 日志配置文件，这样您就不会注意到日志系统的排放量有任何差异。
也就是说, _log4j.properties_ 需要刷新下. 详见例子: [HBASE-20351](https://issues.apache.org/jira/browse/HBASE-20351)在每次 shell 命令调用时，一个过时的日志配置文件都显示为 netty 配置，并在 debug 级别转储为前导码。
zookeeper 配置不再从 zoo.cfg 中读取
HBase 不再选择读取与 ZooKeeper 相关的配置设置的“zoo.cfg”文件。如果您以前依赖“hbase.config.read.zookeeper.config”配置来实现此功能，则应在向每个属性名添加前缀“hbase.zookeeper.property.”的同时，将任何需要的设置迁移到 hbase-site.xml 文件。
权限更改
以下与权限相关的更改要么更改了语义，要么更改了默认值：
* 授予用户的权限现在与该用户的现有权限合并，而不是重写它们。详见: [the release note on HBASE-17472](https://issues.apache.org/jira/browse/HBASE-17472)
* 区域服务器组命令（在 1.4.0 中添加）现在需要管理员权限。
大多数管理 API 不适用于来自 HBase 2.0 之前的客户机的 HBase 2.0+群集。
从 HBase 2.0 之前的客户机使用时，许多管理命令都不起作用。这包括一个 hbase shell，该 shell 具有来自 hbase 2.0 之前版本的库 jar。在您还可以更新到所需的客户端版本之前，您需要计划管理 API 和命令的使用中断。
当从 HBase 2.0 之前的客户机执行时，以下客户机操作不适用于 HBase 2.0+群集：
* list_procedures
* split
* merge_region
* list_quotas
* enable_table_replication
* disable_table_replication
* Snapshot related commands
1.0 已弃用的管理员命令删除。
在适用的情况下，列出了替换命令。
* 'hlog'命令已被删除。 下游用户应该依赖'wal'命令。
区域服务器内存消耗更改。
从 HBase 1.4 之前的版本升级的用户应阅读本节中的说明 [Region Server memory consumption changes.](#upgrade1.4.memory).
此外，HBase 2.0 改变了如何跟踪 memstore 内存以进行刷新决策。 以前，数据大小和存储开销都用于计算冲洗 threashold 的利用率。 现在，只使用数据大小来做出每个区域的决策。 在全球范围内，添加存储开销用于做出有关强制刷新的决策。
用于拆分和合并的 Web UI 对行前缀进行操作
以前，Web UI 包含表状态页面上的功能，以根据编码的区域名称进行合并或拆分。 在 HBase 2.0 中，此功能通过采用行前缀来工作。
从 HBase 1.4 之前对 Replication 用户进行特殊升级
用户在 1.4.0 版本之前运行 HBase 版本并使用复制时，请务必阅读本节中的说明[Replication peer’s TableCFs config](#upgrade1.4.replication).
HBase shell 变化
HBase shell 命令依赖于捆绑的 JRuby 实例。捆绑的 JRuby 已从 1.6.8 版更新到 9.1.10.0 版。它表示从 Ruby 1.8 到 Ruby 2.3.3 的更改，它为用户脚本引入了不兼容的语言更改。
HBase shell 命令现在忽略早期 HBase 1.4 版本中存在的'--return-values'标志。相反，shell 总是表现得像传递了那个标志。如果您希望避免在控制台中打印表达式结果，则应更改 IRB 配置，如[_irbrc_](#irbrc)）部分所述。
HBase 2.0+中的协处理器 API 已更改
所有协处理器 API 都经过重构，以提高针对未来 HBase 版本的二进制 API 兼容性的可支持性。如果您或您所依赖的应用程序具有自定义 HBase 协处理器，您应阅读 [the release notes for HBASE-18169](https://issues.apache.org/jira/browse/HBASE-18169) ，了解您将需要的更改的详细信息在升级到 HBase 2.0+之前制作。
例如，如果你在 HBase 1.2 中有一个 BaseRegionObserver，那么至少你需要更新它以实现 RegionObserver 和 RegionCoprocessor 并添加方法
```
...
@Override
public Optional<RegionObserver> getRegionObserver() {
return Optional.of(this);
}
...
```
HBase 2.0+无法再写入 HFile v2 文件。
HBase 简化了我们内部的 HFile 处理。因此，我们再也无法在版本 3 \的默认版本之前编写 HFile 版本。升级用户应确保在升级之前 hbase-site.xml 中的 hfile.format.version 未设置为 2。如果不这样做将导致 Region Server 失败。 HBase 仍然可以读取以旧版本 2 格式编写的 HFile。
HBase 2.0+无法再读取基于序列文件的 WAL 文件。
HBase 无法再读取以 Apache Hadoop 序列文件格式编写的已弃用的 WAL 文件。应将 hbase.regionserver.hlog.reader.impl 和 hbase.regionserver.hlog.reader.impl 配置条目设置为使用基于 Protobuf 的 WAL 读取器/写入器类。此实现是 HBase 0.96 以来的默认实现，因此传统 WAL 文件不应成为大多数下游用户关注的问题。
干净的群集关闭应确保没有 WAL 文件。如果您不确定给定的 WAL 文件格式，可以使用`hbase wal`命令在 HBase 集群脱机时解析文件。在 HBase 2.0+中，此命令将无法读取基于 WAL 的序列文件。有关该工具的更多信息，请参阅[WALPrettyPrinter](#hlog_tool.prettyprint)）。
过滤器的行为更改
过滤器 ReturnCode NEXT_ROW 已重新定义为跳过当前系列中的下一行，而不是跳到所有系列中的下一行。它更合理，因为 ReturnCode 是商店级别的概念，而不是区域级别。
下游 HBase 2.0+用户应该使用着色客户端
强烈建议下游用户依赖 Maven 坐标 org.apache.hbase：hbase-shaded-client 来运行它们。此工件包含与 HBase 集群通信所需的所有实现详细信息，同时最大限度地减少暴露的第三方依赖项的数量。
请注意，此工件公开 org.apache.hadoop 包空间中的某些类（例如 o.a.h.configuration.Configuration），以便我们可以保持与我们的公共 API 的源兼容性。包含这些类，以便可以将它们更改为使用与 HBase 客户端代码的其余部分相同的重定位第三方依赖项。如果您还需要**在代码中使用 Hadoop，则应确保所有与 Hadoop 相关的 jar 都位于类路径中的 HBase 客户端 jar 之前。
运行时类路径的重大更改
HBase 的许多内部依赖项已从运行时类路径中更新或删除。 不遵循[Downstream HBase 2.0+ users should use the shaded client](#upgrade2.0.shaded.client.preferred)的指导的下游客户端用户将必须检查 Maven 为影响而引入的依赖关系集。 LimitedPrivate Coprocessor API 的下游用户需要检查运行时环境是否有影响。 有关我们对协调兼容运行时版本一直存在问题的第三方库的新处理的详细信息，请参阅参考指南部分[The hbase-thirdparty dependency and shading/relocation](#thirdparty)）。
对客户端 API 的源和二进制兼容性进行多次重大更改
HBase 的 Java 客户端 API 有许多更改可以破坏源和二进制兼容性的详细信息，请参阅要升级到的版本的兼容性检查报告。
跟踪实施变化
HBase 跟踪功能的支持实现已从 Apache HTrace 3 更新为 HTrace 4，其中包括几个重大更改。 虽然 HTrace 3 和 4 可以在同一运行时共存，但它们不会相互集成，从而导致不相交的跟踪信息。
此升级期间 HBase 的内部更改足以进行编译，但尚未确认跟踪功能中没有回归。 请考虑此功能在不久的将来会过期。
如果您以前依赖与 HBase 操作集成的客户端跟踪，则建议您将使用情况升级到 HTrace 4。
HFile 不再向前兼容
由 2.0.0, 2.0.1, 2.1.0 生成的 HFile 与 1.4.6-, 1.3.2.1-, 1.2.6.1-和其他非活动版本不向前兼容。 为什么 HFile 失去兼容性是新版本(2.0.0, 2.0.1, 2.1.0)中的 hbase 使用 protobuf 序列化/反序列化 TimeRangeTracker（TRT），而旧版本使用 DataInput / DataOutput。为解决这个问题,详见: 2.x 中 [HBASE-21012](https://jira.apache.org/jira/browse/HBASE-21012) , 1.x 中 [HBASE-21013](https://jira.apache.org/jira/browse/HBASE-21013) . 还有 [HBASE-21008](https://jira.apache.org/jira/browse/HBASE-21008).
性能
在读取和写入路径发生重大变化的情况下，升级到 hbase-2.0.0 时，您可能会看到性能配置文件发生变化。 在发布时，写入可能会更慢，读取相同或更好，取决于上下文。准备好花时间重新调整
(详见: [Apache HBase Performance Tuning](#performance)). 性能也是一个正在积极审查的领域，因此期待在即将发布的版本中进行改进
(详见: [HBASE-20188 TESTING Performance](https://issues.apache.org/jira/browse/HBASE-20188)).
集成测试和 Kerberos
集成测试（`IntegrationTests *`）过去依赖于 Kerberos 凭证缓存来对安全集群进行身份验证。 当凭证缓存中的票证过期时，这会导致由于身份验证失败导致测试失败。 从 hbase-2.0.0（和 hbase-1.3.0 +）开始，集成测试客户端将使用配置属性`hbase.client.keytab.file`和`hbase.client.kerberos.principal`。 它们是必需的。 客户端将从配置的 keytab 文件执行登录，并在后台自动刷新凭据以获取进程生命周期(详见: [HBASE-16231](https://issues.apache.org/jira/browse/HBASE-16231)).
#### 13.1.2\. 将协处理器升级到 2.0
协处理器在 2.0 中发生了很大变化，从类层次结构中的顶级设计更改到更改/删除的方法，接口等。 (详见 jira: [HBASE-18169 Coprocessor fix and cleanup before 2.0.0 release](https://issues.apache.org/jira/browse/HBASE-18169)). 这种种广泛变化的原因是:
1. 传递接口而不是实现; e.g. TableDescriptor 而不是 HTableDescriptor and Region 而不是 HRegion ([HBASE-18241](https://issues.apache.org/jira/browse/HBASE-18241) 更改 client.Table 和 client.Admin 并非使用 HTableDescriptor).
2. 设计重构让实现者需要填写更少的样板，因此我们可以进行更多的编译时检查 ([HBASE-17732](https://issues.apache.org/jira/browse/HBASE-17732))
3. 从协处理器 API 清除协议缓冲区 ([HBASE-18859](https://issues.apache.org/jira/browse/HBASE-18859), [HBASE-16769](https://issues.apache.org/jira/browse/HBASE-16769), etc)
4. 减少我们向 Coprocessors 公开的内容，删除过于私密而无法公开的内部的钩子(例如: [HBASE-18453](https://issues.apache.org/jira/browse/HBASE-18453) CompactionRequest 不应该暴露给用户; [HBASE-18298](https://issues.apache.org/jira/browse/HBASE-18298) RegionServerServices 对 CP 公开的接口清理;)
要在 2.0 中使用协处理器，应该针对新 API 重建它们，否则它们将无法加载，HBase 进程将会死亡。
升级协处理器的建议更改顺序：
1. 直接实现观察者接口，而不是扩展 Base * Observer 类。 更改
`Foo extends BaseXXXObserver` 到 `Foo implements XXXObserver`. ([HBASE-17312](https://issues.apache.org/jira/browse/HBASE-17312)).
2. 适应从继承到组合的设计变更
([HBASE-17732](https://issues.apache.org/jira/browse/HBASE-17732)) 像 [此例](https://github.com/apache/hbase/blob/master/dev-support/design-docs/Coprocessor_Design_Improvements-Use_composition_instead_of_inheritance-HBASE-17732.adoc#migrating-existing-cps-to-new-design).
3. getTable()已从中删除，协处理器应自行管理 Table 实例。
[这里 hbase-example 模块](https://github.com/apache/hbase/tree/branch-2.0/hbase-examples/src/main/java/org/apache/hadoop/hbase/coprocessor/example)中可以找到使用新 API 编写协处理器的一些示例
最后，如果 api 被更改/删除，会以无法修复的方式打破你，并且如果有充分的理由将其添加回去，请将其通知我们([dev@hbase.apache.org](mailto:dev@hbase.apache.org)).
#### 13.1.3\. 从 1.x 到 2.x 的滚动升级
滚动升级目前是一项实验性功能。 他们的测试有限。 在我们有限的经历中，有可能发现一些极端情况，所以如果你走这条路，你应该小心。
下一节[Upgrade process from 1.x to 2.x](#upgrade2.0.process)中描述的停止/升级/启动是最安全的方式
以下是 1.4 集群滚动升级的提前要求
前提
* 升级到最新的 1.4.x 版本。 Pre 1.4 版本也可以使用但未经过测试，因此请在升级到 2.x 之前升级到 1.4.3+，除非您是专家并且熟悉区域分配和崩溃处理。 有关如何升级到 1.4.x 的信息，请参见[Upgrading from pre-1.4 to 1.4+](#upgrade1.4) 部分。
* 确保启用了无 zk 赋值，即将`hbase.assignment.usezk`设置为`false`。 这是最重要的事情。 它允许 1.x 主服务器为 2.x 区域服务器分配/取消分配区域。 有关如何从基于 zk 的分配迁移到 zk less 赋值，请参阅 [HBASE-11059](https://issues.apache.org/jira/browse/HBASE-11059)的发行说明部分。
* 我们测试了从 1.4.3 到 2.1.0 的滚动升级，但如果要升级到 2.0.x，它也应该可以工作。
说明
1. 卸载 region 服务升级到 2.1.0\. 从 [HBASE-17931](https://issues.apache.org/jira/browse/HBASE-17931) 看出，其他系统表的元区域和区域将立即移动到该区域服务器。 如果没有，请手动将它们移动到新的区域服务器。 这非常重要，因为
* 元区域的模式是硬编码的，如果元在旧的区域服务器上，则新的区域服务器不能访问它，因为它没有一些族，例如，表状态。
* 较低版本的客户端可以与具有更高版本的服务器通信，但反之亦然。 如果元区域位于旧区域服务器上，则新区域服务器将使用具有较高版本的客户端与具有较低版本的服务器通信，这可能引入奇怪的问题。
2. 滚动升级所有其他区域服务器。
3. 升级 masters.
在滚动升级期间，区域服务器崩溃是可以的。 1.x 主服务器可以为 1.x 和 2.x 区域服务器分配区域，[HBASE-19166](https://issues.apache.org/jira/browse/HBASE-19166)修复了问题，以便 1.x 区域服务器还可以读取 2.x 区域服务器写入的 WAL 并将其拆分。
> 在滚动升级之前，请仔细阅读[Changes of Note!](#_changes_of_note)部分。 确保不使用 2.0 中删除的功能，例如前缀树编码，旧的 hfile 格式等。它们都可能无法升级并使群集处于中间状态并且难以恢复。
> 如果您成功运行此处方，请通知开发者列表，并附上您的经验说明和/或更新上述内容以及您可能采取的任何偏差，以便其他人走这条路线可以从您的努力中受益。
#### 13.1.4\. 从 1.x 升级到 2.x 的升级过程
要升级现有的 HBase 1.x 群集，您应该：
* 现有 1.x 群集关闭
* 更新协处理器
* 首先升级主角色
* 升级 RegionServers
* （最终）升级客户端
### 13.2\. Upgrading from pre-1.4 to 1.4+
#### 13.2.1\. Region Server memory consumption changes.
从 HBase 1.4 之前的版本升级的用户应该知道，对于最大为 32G 的堆大小（使用 CompressedOops），memstore 对象（KeyValue，对象和数组头大小等）的堆使用估计已经更准确，从而导致 他们在实践中下降了 10-50％。 由于“更胖”的冲洗，这也导致更少的冲洗和压缩。因人而异。 因此，刷新之前 memstore 的实际堆使用量可能会增加最多 100％。 如果已根据观察到的使用情况调整了区域服务器的已配置内存限制，则此更改可能会导致更糟糕的 GC 行为或甚至 OutOfMemory 错误。 将环境属性（不是 hbase-site.xml）“hbase.memorylayout.use.unsafe”设置为 false 以禁用。
#### 13.2.2\. Replication peer’s TableCFs 设置
在 1.4 之前，表名不能包含复制对等体的 TableCFs 配置的名称空间。 通过将 TableCF 添加到存储在 Zookeeper 上的 ReplicationPeerConfig 来修复它。 因此，当升级到 1.4 时，您必须首先更新 Zookeeper 上的原始 ReplicationPeerConfig 数据。 当您的群集具有具有 TableCFs 配置的复制对等方时，有四个步骤可以升级。
* 禁用 replication peer.
* 如果 master 有权写入复制对等 znode，则直接滚动更新 master。 如果没有，请使用 TableCFsUpdater 工具更新复制对等方的配置。
```
$ bin/hbase org.apache.hadoop.hbase.replication.master.TableCFsUpdater update
```
* 滚动升级 regionservers.
* 开启 replication peer.
注意:
* 无法使用旧客户端（1.4 之前）更改复制对等方的配置。 由于客户端将直接向 Zookeeper 写入配置，因此旧客户端将错过 TableCFs 配置。 并且旧客户端将 TableCFs 配置写入旧的 tablecfs znode，它不适用于新版本的 regionserver。
#### 13.2.3\. 原始数据扫描忽略 TTL
现在，执行原始扫描将返回根据 TTL 设置已过期的结果。
### 13.3\. 从 1.3 之前升级到 1.3+
如果在 Kerberos 下运行集成测试，请参阅[Integration Tests and Kerberos](#upgrade2.0.it.kerberos).
### 13.4\. 升级到 1.x
有关升级过程的详细信息，请参阅专门针对要升级到的 HBase 版本发布的文档。
- HBase™ 中文参考指南 3.0
- Preface
- Getting Started
- Apache HBase Configuration
- Upgrading
- The Apache HBase Shell
- Data Model
- HBase and Schema Design
- RegionServer Sizing Rules of Thumb
- HBase and MapReduce
- Securing Apache HBase
- Architecture
- In-memory Compaction
- Backup and Restore
- Synchronous Replication
- Apache HBase APIs
- Apache HBase External APIs
- Thrift API and Filter Language
- HBase and Spark
- Apache HBase Coprocessors
- Apache HBase Performance Tuning
- Troubleshooting and Debugging Apache HBase
- Apache HBase Case Studies
- Apache HBase Operational Management
- Building and Developing Apache HBase
- Unit Testing HBase Applications
- Protobuf in HBase
- Procedure Framework (Pv2): HBASE-12439
- AMv2 Description for Devs
- ZooKeeper
- Community
- Appendix