简介本资源为适配 ambari-2.7.5 编译环境的 HBase 离线安装包面向大数据平台搭建与运维人员用于解决编译过程中 hbase-2.0.2.3.1.4.0-315-bin.tar.gz 等大包下载缓慢、易中断的问题可提前下载后放入本地仓库加速集群部署流程。压缩包共 412 个文件约 211.57MB以 194 个 jar 依赖库、158 个 rb 脚本、17 个 sh 启动脚本为主另含 xml 配置、cmd 批处理、properties 属性文件及少量 html、js、png 等前端与文档资源覆盖 HBase 运行所需的依赖、配置与启动脚本。目录结构完整包含 hbase-env、regionservers 等关键配置项便于直接替换或集成到 ambari 编译流程中。目前已有 2195 人学习下载适合需要离线部署 HBase 组件、排查依赖缺失或加速 ambari 编译的工程师参考使用。1. 拿到 hbase-2.0.2.3.1.4.0-315-bin.tar.gz 之后先别急着解压这个包名第一次见的人多半会愣一下hbase-2.0.2.3.1.4.0-315-bin.tar.gz版本号长得像一串电话号码。它不是一个普通的 Apache HBase 发行版而是某套大数据平台发行版里被重新打包、重新编号的 HBase 二进制分发包——2.0.2是上游 HBase 的基线版本后面那串3.1.4.0-315是平台侧的构建号bin表示里面是编译好的二进制而非源码。你拿到它通常意味着你要在一个已经跑着同系列组件的集群里把 HBase 这一层单独部署、升级或者排障。它解决的核心问题是让你不用自己从源码编译 HBase也不用去猜平台内部改了什么依赖直接解压就能拿到一套和集群其余组件版本对齐的 HBase 运行时。适合谁适合正在维护这套平台、需要手工拉起 HBase 服务、或者要排查 RegionServer 起不来、ZooKeeper 连不上这类问题的运维和开发。这篇笔记就按「解压前确认什么 → 怎么配 → 怎么起 → 怎么验证 → 坑在哪」的顺序讲一遍都是我实际部署时踩出来的路径。2. 解压之前必须确认的三件事JDK、ZooKeeper、Hadoop 依赖很多人拿到 tar.gz 第一反应是tar -zxvf然后bin/start-hbase.sh结果卡在启动脚本报JAVA_HOME is not set或者连不上 ZooKeeper。HBase 是强依赖外部环境的组件解压前把这三件事确认清楚能省掉后面一大半的排查时间。2.1 JDK 版本与 JAVA_HOME 的硬性要求HBase 2.0.x 这条线对 JDK 的要求是 JDK 8不支持 JDK 11 及以上。平台打包的版本通常还会在conf/hbase-env.sh里写死一些 JVM 参数如果你机器上默认 JDK 是 17启动脚本会直接抛UnsupportedClassVersionError。先确认# 查看当前默认 JDK 版本必须是 1.8.x java -version # 如果机器上有多个 JDK显式指定路径 echo $JAVA_HOME ls $JAVA_HOME/bin/java如果默认不是 JDK 8不要改系统默认直接在hbase-env.sh里指定# conf/hbase-env.sh 中取消注释并改成实际路径 export JAVA_HOME/usr/lib/jvm/java-1.8.0-openjdk # 平台包常带的额外 JVM 参数按机器内存调整 export HBASE_MASTER_OPTS-Xms2g -Xmx2g -XX:UseG1GC export HBASE_REGIONSERVER_OPTS-Xms4g -Xmx4g -XX:UseG1GC参数说明-Xms和-Xmx设成一样是为了避免运行期堆伸缩带来的停顿G1 在 HBase 2.0 上比 CMS 更稳尤其是 RegionServer 堆大于 4G 时。这里不要照抄数值按你机器的物理内存来RegionServer 堆一般不超过物理内存的一半留足空间给堆外和系统缓存。2.2 ZooKeeper 是自带的还是外部的必须先定HBase 用 ZooKeeper 做集群协调包名里没有 zk 字样说明它大概率依赖外部 ZooKeeper。平台发行版有两种模式一种是 HBase 自带一个 ZK 实例hbase.zookeeper.property.dataDir指向本地目录另一种是连集群统一的 ZK 集群。搞错了会出现「Master 起来了但 RegionServer 注册不上」的玄学现象。判断方法看conf/hbase-site.xml里有没有hbase.cluster.distributed和hbase.zookeeper.quorum!-- 分布式模式连外部 ZK -- property namehbase.cluster.distributed/name valuetrue/value /property property namehbase.zookeeper.quorum/name valuezk-node-1,zk-node-2,zk-node-3/value /property property namehbase.zookeeper.property.clientPort/name value2181/value /property如果hbase.zookeeper.quorum写的是localhost那多半是单机自带 ZK 模式只适合本地测试。生产环境一定要指向真实 ZK 集群地址并且确认这些节点从你的 HBase 机器上telnet zk-node-1 2181是通的。ZK 连不上时HBase 日志里会出现ConnectionLossException或者一直重试Session 0x0 for server null这时候别去翻 HBase 代码先查网络和 ZK 服务本身。2.3 Hadoop 依赖用自带的 jar 还是外部 classpathHBase 读写 HDFS需要 Hadoop 的 client jar。平台包通常会在lib/下自带一批 hadoop 相关 jar但如果你集群的 HDFS 版本和包内自带的不一致会出现NoSuchMethodError或者RPC protocol version mismatch。确认方式# 看包内自带的 hadoop jar 版本 ls lib/ | grep hadoop # 看集群 HDFS 的版本 hdfs version如果两边大版本不一致常见做法是在hbase-env.sh里用HBASE_CLASSPATH把集群的 hadoop 配置目录加进来让 HBase 优先用集群的配置# 把集群的 core-site.xml / hdfs-site.xml 所在目录加入 classpath export HBASE_CLASSPATH/etc/hadoop/conf注意这里加的是配置目录不是 jar 目录。HBase 启动时会读core-site.xml里的fs.defaultFS来确定 HDFS 地址如果这个读错了Master 初始化时会在hbase.rootdir上创建目录失败日志报FileSystemNotFoundException或者直接连到本地文件系统去了。我一般会在解压后先grep -r fs.defaultFS /etc/hadoop/conf/core-site.xml确认一下 HDFS 地址再往下走。3. 从解压到改配置hbase-site.xml 里必须动的五个参数环境确认完解压和配置就是纯体力活但hbase-site.xml里有五个参数如果不动集群要么起不来要么起来了数据写不进去。这一章把解压、目录规划、参数含义和改法一次讲清。3.1 解压与目录规划别放在 /tmp 下# 解压到规划好的目录不要放 /tmp重启会丢 tar -zxvf hbase-2.0.2.3.1.4.0-315-bin.tar.gz -C /opt/ # 建软链接方便后续升级时切换版本 ln -s /opt/hbase-2.0.2.3.1.4.0-315 /opt/hbase # 确认目录结构 ls /opt/hbase/ # bin conf lib logs hbase-webapps逻辑说明解压出来的目录名带完整版本号建一个/opt/hbase软链接指向它以后升级只改软链接配置和脚本里统一用/opt/hbase路径。logs目录默认可能不存在启动前手动mkdir -p /opt/hbase/logs否则日志会写到启动脚本所在目录排查时找不到。3.2 hbase.rootdir 与 hbase.tmp.dir两个最容易写错的路径property namehbase.rootdir/name valuehdfs://mycluster/hbase/value /property property namehbase.tmp.dir/name value/opt/hbase/tmp/value /property property namehbase.unsafe.stream.capability.enforce/name valuefalse/value /property参数说明hbase.rootdir是 HBase 在 HDFS 上的根目录必须和core-site.xml里的fs.defaultFS一致mycluster换成你实际的 nameservice 名。hbase.tmp.dir是本地临时目录不要指向/tmp系统清理会把它删掉导致 RegionServer 崩溃。hbase.unsafe.stream.capability.enforce设成false是 HBase 2.0 在部分 HDFS 版本上的兼容开关不设的话启动时会报StreamCapabilities相关的警告甚至异常这是平台包常见的默认值照抄即可。3.3 regionserver 相关参数堆内存与 handler 数property namehbase.regionserver.handler.count/name value30/value /property property namehbase.hregion.memstore.flush.size/name value134217728/value /property property namehbase.hregion.max.filesize/name value10737418240/value /property参数说明handler.count是 RegionServer 处理 RPC 请求的线程数默认 30写多读少的场景可以调到 50 左右但不要超过 100线程太多反而增加上下文切换开销。memstore.flush.size是单个 Region 的 MemStore 刷写阈值默认 128MB调大能减少 flush 次数但增加堆压力。max.filesize是 Region 分裂阈值默认 10GB小集群可以调小到 5GB 让分裂更均匀。这三个参数没有绝对最优值我一般先按默认跑观察logs/hbase-*-regionserver-*.log里的 flush 频率和 GC 日志再调。3.4 把配置分发到所有节点单机改完不算完集群里每个节点都要有一份一致的配置。常见做法是用 scp 或者配置管理工具同步# 假设有三台机器把整个 hbase 目录同步过去 for host in node-1 node-2 node-3; do rsync -avz /opt/hbase/ $host:/opt/hbase/ done注意rsync同步的是软链接指向的实际目录内容目标机器上也要建同样的软链接。同步完在每台机器上确认conf/hbase-site.xml的hbase.zookeeper.quorum和hbase.rootdir一致不一致的节点启动后会加入错误的集群这种问题在日志里表现为 RegionServer 反复尝试连接一个不存在的 Master。4. 启动顺序与验证Master、RegionServer、Web UI 三步走配置同步完启动顺序错了也会出问题。HBase 的启动脚本start-hbase.sh会按conf/regionservers文件里的列表去拉起 RegionServer但前提是 Master 先起来并且 ZK 里已经写入了集群状态。这一章讲启动、验证和几个必看的日志位置。4.1 启动命令与 regionservers 文件# conf/regionservers 里每行一个主机名 cat conf/regionservers # node-2 # node-3 # 在 Master 节点执行启动 cd /opt/hbase bin/start-hbase.sh逻辑说明start-hbase.sh会先在本机启动 HMaster然后通过 SSH 到regionservers列表里的每台机器启动 HRegionServer。前提是 Master 到这些机器免密 SSH 已经配好否则脚本会卡在输入密码或者直接报Permission denied。如果只想单独启动某个角色用bin/hbase-daemon.sh start master或bin/hbase-daemon.sh start regionserver调试时更可控。4.2 用 jps 和日志确认进程状态# 在 Master 节点 jps # 期望看到 HMaster # 在 RegionServer 节点 jps # 期望看到 HRegionServer # 看 Master 日志尾部 tail -n 100 logs/hbase-*-master-*.log # 看 RegionServer 日志尾部 tail -n 100 logs/hbase-*-regionserver-*.log判断标准Master 日志里出现Master startup complete或者Active Master字样说明 Master 正常。RegionServer 日志里出现RegionServer startup complete并且有Registered with master字样说明注册成功。如果 RegionServer 日志停在Trying to connect to master反复重试回去查 ZK 连接和 Master 是否真的起来了。4.3 Web UI 和 hbase shell 双重验证# 默认 Web UI 端口 16010 curl -s http://node-1:16010/master-status | head -n 20 # 进入 shell 做一次建表、插入、查询 bin/hbase shell在 shell 里执行# 建一张测试表一个列族 create test_table, cf # 插入一行 put test_table, row1, cf:name, hello # 查询 get test_table, row1 # 删除测试表 disable test_table drop test_table逻辑说明Web UI 能看到Region Servers列表里所有节点都是绿色说明集群拓扑正常。shell 能建表、写入、读出说明 HDFS 写入和 ZK 协调都通了。如果create卡住不返回多半是 HDFS 权限问题或者hbase.rootdir路径不可写去 Master 日志里找AccessControlException或Permission denied。5. 避坑记录五个让集群起不来的常见问题这一章是我在实际部署里翻车最多的五个点每个都按「现象 → 原因 → 解决」写清楚。你如果启动失败先对照这里排查大概率能命中。5.1 现象Master 启动后秒退日志无明显报错原因hbase.rootdir指向的 HDFS 路径不存在且当前用户没有创建权限或者core-site.xml没被正确加载导致连到了本地文件系统。Master 在初始化时尝试创建根目录失败进程直接退出日志可能只留下一行Failed to create rootdir。解决先确认HBASE_CLASSPATH是否包含了集群的 hadoop 配置目录再手动在 HDFS 上创建目录并授权hdfs dfs -mkdir -p /hbase hdfs dfs -chown hbase:hbase /hbase hdfs dfs -chmod 755 /hbase然后用hdfs dfs -ls /hbase确认目录存在且属主正确再重启 Master。5.2 现象RegionServer 启动后反复报 ConnectionLossException原因ZK 集群地址配错或者 ZK 的maxClientCnxns限制导致 HBase 连接被拒。平台包默认的 ZK 客户端超时是 90 秒网络抖动时容易触发会话过期。解决先telnet确认 ZK 端口通再在hbase-site.xml里适当调大超时property namezookeeper.session.timeout/name value180000/value /property property namehbase.zookeeper.property.tickTime/name value6000/value /property注意zookeeper.session.timeout要大于 ZK 服务端的tickTime * 2否则会话还没建立就被判超时。5.3 现象HDFS 写入报 NoSuchMethodError 或 RPC 版本不匹配原因包内自带的 hadoop client jar 和集群 HDFS 版本不一致类加载时找到了旧版本的方法签名。解决在hbase-env.sh里把集群的 hadoop jar 目录加到 classpath 最前面让 HBase 优先加载集群版本export HBASE_CLASSPATH/etc/hadoop/conf:/usr/lib/hadoop/client如果还是不行检查lib/下是否有重复的 hadoop jar把包内自带的删掉或改名备份只保留集群版本。5.4 现象Web UI 能打开但 RegionServer 列表为空原因RegionServer 进程起来了但注册到 Master 时用的主机名和 Master 解析到的不一致或者regionservers文件里写的是 IP 而 DNS 反解成了另一个名字。解决统一用主机名而不是 IP在每台机器的/etc/hosts里把主机名和 IP 对应关系写死确保 Master 和 RegionServer 互相能通过主机名解析。改完重启整个集群。5.5 现象shell 建表卡住最后报 Timeout原因HDFS 的dfs.datanode.max.transfer.threads太小或者 HBase 的hbase.hregion.memstore.flush.size设得过大导致 MemStore 一直不刷写建表时的元数据写入被阻塞。解决先看 HDFS 的 DataNode 日志有没有xceiverCount超限的警告有的话调大dfs.datanode.max.transfer.threads。再看 HBase 的 MemStore 使用情况把flush.size调回默认的 128MB 试试。建表卡住时不要反复重试先disable再drop否则会留下半成品表影响后续操作。6. 版本号背后的构建逻辑与一个手工验证技巧hbase-2.0.2.3.1.4.0-315-bin.tar.gz这串版本号不是随便编的它反映的是平台发行版的构建流水线上游 HBase 2.0.2 作为基线平台侧打了 3.1.4.0 这个内部版本315 是第 315 次构建。理解这一点你就能预判这个包里可能带了哪些平台特有的补丁——通常是安全修复、HDFS 兼容性适配、以及和平台其他组件的 RPC 协议对齐。一个我常用的验证技巧解压后不要急着启动先看lib/下 jar 的命名和数量和上游 Apache HBase 2.0.2 的官方发行版对比。平台包通常会多出几个platform-*.jar或者把某些依赖的版本号改掉。用下面这个命令快速列出差异# 列出包内所有 jar按名称排序观察有没有平台特有的前缀 ls lib/*.jar | xargs -n1 basename | sort /tmp/pkg_jars.txt # 和官方发行版的 jar 列表对比假设你手头有官方包 ls /opt/hbase-official/lib/*.jar | xargs -n1 basename | sort /tmp/official_jars.txt # 看差异 diff /tmp/official_jars.txt /tmp/pkg_jars.txt逻辑说明差异里出现的平台特有 jar往往是排查兼容性问题的关键。比如多了一个platform-rpc-bridge-*.jar那说明平台在 HBase RPC 层做了封装你如果直接用上游的客户端去连可能会因为协议不一致而连不上。这时候要么用包内自带的客户端要么找平台侧确认协议版本。参数说明xargs -n1 basename是把完整路径变成纯文件名方便对比。sort保证两边顺序一致diff才能准确找出差异。这个技巧不限于 HBase任何平台打包的组件都可以这么干。最后说一个我自己的习惯每次拿到这种带长版本号的包我都会在解压后的目录里放一个BUILD_INFO.txt把包名、解压时间、机器主机名、JDK 版本、ZK 地址记进去。过几个月再回来看这台机器不用去翻聊天记录就能知道当时部署的是什么版本、连的哪个 ZK。这个习惯帮我省过好几次「这机器上跑的到底是哪个版本」的后悔药。希望帮到你。本文还有配套的精品资源点击获取
