标题里那个 Ubantu我猜是 Ubuntu 18.04 的笔误毕竟这套组合在本地大数据实验环境里实在太常见了。Vmware 虚拟机 Ubuntu 18.04 HBase 2.3.5基本是很多入门 HBase 的人亲手搭的第一个分布式存储环境。这篇就围绕这套组合从虚拟机准备、系统初始化、依赖环境到 HBase 2.3.5 的下载配置、启动验证和常见故障排查完整走一遍。适合从来没搭过大数据环境的新手也适合准备做 HBase 二次开发、需要一套稳定测试环境的老手参考。1. 选型逻辑为什么这套组合在本地实验环境最常见1.1 用虚拟机而不是物理机很多人第一次接触 HBase 时第一反应是找一台服务器或者云主机往上一通乱装。实际上在本地学习阶段我更推荐先在虚拟机里把环境跑通原因很简单快照。装好系统、配好基础环境之后打一个快照后面无论把配置折腾成什么样一条命令就能恢复到干干净净的初始状态。我见过太多人因为配置写错整个系统重装一晚上就交代进去了这种成本完全没必要。Vmware 作为虚拟机软件的最大优势是生态成熟NAT、桥接、自定义网络三种模式齐全且对 Linux 的硬件兼容性极好。用 Vmware 搭 Ubuntu 18.04 虚拟机能精准模拟出多台服务器的效果——即使你的物理机只有一台也能通过克隆虚拟出三台节点形成一个最小的 HBase 集群。这一点对后续理解分布式原理的帮助是单纯用 Docker 起容器完全无法替代的。1.2 Ubuntu 18.04 在这个版本下的优势Ubuntu 版本很多为什么偏偏是 18.04 和 HBase 2.3.5 搭在一起最顺核心原因是软件源和 JDK 生态。18.04 的官方源里还保留着 OpenJDK 8 的安装包而 HBase 2.3.5 官方文档明确推荐基于 JDK 8 运行。到了 Ubuntu 20.04 之后的版本OpenJDK 8 需要额外配置第三方源才能装虽然说不上多难但对于新手来说每一步多出的配置都是出错的机会。从稳定性角度讲18.04 属于长期支持版本社区资料极其丰富在 2025 年依然有大量教程和问答基于这个版本。HBase 2.3.5 是 2.x 系列里比较成熟稳定的一个小版本比起更早的 2.2 修复了不少 ZooKeeper 会话超时和内存管理问题比起最新的 2.4/2.5 又更保守安全不会因为引入新特性而改变默认配置行为。对一套学习环境来说稳定、资料多、好复现就是最大的优势。1.3 单机实验版与多节点集群的权衡这里必须先分清一个概念HBase 的“单机安装”有两种级别。一种是 standalone 模式数据直接写到本地文件系统不依赖 HDFS连 ZooKeeper 也是 HBase 自己内置启动。另一种是伪分布式模式HBase 进程跑在 HDFS 之上HMaster、HRegionServer、HQuorumPeer 都在这同一台机器上逻辑上是完整集群物理上只有一个节点。从学习价值来看我更推荐伪分布式模式。原因很简单HBase 真正的生产形态一定是跑在 HDFS 上的你迟早要面对 fs.defaultFS、hbase.rootdir、ZooKeeper quorum 这一串互相咬合的配置。如果一开始就只装 standalone后面切到集群模式时还是要重新理解一遍配置体系等于走了弯路。这篇博文也以伪分布式为主兼顾 standalone 模式的说明。2. 虚拟机与系统初始化HBase 部署前的底座2.1 VMware 网络与内存分配新建虚拟机时网络模式的选择很多人不在意其实很影响后续。单机实验直接选 NAT 模式最简单虚拟机通过宿主机共享上网IP 由 Vmware 的 DHCP 分配不需要和局域网里的其他设备打交道。但如果你打算克隆出两三台虚拟机模拟集群建议一开始就选桥接模式或者自定义一个仅主机网络保证节点之间能互相 ping 通。NAT 模式下克隆出来的虚拟机相互访问一般也能通但宿主机 DHCP 分配的地址段和桥接模式不一样有些人的实验环境里会出现跨网段看不明白的问题。内存分配是最容易忽略的硬指标。HBase 启动后HMaster、HRegionServer、内置 ZooKeeper 三组进程常驻加上系统本身和 HDFS 的 DataNode/NameNode1G 内存跑起来会非常勉强表现为进程反复被 OOM Killer 杀掉。建议至少给 2G最稳妥是 4G。磁盘方面Ubuntu 18.04 系统本身占用不大但 HDFS 的 NameNode 和 DataNode 都会存储元数据和数据块建议给到 30G 以上避免跑几天测试发现磁盘满了。CPU 给双核就足够大数据组件大多是 IO 和内存敏感型CPU 不是瓶颈。2.2 安装 Ubuntu 时的用户与分区细节安装 Ubuntu 18.04 时有一个小决策会影响后面所有操作那就是用户名。我强烈建议不要用含空格的用户名也不要用大写字母开头的用户名更不要用系统保留字。很多人习惯用类似 “test user” 这样的名字后面写 Hadoop 配置文件时home 目录路径里带着空格各种脚本直接跑挂。最省心的方式是单单词小写用户名比如 hadoop、hbase 或者你的英文名。分区上新手直接让安装器自动分配就好。如果你有意识地把 /home 或 /opt 单独分出来那要注意给 /opt 留足空间因为后面 Hadoop、HBase 这一类软件我建议统一装到 /opt 下。系统盘和软件盘分开的好处是后期做虚拟机扩容时不用重新分区直接把硬件磁盘加大再扩展逻辑卷就行。2.3 hostname、hosts、防火墙与软件源装完系统后我习惯按这个顺序做基础初始化改主机名、配 hosts、关防火墙、换软件源。主机名我在这里统一用 node1 举例你可以改成自己的。修改方式sudo hostnamectl set-hostname node1然后编辑 /etc/hosts把本机 IP 和主机名对应起来。这里要特别注意不要只写“127.0.0.1 node1”否则 Hadoop 和 HBase 的 RPC 通信时节点之间解析到回环地址会连接失败。正确做法是写上实际 IP# /etc/hosts 192.168.x.x node1 127.0.0.1 localhost防火墙这块Ubuntu 18.04 默认没有启用 ufw 的强制执行但保险起见还是看一眼状态。命令是 sudo ufw status如果是 active你要么 sudo ufw disable 直接关掉要么把 HBase 用到的端口加入白名单。学习环境直接关掉是最省事的。软件源建议在安装 Hadoop/HBase 前先更新一遍。Ubuntu 18.04 的默认源在国外速度时快时慢换成国内镜像源之后 apt 装东西会快很多。操作方式是修改 /etc/apt/sources.list把 archive.ubuntu.com 替换成镜像地址然后 sudo apt update sudo apt upgrade。2.4 克隆虚拟机时最容易埋下的隐患如果你打算用 Vmware 的克隆功能生成多台节点这里有几个隐藏坑会在 HBase 启动时突然爆发。首先克隆出来的虚拟机网卡 MAC 地址如果和源虚拟机一致DHCP 可能分配出相同 IP节点之间互相抢地址HBase 的 ZooKeeper 集群直接逻辑混乱。Vmware 克隆时如果选“完全克隆”一般会自动生成新 MAC但有些版本下不会建议克隆后执行 ip link 检查一下网卡 MAC必要时手动修改。其次克隆后主机名还保持着源虚拟机的名字必须一台台改掉。最后也是最重要的克隆出的机器如果是从一个已经安装了 Hadoop/HBase 的系统克隆的那么 Hadoop 临时目录、ZooKeeper dataDir 里的数据文件也是复制过来的多个节点共享同一份元数据启动时各种“NodeAlreadyExists”报错。正确做法是先装好基础系统和 JDK再打快照之后再克隆而不是装完 Hadoop 再克隆。3. 依赖环境JDK 8、Hadoop 与 SSH 免密3.1 HBase 对 JDK 的要求HBase 运行在 JVM 之上版本对不上后面所有问题都会出现。HBase 2.3.5 发布时官方推荐的 Java 版本就是 JDK 8虽然 2.3.x 在某些 JDK 11 环境下也能跑但配置参数和 GC 日志格式的兼容性没有 JDK 8 稳。Ubuntu 18.04 上是这样装的sudo apt update sudo apt install -y openjdk-8-jdk装完后验证java -version正常会输出 OpenJDK 1.8 版本信息。这里要专门强调不要跳过 JAVA_HOME 的配置因为 HBase 的启动脚本 hbase-env.sh 里如果不显式指定 JAVA_HOME它可能拿到系统默认的 JVM而系统默认 JVM 可能已经被其他软件改成了新版本。配置方法在 /etc/environment 或 ~/.bashrc 里加export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export PATH$PATH:$JAVA_HOME/binJAVA_HOME 的路径可以执行 sudo update-alternatives --config java 查看当前生效的 JDK 实际路径不要凭记忆硬写。3.2 Hadoop 到底要不要装这是很多新手最纠结的问题。答案是伪分布式模式下必须要装 Hadoop 并启动 HDFS。HBase 只是数据库层它的数据最终要落到存储层生产环境里存储层就是 HDFS。如果 HDFS 没起来HBase 启动时找不到数据目录HMaster 会反复尝试连接后直接退出。如果你只想验证 HBase 的基本 CRUD对 HDFS 没兴趣那可以跑 standalone 模式hbase-site.xml 里不配置 hbase.rootdir数据直接写本地文件系统。但我前面说过这条路对理解 HBase 架构帮助有限。下面按伪分布式讲所以请先准备 Hadoop。版本选择上Hadoop 3.1.x / 3.2.x 和 HBase 2.3.5 的配合在社区里有大量成功案例不用追新。3.3 Hadoop 单机伪分布式快速搭建Hadoop 的完整安装教程很长这里只说和 HBase 配合的关键点。下载 Hadoop 3.2.4 二进制包后解压到 /opt/hadoop-3.2.4然后配置 4 个文件。core-site.xml 里设置 NameNode 的地址property namefs.defaultFS/name valuehdfs://node1:9000/value /propertyhdfs-site.xml 里设置副本数和 NameNode 的数据目录。单节点伪分布式副本数改为 1property namedfs.replication/name value1/value /property property namedfs.namenode.name.dir/name value/opt/hadoop-3.2.4/namenode-dir/value /property property namedfs.datanode.data.dir/name value/opt/hadoop-3.2.4/datanode-dir/value /property配置好后格式化文件系统hdfs namenode -format之后启动 HDFSstart-dfs.sh启动完执行 jps应该能看到 NameNode 和 DataNode 两个进程。注意namenode 目录一旦格式化不要再重复执行否则会清空 HBase 存储在 HDFS 上的数据。3.4 SSH 免密登录HBase 的启动脚本会通过 SSH 登录到 regionservers 文件中列出的每台节点并远程拉起进程。单机伪分布式环境虽然只有 node1 一台但脚本依然会尝试 SSH 到 node1如果你没有配置免密每次启动都要输密码而且有些版本的启动脚本在交互式输入密码时还会卡住。所以提前配好免密是必须的。ssh-keygen -t rsa -P -f ~/.ssh/id_rsa cat ~/.ssh/id_rsa.pub ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys然后验证ssh node1如果不要求输入密码直接进入就说明配置成功。这里有个很容易被忽视的细节SSH 免密验证的是主机名解析也就是你 ssh 后面写的是 node1那么 node1 必须能解析到正确的 IP否则免密配了也没用。这也是我前面强调 hosts 文件的原因。4. HBase 2.3.5 部署下载、目录布局与关键配置4.1 安装包下载与目录布局HBase 2.3.5 的二进制包可以从 Apache 官方下载页面获取文件名一般是 hbase-2.3.5-bin.tar.gz。建议直接下载 bin 版本不要下载 src 版本src 是源码包需要自己编译耗时且没有意义。解压安装cd /opt tar -zxvf hbase-2.3.5-bin.tar.gz mv hbase-2.3.5 /opt/hbase-2.3.5解压后先大致看一下目录布局这对后续排查问题很有帮助。bin 目录下是各种启停脚本conf 目录下是全部配置文件lib 目录下是 HBase 依赖的所有 jar 包logs 目录默认不存在首次启动时会自动生成是排错的第一个去处。我见过不少人在 HMaster 启动失败后一头雾水其实 logs 下的日志里已经把失败原因写得明明白白。4.2 hbase-env.sh 核心配置项conf 目录下的 hbase-env.sh 是环境变量脚本打开后重点改两个配置。第一个是 JAVA_HOME一定要显式写死export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64第二个是 JVM 堆内存设置。默认值对虚拟机不太友好HBase 2.3.5 的 HBASE_HEAPSIZE 默认是 1G如果你的虚拟机只有 2G 内存再加上 HDFS 的进程很容易触发 OOM。建议调小到 512mexport HBASE_HEAPSIZE512m另外还有一个 HBASE_MANAGES_ZK 参数默认是 true表示由 HBase 自己启动和管理 ZooKeeper。伪分布式场景保持 true 即可。如果你后续接了外部 ZooKeeper 集群才需要改成 false。新手时期别去动它否则会陷入“为什么我起来了 3 个进程但 ZooKeeper 连不上”的焦虑。4.3 hbase-site.xml 核心配置项hbase-site.xml 是整个配置体系的核心。打开后在 configuration 标签内添加以下配置并确保没有残留原有的默认内容默认文件里通常只有一堆注释。property namehbase.rootdir/name valuehdfs://node1:9000/hbase/value /property property namehbase.cluster.distributed/name valuetrue/value /property property namehbase.zookeeper.quorum/name valuenode1/value /property property namehbase.zookeeper.property.dataDir/name value/opt/hbase-2.3.5/zookeeper-data/value /property这里每个配置都有讲究。hbase.rootdir 告诉 HBase 数据落在哪个文件系统路径下格式是 hdfs://node1:9000/hbase其中 node1 和 9000 必须与 Hadoop core-site.xml 里的 fs.defaultFS 完全一致9000 端口也是由 fs.defaultFS 决定的。hbase.cluster.distributed 设为 true 代表伪分布式模式HBase 会真正连接 ZooKeeper 和 HDFS。hbase.zookeeper.quorum 是 ZooKeeper 集群地址单机环境填主机名 node1 即可但注意它不能填 IP填 IP 在某些版本下会导致集群节点之间广播地址不一致。hbase.zookeeper.property.dataDir 是 ZooKeeper 的数据目录建议放在 HBase 目录下方便整体清理和备份。不要忘记创建 zookeeper-data 目录并给予当前用户写权限否则 ZooKeeper 启动时会报 Unable to create data directory 之类的错误。4.4 regionservers 文件与目录权限conf/regionservers 文件里列出了所有 RegionServer 节点的主机名。单机伪分布式就写一行 node1 即可。这里实际承载的机制是start-hbase.sh 启动时读取这个文件对每个主机名执行 SSH 远程启动 HRegionServer 进程。如果你的 node1 在 hosts 里没配置或者 SSH 免密没生效HMaster 能起来但 HRegionServer 永远起不来整个 HBase 集群处于“只读不写”的诡异状态。目录权限是另一个非常隐蔽的坑。HBase 进程最终会以你当前登录的用户身份运行所以 /opt/hbase-2.3.5 整个目录的所有权必须归属该用户否则启动时写日志、写 ZooKeeper dataDir 都会遇到 Permission denied。建议直接sudo chown -R $USER:$USER /opt/hbase-2.3.5同样的道理HDFS 的 /hbase 根目录也不要跑到别的用户下。如果你不是用 hadoop 用户统一管理的建议所有进程都用一个用户跑省掉大量权限问题。4.5 环境变量与 PATH 配置为了让后续命令敲起来方便在 ~/.bashrc 末尾追加export HBASE_HOME/opt/hbase-2.3.5 export PATH$PATH:$HBASE_HOME/bin export HADOOP_HOME/opt/hadoop-3.2.4 export PATH$PATH:$HADOOP_HOME/bin然后执行 source ~/.bashrc。特别提醒HADOOP_HOME 和 HBASE_HOME 的 bin 目录里都有同名脚本比如 start-all.sh、hadoop 之类如果 PATH 顺序不对可能调起了错误版本。所以再执行 which hbase 和 which hadoop 检查一下路径是否指向你期望的位置。这一步看起来不起眼但能省下后续一两个小时排查“我怎么跑的是旧版命令”的时间。5. 启动验证与经典故障排查5.1 启动顺序与 jps 验证HBase 伪分布式的启动顺序有讲究先启动 HDFS再启动 HBase。反过来是不行的HBase 启动时如果发现 hbase.rootdir 对应的 HDFS 文件系统不可用会直接失败退出。# 先启动 HDFS start-dfs.sh # 确认 NameNode 和 DataNode 都已启动 jps # 再启动 HBase start-hbase.sh启动脚本执行完后再次执行 jps一个正常的单机伪分布式环境应该能看到这些进程NameNode、DataNode、HMaster、HRegionServer、HQuorumPeer。HQuorumPeer 是 HBase 内置 ZooKeeper 的进程名看到它就说明 ZooKeeper 起来了。如果 jps 里没有 HMaster 或者 HRegionServer说明启动失败。不要重试 start-hbase.sh先把日志看了再说。日志位置在 /opt/hbase-2.3.5/logsHMaster 和 HRegionServer 各有一个单独的 .log 文件还会有对应的 .out 文件。.log 是 log4j 输出的标准日志信息最全.out 是 JVM 标准输出通常只有异常栈。排查时两个都翻一下。5.2 HBase Shell 验证读写进程都起来之后进入 HBase Shell 做一轮真实读写才能证明集群功能完整。hbase shell进入 shell 后依次执行status这个命令会显示集群中 RegionServer 的数量正常能看到 1 个 active master 和 1 个 region server。然后建表、写数据、读数据create member, info put member, 1001, info:name, test put member, 1001, info:age, 25 get member, 1001 scan membercreate 成功后再执行 status你会发现 RegionServer 上的表数量从 0 变成 1说明表的元数据已经成功注册到 HBase Master。get 和 scan 都能返回刚写入的数据说明 RegionServer 和 HDFS 之间的数据通道是通的。第一次测试全部跑通时这套环境就算真正完成了。退出 shell 用 exit 命令。之后如果想关闭环境顺序和启动相反stop-hbase.sh stop-dfs.sh5.3 HMaster 起不来的完整排查链路HMaster 进程启动后几秒就消失是整个安装过程中出现频率最高的故障没有之一。下面给出一条我自己每次都会按顺序走的排查链路。第一步看日志。打开 logs/hbase- -master-node1.log搜索 ERROR 关键字。最常见的第一行错误通常直接说明问题比如 java.net.UnknownHostException: node1那基本就是 hosts 文件写错了比如 FileAlreadyExistsException那就是 ZooKeeper dataDir 里残留了之前失败的元数据。第二步验证 HDFS。执行 hdfs dfs -ls /确认根目录存在且能访问再检查 /hbase 目录是否出现。如果 HDFS 里根本没有 /hbase 目录说明 HMaster 在连接 ZooKeeper 或者初始化阶段就失败了问题不在 HDFS 而在 ZooKeeper 或配置。如果 /hbase 目录存在但 HMaster 还是起不来可以执行 hdfs dfs -ls /hbase 看看是否由当前用户创建如果 owner 是别人删掉重建。第三步检查 ZooKeeper 状态。看 logs 里有没有 java.net.ConnectException有的话确认 2181 端口是否被占用或监听在错误地址上执行 ss -lntp | grep 2181。如果是 HBase 内置 ZooKeeper正常情况下端口监听在 0.0.0.0:2181如果被其他进程占用把那个进程处理掉再重启。第四步清理数据目录再重启。如果确认配置没问题、日志也没给出明确异常就执行 hbase 自带的清理命令先停掉 HBase 和 HDFS删除 /opt/hbase-2.3.5/zookeeper-data 目录再删除 HDFS 上的 /hbase 目录然后按启动顺序重新拉起。这个方法能解决 80% 的“残留元数据导致起不来”问题。5.4 虚拟机场景特有的坑真实物理集群很少遇到的一些问题在 Vmware 环境里反而高发这里集中说一下。第一个是时钟偏差。Vmware 虚拟机在挂起、恢复、克隆之后系统时间经常和宿主机偏离。ZooKeeper 对集群节点间的时钟偏差有默认容忍上限虽然单机节点不涉及跨节点比较但 HBase 在本地写 WAL 时时间戳异常会导致一些奇怪的写入失败。解决办法很简单在虚拟机里配置 NTP 自动同步或者每次恢复快照后手动执行 sudo ntpdate 同步一次。第二个是交换分区不足。内存不够用是虚拟机常态当 HBase 堆内存加上 HDFS 进程把物理内存吃完后系统会开始疯狂 swap表现为所有操作变得极慢HBase RPC 大量超时。建议创建虚拟机时就给一个 2G 的 swap 分区或者装完系统后用文件方式启用 swap。有了 swap 兜底即使物理内存打满至少不会立刻 OOM。第三个是宿主机休眠导致的网络假死。笔记本合盖休眠后Vmware 虚拟机的网络经常处于半连接状态HBase 的 ZooKeeper 会话会超时断开恢复后客户端连接报 Session expired。碰到这种情况最简单的办法不是重启虚拟机而是把 HBase 和 HDFS 全部 stop再重新 start让所有进程重新建立会话。最后再分享一个我个人的操作习惯每次成功装完一套环境立即在 Vmware 里打一个快照。快照的名字我会写成“Base System JDK HDFS HBase OK”这样后面无论怎么折腾都能快速回退到已经验证过的状态。这个习惯在我带新人、做实验性开发时帮我省下了大量返工时间。如果你要在 HBase 上跑复杂的压力测试或者调试源码也可以在此基础上再打一个“HBase 干净状态”的快照作为每次实验的固定起点。