Kubernetes 上跑 Java 服务：Quarkus 与 HBase 组合实战

别人问我为什么在Kubernetes上跑Java服务，最后绕不开Quarkus和HBase这个组合。这俩放一起，乍一看一个是云原生Java框架，一个是老牌分布式列式数据库，好像没什么交集。但真在K8s里把有状态的HBase集群和无状态的Java服务编排到一起的时候，你会发现Quarkus几乎是为这个场景量身定做的。这篇文章我用自己的实际项目经验，把HBase和Quarkus在Kubernetes原生环境下的搭配思路、踩坑记录、部署细节一次说清楚，适合正在做微服务拆分、想把Java应用容器化部署到K8s上的开发者参考。

先说结论：这个组合解决的核心问题有三个——Java应用在K8s里启动太慢导致滚动更新卡顿、内存占用太高导致节点资源紧张、以及HBase这种重量级客户端服务在容器环境下的连接管理难题。Quarkus通过GraalVM原生镜像和构建期元数据处理，把启动时间从秒级压到毫秒级，内存占用从几百MB降到几十MB；HBase则提供了完整的分布式存储能力和成熟的数据模型。两者结合，正好覆盖了云原生应用最关键的存储与计算两端。

1. 为什么是HBase和Quarkus这对组合

1.1 HBase在云原生场景里的真实定位

HBase这个项目在Java生态里活了很多年，它基于LSM树实现高吞吐写入，天然适合海量结构化数据的随机读写场景。我在实际项目中见到的用法很多样：有拿它存埋点日志的，有拿它做用户画像的，也有拿它当特征存储的。

但把HBase搬到Kubernetes上之后，很多人第一反应是“太重了”。HBase本身包含HMaster、RegionServer、ZooKeeper三个核心组件，部署一套完整的集群需要不少资源。这时候如果业务侧还是按照传统方式写一堆Spring Boot服务去连HBase，每个服务都维护一个连接池，整个集群的资源利用率会很难看。

Kubernetes原生Java应用的核心诉求是快速弹性伸缩、资源精细化管理。而HBase这边，真正需要的其实是一个清晰的数据访问边界——让业务应用不直接依赖HBase内部的RegionServer分布和ZooKeeper状态，而是通过标准化的API访问数据。这个思路和Quarkus的“构建期尽量搞定一切、运行期只保留必要组件”的理念是相互呼应的。

1.2 Quarkus到底解决了什么问题

Quarkus不是简单的Spring Boot替代品，它在设计哲学上就奔着云原生去的。普通Java应用跑在JVM里，启动时要做类加载、字节码校验、Spring容器初始化这一大堆事情，再快的机器也要几秒钟。而Quarkus在构建阶段就完成了类路径扫描和元数据处理，运行期直接以原生可执行文件的方式跑，启动时间能压到几十毫秒。

我实测过一个典型的订单查询服务，Spring Boot 2.7版本打包成容器镜像后，冷启动时间大约在8到12秒，内存占用动辄500MB起步。换成Quarkus原生镜像后，同样功能的服务启动只要0.2秒左右，常驻内存降到80MB上下。这个差距在K8s里非常宝贵：滚动更新时新Pod能秒级Ready，副本缩容时资源释放也更干净。

而且Quarkus对Kubernetes的无缝集成一直是它的核心竞争力之一。通过quarkus-kubernetes扩展，构建时可以自动生成Deployment、Service、ConfigMap等清单文件，配合Jib或Dockerfile就能一键出镜像。

1.3 和传统Spring Boot方案的对比

我把两种方案放在一起对比过，差异非常明显：

1.4 什么时候不适合这个组合

不是所有项目都适合上Quarkus + HBase。如果你们团队没有容器化经验，HBase集群本身就是单机伪分布模式在跑，那先把运维基本功打牢更重要。另外，如果业务逻辑重度依赖HBase的协处理器或自定义Filter，走REST网关就会碰壁，这种场景还是得用直连客户端。

但反过来，如果你的业务主要是标准化的读写模式——按RowKey查询、按条件扫描、批量写入——REST网关那点性能损耗完全可控，换来的部署弹性和资源节省非常划算。

2. 搭建环境与初始化项目骨架

2.1 本地开发环境准备

开发环境我用的是Docker Compose拉起一套单机版HBase。注意这里说的是伪分布模式，不是真正的高可用集群，但本地验证API调用和Quarkus代码逻辑完全够用。

version: "3" services: hbase: image: hbase-docker:2.4.5 container_name: hbase-local ports: - "16010:16010" - "8080:8080" - "2181:2181" environment: - HBASE_MODE=standalone

这个镜像里自带了HBase REST网关（端口8080）和HBase UI（端口16010）。启动完成后，访问http://localhost:8080/version能返回REST API版本信息，说明网关已经OK了。如果只用Quarkus连REST网关，ZooKeeper端口2181其实用不上，我本地开着纯粹为了调试方便。

2.2 Quarkus项目初始化

用IDEA或者命令行创建Quarkus项目都行。命令行的话：

mvn io.quarkus:quarkus-maven-plugin:create \ -DprojectGroupId=com.demo \ -DprojectArtifactId=hbase-quarkus-demo \ -DclassName="com.demo.HBaseResource" \ -Dpath="/hbase"

创建完成后，建议加上几个扩展：

./mvnw quarkus:add-extension -Dextensions="resteasy-reactive,rest-client-reactive,jsonb,kubernetes,container-image-jib"

• resteasy-reactive：REST端点的基础
• rest-client-reactive：用来调HBase REST网关
• jsonb：处理JSON序列化
• kubernetes + container-image-jib：一键生成K8s清单和镜像

2.3 关键依赖配置

pom.xml里需要显式声明HBase REST客户端的相关依赖。这里我不建议引入完整的hbase-client，因为那会把ZooKeeper和Hadoop的依赖全部带进来，原生编译时会非常痛苦。只引入hbase-rest-client或者干脆自己用Quarkus的REST Client写调用即可。

<dependency> <groupId>org.apache.hbase</groupId> <artifactId>hbase-rest-client</artifactId> <version>${hbase.version}</version> <exclusions> <exclusion> <groupId>org.apache.hadoop</groupId> <artifactId>hadoop-common</artifactId> </exclusion> </exclusions> </dependency>

如果是走直连模式，需要引入hbase-client和相关hadoop依赖，这个下面第3节专门讲，因为涉及原生编译时的反射问题，配置方式差别很大。

2.4 应用配置文件

application.properties里最核心的配置是HBase REST网关的地址。建议不要写死IP，而是通过环境变量注入，这样同一个镜像在本地和K8s里都能直接用：

# HBase REST网关地址 hbase.rest.url=${HBASE_REST_URL:http://localhost:8080} quarkus.http.port=8081 # 原生镜像模式下，JSONB序列化反射处理 quarkus.native.additional-bundles=org.jboss.logging # 连接超时配置（毫秒） hbase.rest.connect-timeout=3000 hbase.rest.read-timeout=5000

3. 数据访问层：从直连到REST网关的取舍

3.1 直连模式的完整配置

直连模式适合对读写延迟极度敏感、且能够接受复杂依赖的场景。配置方式是这样的：

@ApplicationScoped public class HBaseConnectionProvider { @Produces public Connection hBaseConnection() { org.apache.hadoop.conf.Configuration config = HBaseConfiguration.create(); config.set("hbase.zookeeper.quorum", System.getenv().getOrDefault("HBASE_ZOOKEEPER_QUORUM", "localhost:2181")); config.set("hbase.zookeeper.property.clientPort", "2181"); config.set("zookeeper.session.timeout", "30000"); try { return ConnectionFactory.createConnection(config); } catch (IOException e) { throw new RuntimeException("Failed to create HBase connection", e); } } }

然后写一个DAO类，用Table接口做读写：

public class UserProfileDao { private static final byte[] CF = Bytes.toBytes("info"); private static final byte[] COL_NAME = Bytes.toBytes("name"); private static final byte[] COL_AGE = Bytes.toBytes("age"); public UserProfile get(String rowKey) { try (Table table = connection.getTable(TableName.valueOf("user_profile"))) { Get get = new Get(Bytes.toBytes(rowKey)); Result result = table.get(get); if (result.isEmpty()) { return null; } UserProfile profile = new UserProfile(); profile.setRowKey(rowKey); profile.setName(Bytes.toString(result.getValue(CF, COL_NAME))); profile.setAge(Bytes.toInt(result.getValue(CF, COL_AGE))); return profile; } catch (IOException e) { throw new RuntimeException("HBase get failed", e); } } }

这个方案在建表、扫描、批量写方面功能最全，但有两个硬伤：一是hbase-client依赖体积大，原生编译时反射配置多到让人抓狂；二是每增加一个业务服务就多一套连接池，K8s集群里连接数会迅速膨胀。

3.2 通过REST网关封装数据访问

REST网关方案让每个Quarkus服务变成一个纯粹的无状态HTTP客户端，连接管理交给HBase集群自己处理。我用Quarkus自带的REST Client定义一个调用HBase REST API的接口：

@Path("/") @RegisterRestClient(configKey = "hbase-rest") public interface HBaseRestClient { @GET @Path("/{table}/{rowKey}") @Produces(MediaType.APPLICATION_JSON) String getRow(@PathParam("table") String table, @PathParam("rowKey") String rowKey); @PUT @Path("/{table}/{rowKey}") @Consumes(MediaType.APPLICATION_JSON) Response putRow(@PathParam("table") String table, @PathParam("rowKey") String rowKey, String body); @GET @Path("/{table}/scanner") @Produces(MediaType.APPLICATION_JSON) String createScanner(@PathParam("table") String table); @DELETE @Path("/{table}/scanner/{scanId}") Response deleteScanner(@PathParam("table") String table, @PathParam("scanId") String scanId); }

然后在application.properties里指定这个客户端的基地址：

quarkus.rest-client.hbase-rest.url=${HBASE_REST_URL:http://localhost:8080} quarkus.rest-client.hbase-rest.connect-timeout=3000 quarkus.rest-client.hbase-rest.read-timeout=5000

服务层调用时注入这个接口即可：

@ApplicationScoped public class UserProfileService { @Inject @RestClient HBaseRestClient hbaseClient; public String getUser(String rowKey) { return hbaseClient.getRow("user_profile", rowKey); } public void saveUser(String rowKey, UserProfile profile) { String json = JsonbBuilder.create().toJson(profile); hbaseClient.putRow("user_profile", rowKey, json); } }

REST网关的API返回格式基于JSON的Cell表示，HBase网关默认会把每个单元格映射成{"Row": [...], "Cell": [...]}的结构。如果需要更友好的对象映射，可以在服务层做一次反序列化，这里的数据格式转换逻辑可以根据自己表的列族设计来定制。

3.3 RowKey设计与数据模型映射的实践心得

无论直连还是REST网关，RowKey设计都是HBase开发绕不开的坎。我在做某个IoT设备数据平台的时候，一开始图省事直接用设备ID作为RowKey前缀，结果写入量上来后全部请求打到一个Region上，RegionServer直接成为瓶颈。

后来改成“设备ID反转 + 时间戳倒序”的组合，把写入压力均匀分散到多个Region，读取最近数据的场景也能利用倒序时间戳快速定位。这个细节特别值得注意，因为K8s场景下HBase的Region分配和Pod调度是两套系统，热点问题会被放得更大。

数据模型映射方面，建议在Java侧单独写一个转换层，不要直接把JSON字符串塞进HBase单元格。HBase作为列式存储，每一列的字节数组存储效率差异很大，字符串类型和二进制类型混用会导致表结构混乱。我在项目里统一用Protocol Buffers做序列化，配合Quarkus原生镜像的反射配置反而比JSONB更干净。

3.4 原生编译的反射坑

如果非要用直连模式跑Quarkus原生镜像，反射配置基本逃不掉。hbase-client底层大量用到了Hadoop的Configuration反射机制，还有Protobuf的序列化类。需要在reflect-config.json里手动注册一堆类：

[ { "name": "org.apache.hadoop.hbase.client.ConnectionFactory", "allDeclaredMethods": true, "allDeclaredConstructors": true }, { "name": "org.apache.hadoop.hbase.protobuf.generated.ClientProtos", "allDeclaredMethods": true } ]

但每次升级HBase版本，这个配置文件就要重新调试一轮，非常痛苦。我自己的经验是：原生镜像模式坚决走REST网关，直连模式老老实实用JVM模式跑。这两个选择不应该混在一起。

4. 容器化构建与Kubernetes部署路径

4.1 构建原生镜像

Quarkus构建原生镜像的流程并不复杂，前提是Docker环境可用：

./mvnw package -Dquarkus.package.type=native \ -Dquarkus.native.container-build=true \ -Dquarkus.container-image.build=true

这条命令会先在容器里执行GraalVM的native-image编译，然后调用Jib或Dockerfile生成最终镜像。用了rest-client-reactive扩展后，HBase REST调用相关的GraalVM反射需求已经内置处理，不需要额外配置。

需要注意的是，第一次native编译会比较耗时，我实测在一台8核16G的机器上大概需要3到5分钟。之后的增量编译会快很多，但如果改了依赖版本，可能又要重新走一遍完整流程。

4.2 多阶段Dockerfile参考

如果不用Jib，可以自己写多阶段Dockerfile：

# Stage 1: 构建原生镜像 FROM quay.io/quarkus/ubi-quarkus-graalvm-builder-image:22.3-java17 AS build COPY --chown=quarkus:quarkus mvnw /workspace/mvnw COPY --chown=quarkus:quarkus pom.xml /workspace/pom.xml RUN chmod +x /workspace/mvnw && cd /workspace && ./mvnw dependency:go-offline COPY --chown=quarkus:quarkus src /workspace/src RUN cd /workspace && ./mvnw package -Dquarkus.package.type=native # Stage 2: 运行镜像 FROM registry.access.redhat.com/ubi8/ubi-minimal:8.9 WORKDIR /work/ COPY --from=build /workspace/target/*-runner /work/application COPY --from=build /workspace/target/*-runner.jar /work/application.jar EXPOSE 8081 ENTRYPOINT ["./application"]

这里有个细节：UBI minimal基础镜像本身很小，但如果你需要运行时的证书库或者时区文件，记得手工拷贝，否则访问带TLS的HBase REST网关时会报证书错误。

4.3 Kubernetes部署清单

Deployment和Service的清单我直接给出可用版本：

apiVersion: apps/v1 kind: Deployment metadata: name: hbase-quarkus-demo labels: app: hbase-quarkus-demo spec: replicas: 3 selector: matchLabels: app: hbase-quarkus-demo template: metadata: labels: app: hbase-quarkus-demo spec: containers: - name: hbase-quarkus-demo image: registry.example.com/demo/hbase-quarkus-demo:1.0.0 imagePullPolicy: IfNotPresent ports: - containerPort: 8081 name: http env: - name: HBASE_REST_URL value: "http://hbase-rest.default.svc.cluster.local:8080" resources: requests: memory: "128Mi" cpu: "250m" limits: memory: "256Mi" cpu: "500m" livenessProbe: httpGet: path: "/health/live" port: 8081 initialDelaySeconds: 3 periodSeconds: 10 readinessProbe: httpGet: path: "/health/ready" port: 8081 initialDelaySeconds: 3 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: hbase-quarkus-demo spec: selector: app: hbase-quarkus-demo ports: - name: http port: 8081 targetPort: 8081 type: ClusterIP

Quarkus默认暴露的/health/live和/health/ready端点在这套配置里刚好用上，不需要额外改代码。

4.4 网络拓扑与安全组配置

K8s里访问HBase集群，建议走Headless Service或者ClusterIP类型的稳定DNS地址。我在生产环境就是这么做的：

hbase-rest.default.svc.cluster.local

如果HBase集群部署在独立Namespace，记得检查NetworkPolicy是否放行对应端口。REST网关模式只需要打开8080端口，直连模式则要开放2181和所有RegionServer的RPC端口（通常是16020/16030），后者在K8s网络策略里配置起来麻烦得多。

5. 生产环境常见问题与排查实录

5.1 高频问题速查表

5.2 我踩过的三次典型故障

第一个是Quarkus原生模式下使用HBase直连客户端，编译时反射配置缺了Protobuf的类，运行期只要一调用get就抛异常。我尝试在reflect-config.json里补齐，但每次hbase-client版本升级就要重新排查一轮，后来彻底切到REST网关模式才根治。

第二个是K8s里Pod的DNS解析问题。我在本地用localhost访问REST网关一切正常，移到K8s后超时。排查半天发现是HBase REST网关的Service selector写得有问题，根本没匹配到后端Pod。kubectl get endpoints一下就暴露了，这个检查动作建议每次部署后都做一遍。

第三个是原生镜像在受限的Pod安全上下文里跑不起来。Quarkus原生可执行文件默认是动态链接到glibc的，如果集群强制开启SELinux或使用只读文件系统，需要在镜像构建时加入-Dquarkus.native.enable-static-linking=true，编译出静态链接的二进制，绕开这类运行限制。

5.3 性能调优的实测数据

我拿同一套查询接口做了一次简单压测，Quarkus原生镜像模式单Pod 512MB内存、2核CPU，QPS压到800时，CPU使用率约65%，内存稳定在140MB上下。同逻辑的JVM模式在相同限制下跑到400就开始FullGC频繁，响应延迟明显爬升。这就是云原生场景下Quarkus的价值——单位资源能扛住更多流量，且GC压力小得多。

HBase侧的调优主要看RegionServer的数量和Region预分区。我在某个批量导入项目里预先建了20个Region，写入速率直接翻了近一倍。如果你在K8s里用HBase Operator管理集群，建议创建表时规划好分区数，不要等数据涨起来才做split操作。

5.4 连接池与缓存的设计建议

REST网关模式虽然无状态，但也不要每个请求都重复建立HTTP连接。我建议在Quarkus侧配置一个简单的连接池：

@ApplicationScoped public class RestClientProducer { @Produces @ApplicationScoped public HBaseRestClient produceRestClient() { HBaseRestClient client = new HBaseRestClientImpl(); return client; } }

实际上Quarkus的REST Client Reactive底层基于Vert.x，已经内置了连接复用机制，不用重复造轮子。你只需要合理配置quarkus.http.idle-timeout和quarkus.http.connection-idle-timeout，避免空闲连接长时间占着不释放。

缓存方面，如果业务数据允许一定程度的一致性延迟，强烈建议在服务层加一层Caffeine缓存。热点数据的读压力能够直接消化在Pod内部，不给HBase集群增加请求量。我习惯把缓存TTL设置在30秒到5分钟之间，具体要看业务容忍度。

5.5 监控与告警的最小配置

Quarkus应用接Prometheus用的是自带的quarkus-micrometer-registry-prometheus扩展，加依赖后打开/q/metrics端点即可。HBase本身的监控则依赖JMX和HBase UI暴露的指标。

我的经验是至少盯四个指标：Quarkus侧的请求延迟P99、Pod内存使用率、HBase侧的RegionServer平均负载、REST网关活跃连接数。这四个指标能覆盖从入口到存储的完整链路，出现问题的时候能够快速定位是应用层瓶颈还是存储层瓶颈。

注意：K8s的Pod内存限制一定要比Quarkus实际使用量留出20%到30%的余量。原生镜像的内存是线性增长的，但GC余量和Vert.x的堆外缓冲仍然需要空间，设置太极限会导致Pod被频繁OOMKill。

最后再分享一个经验：刚开始做这个组合的时候，别急着把核心业务全部切到Quarkus上来，先用一个非核心查询服务跑通“Quarkus + HBase REST网关 + K8s部署”这条完整链路，把网络模型、监控告警、发布流程都理顺了，再逐步扩大范围。我在实践中就是这样一步一步把几十个服务全部迁到这套架构上的，整体切换过程平滑得多。HBase不管直连还是走REST网关，RowKey设计和列族规划这些基本功永远不能丢，它们决定的数据分布质量，在K8s这种动态调度环境下会被放大成明显的性能差异。这大概就是这个组合最真实的吸引力——计算侧极致弹性，存储侧稳定可靠，中间打通链路之后，每一步都值得仔细打磨。