Windows本地Scala应用无法连接Docker容器内HBase问题求助

报错栈中的java.nio.channels.UnresolvedAddressException由HBase客户端的连接机制导致，和ZooKeeper端口连通性无关：

• HBase客户端连接分两步：首先连接配置中指定的ZooKeeper节点，再从ZooKeeper中获取HBase Master、RegionServer的注册地址，直接对该地址发起连接
• 你的容器通过-h hbb设置了内部主机名，HBase默认会将这个仅容器内部可解析的主机名、Docker网桥内网IP注册到ZooKeeper中
• 运行在Windows宿主机的Scala客户端拿到hbb这个内部主机名后，无法在宿主机网络中解析到对应IP，直接抛出地址解析失败错误
• 之前尝试将ZooKeeper地址改为localhost、手动配置hosts映射未生效的原因：前者仅解决了第一步ZooKeeper连接的问题，ZooKeeper返回的HBase服务地址仍是内部地址；后者无法匹配容器动态变化的内网IP，也无法覆盖HBase注册的主机名地址。

1. 修改容器内HBase配置 #

更新容器中conf/hbase-site.xml，补充服务监听、地址注册相关配置，强制HBase注册宿主机可访问的地址：

<configuration>
  <!-- 保留原有已配置参数 -->
  <property>
    <name>hbase.cluster.distributed</name>
    <value>false</value>
  </property>
  <property>
    <name>hbase.unsafe.stream.capability.enforce</name>
    <value>false</value>
  </property>
  <!-- 新增以下配置 -->
  <!-- 绑定所有网卡监听请求 -->
  <property>
    <name>hbase.master.ipc.address</name>
    <value>0.0.0.0</value>
  </property>
  <property>
    <name>hbase.regionserver.ipc.address</name>
    <value>0.0.0.0</value>
  </property>
  <!-- 核心配置：强制向ZooKeeper注册宿主机可访问的回环地址，走Docker端口映射 -->
  <property>
    <name>hbase.master.hostname</name>
    <value>127.0.0.1</value>
  </property>
  <property>
    <name>hbase.regionserver.hostname</name>
    <value>127.0.0.1</value>
  </property>
  <property>
    <name>hbase.zookeeper.quorum</name>
    <value>127.0.0.1</value>
  </property>
  <property>
    <name>hbase.zookeeper.property.clientPort</name>
    <value>2181</value>
  </property>
</configuration>

2. 调整容器启动命令 #

去掉单机模式用不到的集群端口映射，保留核心服务端口即可：

docker run -itd \
  -p 2181:2181 \
  -p 16000:16000 \
  -p 16010:16010 \
  -p 16020:16020 \
  -p 16030:16030 \
  hbase-1

注：2888、3888为ZooKeeper集群内部通信端口，8080为HBase REST服务默认端口，单机伪分布式模式无需映射。

3. 更新Scala客户端配置 #

移除无效的硬编码hbase.master、内部主机名配置，客户端会自动从ZooKeeper动态发现服务地址：

val conf : Configuration = HBaseConfiguration.create()
conf.set("hbase.zookeeper.quorum", "127.0.0.1")
conf.set("hbase.zookeeper.property.clientPort", "2181")
conf.set("hbase.cluster.distributed","false")
// 测试阶段可打开以下重试配置，减少连接失败等待时间
conf.set("hbase.client.pause", "1000")
conf.set("hbase.client.retries.number", "3")
conf.set("zookeeper.recovery.retry", "2")
val connection = ConnectionFactory.createConnection(conf)

4. 有效性验证 #

1. 重新构建HBase镜像并启动容器，进入容器执行hbase shell确认基础操作正常
2. 访问http://127.0.0.1:16010打开HBase Web UI，确认页面上展示的Master、RegionServer地址为127.0.0.1，若仍显示hbb或容器内网IP说明配置未生效
3. 运行Scala客户端代码测试连接，不会再出现地址解析类报错。

• 本地开发环境用端口映射的方式部署HBase时，必须显式配置hbase.master.hostname和hbase.regionserver.hostname为宿主机可访问的地址，否则默认注册的容器内部地址永远无法被宿主机客户端访问
• 若使用WSL2后端的Docker Desktop出现回环地址映射异常，可将上述配置中的127.0.0.1替换为host.docker.internal，这是Docker Desktop提供的宿主机专用解析域名
• 不要在客户端硬编码hbase.master参数，该参数仅适用于无ZooKeeper的本地文件模式，正常场景下硬编码会覆盖ZooKeeper的动态发现逻辑，引发不必要的连接问题。

内容的提问来源于stack exchange，提问作者Fusion