Java项目Kubernetes部署实战：镜像构建、健康检查与配置管理

1. 项目整体设计与思路拆解

把Java项目搬上Kubernetes，这件事在五年前可能还是个“高级玩法”，现在基本已经是中大型团队的标配了。但标配归标配，真正动手的时候你会发现，坑一点都不少。我见过太多团队把Spring Boot应用往K8s一扔，结果镜像拉取失败、健康检查永远不通过、日志找不到、配置改不动，最后又灰溜溜地退回虚拟机部署。问题出在哪？不是K8s不好用，而是Java应用和K8s的“脾气”需要磨合。

这个项目的核心目标很明确：把一个标准的Java后端服务（以Spring Boot为例）完整地部署到Kubernetes集群中，并且让它具备生产级别的基本能力——包括镜像构建、配置管理、健康检查、日志收集、资源限制和滚动更新。适合谁看？如果你已经写过Dockerfile，对K8s的Pod、Service有概念但没完整走过一遍部署流程，或者你部署过但总出各种小毛病，那这篇内容就是给你准备的。

先说整体思路。Java项目上K8s，本质上要解决三个层面的问题：构建层（怎么把Jar包变成镜像）、编排层（怎么让K8s知道你的应用需要什么资源、怎么判断它活着）、运维层（怎么改配置、怎么看日志、怎么更新版本）。很多人只关注第一层，觉得镜像推上去就完事了，结果后面两层全是坑。

为什么选择Spring Boot作为示例？因为它的生态最成熟，和K8s的适配方案最多，而且大部分Java团队都在用。如果你用的是其他框架，核心思路一样，只是细节参数需要调整。

在方案选型上，我倾向于用多阶段构建来打镜像。什么意思？就是在一个Dockerfile里分两个阶段：第一个阶段用Maven镜像编译打包，第二个阶段只用JRE运行。这样做的好处是最终镜像里没有Maven、没有源码、没有构建缓存，体积能从七八百兆压到两百兆以内。别小看这个体积差，在集群规模大的时候，镜像拉取时间直接影响到扩容速度。

配置管理方面，我建议用ConfigMap挂载配置文件加Secret管理敏感信息的组合。有些团队图省事，直接把application.yml打进镜像里，改个数据库地址就要重新构建推送，这在生产环境里是灾难。正确的做法是把配置外置，镜像只包含代码和默认配置，环境相关的配置通过ConfigMap注入。

健康检查是另一个重灾区。Spring Boot Actuator提供了/actuator/health端点，但很多人不知道要把它暴露出来，也不清楚liveness和readiness探针的区别。简单说，liveness探针判断应用是否还活着，失败了K8s会重启Pod；readiness探针判断应用是否能接收流量，失败了K8s会把它从Service的Endpoints里摘掉。这两个探针的配置参数完全不一样，配错了要么频繁重启，要么流量打到还没准备好的实例上。

资源限制这块，我见过太多人要么不设，要么随便写个512Mi。不设资源限制的Pod在节点资源紧张时会被OOM Killer干掉，设得太小又会导致应用频繁GC甚至启动失败。合理的做法是先跑一段时间观察实际用量，再根据监控数据来调整。

2. 核心细节解析与实操要点

2.1 镜像构建：多阶段构建的细节与避坑

先看Dockerfile的写法。我一般会这样组织：

# 第一阶段：构建 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn package -DskipTests -B # 第二阶段：运行 FROM eclipse-temurin:17-jre-jammy WORKDIR /app COPY --from=builder /build/target/*.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "app.jar"]

这里有几个关键点值得展开说。第一，为什么先COPY pom.xml再RUN mvn dependency:go-offline，最后才COPY src？这是为了利用Docker的层缓存。只要pom.xml没变，依赖下载这一层就不会重新执行。我实测过，一个中等规模的Spring Boot项目，依赖下载要两三分钟，如果每次改代码都重新下载，构建时间直接翻倍。

第二，基础镜像的选择。eclipse-temurin:17-jre-jammy这个镜像基于Ubuntu Jammy，包含了完整的glibc和时区数据，兼容性最好。如果你追求极致体积，可以用alpine版本，但要注意alpine用的是musl libc，某些依赖native库的Java应用可能会出问题。我踩过一次坑，一个用了Netty的项目在alpine镜像里跑不起来，排查了半天才发现是DNS解析的native实现不兼容。

第三，JVM参数。在容器里跑Java，JVM默认会读取宿主机的内存和CPU信息，而不是容器的限制。这会导致堆内存设置过大，Pod被OOM Kill。解决办法是加上-XX:MaxRAMPercentage=75.0，让JVM按容器内存限制的百分比来设置堆大小。如果你用的是JDK 10以上，默认已经支持容器感知了，但显式指定更保险。

注意：不要用-Xmx写死堆大小，除非你非常确定Pod的内存限制不会变。用MaxRAMPercentage更灵活。

2.2 健康检查：探针参数的计算与配置

Spring Boot Actuator的health端点默认只返回{"status":"UP"}，不包含详细信息。要让它能反映数据库、Redis等依赖的状态，需要配置management.endpoint.health.show-details=always。但这里有个坑：如果数据库挂了，health端点会返回DOWN，readiness探针失败，Pod被摘流量——这是对的。但liveness探针也会失败，导致Pod被重启——这就没必要了，因为重启也解决不了数据库的问题。

所以我的做法是：liveness探针只检查应用进程本身，用一个轻量的端点比如/actuator/health/liveness；readiness探针检查完整依赖，用/actuator/health/readiness。Spring Boot 2.3以上支持健康检查分组，配置如下：

management: endpoint: health: probes: enabled: true group: liveness: include: livenessState readiness: include: readinessState,db,redis

探针的参数也需要仔细算。initialDelaySeconds要大于应用启动时间，periodSeconds和timeoutSeconds要根据接口响应时间来定。我一般会这样设：

为什么liveness的initialDelaySeconds要比readiness大？因为readiness失败只是摘流量，不影响应用启动；但liveness失败会重启Pod，如果启动时间没给够，Pod会陷入“启动-被杀-再启动”的死循环。

2.3 配置管理：ConfigMap与Secret的正确用法

ConfigMap挂载配置文件有两种方式：volume挂载和环境变量注入。我强烈建议用volume挂载，因为环境变量里的特殊字符（比如换行、引号）容易出问题，而且环境变量在Pod启动后就固定了，改ConfigMap需要重启Pod。Volume挂载的话，ConfigMap更新后文件会自动更新（有延迟），配合Spring Boot的配置刷新机制可以实现热更新。

具体做法是把application.yml放在ConfigMap里，挂载到/app/config/目录，然后启动命令加上--spring.config.additional-location=/app/config/。这样Spring Boot会优先读取挂载的配置，覆盖jar包里的默认配置。

Secret的用法类似，但要注意Secret的值是base64编码的，创建的时候用kubectl create secret generic命令会自动编码，不要手动去echo再base64，容易出错。另外，Secret挂载到volume里是明文文件，如果对安全性要求高，可以考虑用外部Secret管理方案，但那是另一个话题了。

提示：ConfigMap和Secret的大小限制是1MB，别把整个日志文件塞进去。

3. 实操过程与核心环节实现

3.1 从零开始：完整部署流程

假设你已经有一个能正常运行的Spring Boot项目，本地mvn package能打出jar包。接下来我们一步步把它部署到K8s。

第一步：构建并推送镜像。先确认你的Dockerfile放在项目根目录，然后执行：

docker build -t your-registry/java-app:1.0.0 . docker push your-registry/java-app:1.0.0

这里注意镜像tag不要用latest，生产环境用latest会导致滚动更新时无法确定版本。我习惯用语义化版本号或者Git commit hash。

第二步：创建ConfigMap。把application.yml的内容拿出来，去掉敏感信息，创建ConfigMap：

kubectl create configmap java-app-config \ --from-file=application.yml=./config/application.yml \ -n your-namespace

第三步：创建Secret。数据库密码、Redis密码这些：

kubectl create secret generic java-app-secret \ --from-literal=db-password='your-password' \ --from-literal=redis-password='your-redis-password' \ -n your-namespace

第四步：编写Deployment。这是核心部分，我把它拆成几个关键块来看：

apiVersion: apps/v1 kind: Deployment metadata: name: java-app namespace: your-namespace spec: replicas: 3 strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0 selector: matchLabels: app: java-app template: metadata: labels: app: java-app spec: containers: - name: java-app image: your-registry/java-app:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_PROFILES_ACTIVE value: "prod" - name: DB_PASSWORD valueFrom: secretKeyRef: name: java-app-secret key: db-password resources: requests: memory: "512Mi" cpu: "250m" limits: memory: "1Gi" cpu: "1000m" livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 60 periodSeconds: 10 timeoutSeconds: 3 failureThreshold: 3 readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 30 periodSeconds: 5 timeoutSeconds: 3 failureThreshold: 3 volumeMounts: - name: config-volume mountPath: /app/config readOnly: true volumes: - name: config-volume configMap: name: java-app-config

这里有几个参数需要解释。maxUnavailable: 0表示滚动更新时不允许有不可用的Pod，maxSurge: 1表示可以临时多出一个Pod。这样配置能保证更新过程中服务不中断，但需要集群有足够的资源。

资源限制里的requests和limits的区别：requests是调度依据，K8s会把Pod分配到有足够资源的节点；limits是硬限制，超过会被限制或杀掉。我一般设requests为limits的一半左右，这样调度器有弹性空间。

第五步：创建Service。让其他服务能访问到：

apiVersion: v1 kind: Service metadata: name: java-app-svc namespace: your-namespace spec: selector: app: java-app ports: - port: 80 targetPort: 8080 type: ClusterIP

如果需要对外暴露，可以用Ingress或者NodePort，但生产环境建议用Ingress配合Ingress Controller。

第六步：应用并验证。

kubectl apply -f deployment.yaml kubectl apply -f service.yaml kubectl get pods -n your-namespace -w

看到Pod状态变成Running并且READY是1/1，就说明部署成功了。

3.2 JVM调优：容器环境下的参数计算

在K8s里跑Java，JVM参数需要根据Pod的资源限制来调整。假设limits.memory是1Gi，我一般会这样设置：

java -XX:MaxRAMPercentage=75.0 \ -XX:InitialRAMPercentage=50.0 \ -XX:+UseG1GC \ -XX:MaxGCPauseMillis=200 \ -jar app.jar

MaxRAMPercentage=75.0意味着堆内存最大约768Mi，剩下的256Mi留给Metaspace、线程栈、直接内存等。为什么是75%而不是更高？因为JVM除了堆之外还有很多内存开销，设太高容易触发OOM。

UseG1GC是JDK 9以上的默认GC，但在容器环境里显式指定更放心。MaxGCPauseMillis=200是G1的目标停顿时间，对于大多数Web应用来说200ms是可以接受的。

如果你用的是JDK 8，容器感知需要加-XX:+UseContainerSupport，而且MaxRAMPercentage的默认值可能不一样，建议升级到JDK 11或17。

注意：不要同时用-Xmx和MaxRAMPercentage，后者会被忽略。

3.3 日志方案：让日志可查可追

Java应用的日志默认输出到stdout，K8s会自动收集。但Spring Boot默认的日志格式是单行的，没有结构化，排查问题时不好过滤。我建议用JSON格式输出日志，配合logback的JSON encoder：

<encoder class="net.logstash.logback.encoder.LogstashEncoder"> <includeMdcKeyName>traceId</includeMdcKeyName> <includeMdcKeyName>spanId</includeMdcKeyName> </encoder>

这样每条日志都是JSON，包含时间戳、级别、类名、traceId等字段。在Kibana或Loki里可以直接按traceId搜索，快速定位一次请求的所有日志。

如果不想引入额外依赖，至少要把日志格式改成包含时间戳和线程名的格式，方便排查。

4. 常见问题与排查技巧实录

4.1 镜像拉取失败：从ImagePullBackOff说起

Pod状态显示ImagePullBackOff，原因通常有三个：镜像名写错、镜像仓库需要认证、网络不通。排查步骤：

kubectl describe pod <pod-name> -n <namespace>

看Events部分，如果是manifest unknown就是镜像名或tag错了；如果是unauthorized就是缺少imagePullSecret；如果是timeout就是网络问题。

创建imagePullSecret的方法：

kubectl create secret docker-registry regcred \ --docker-server=your-registry \ --docker-username=your-username \ --docker-password=your-password \ -n your-namespace

然后在Deployment的spec里加上imagePullSecrets: - name: regcred。

4.2 健康检查失败：探针配置的常见误区

Pod一直重启，describe看到Liveness probe failed。可能的原因：

• 端点路径写错。Spring Boot 2.3以上默认的liveness端点是/actuator/health/liveness，但需要先启用probes。
• 端口写错。containerPort和探针的port要一致。
• 启动时间不够。initialDelaySeconds太小，应用还没启动完就被判定失败。
• 应用本身启动失败。看Pod日志确认。

我遇到过一次，应用启动要90秒，但initialDelaySeconds设了60秒，结果Pod一直在重启。改成120秒后正常。

4.3 配置不生效：ConfigMap挂载的坑

ConfigMap更新后，挂载的文件不会立即更新，默认有几十秒到几分钟的延迟。而且Spring Boot默认不会重新读取配置文件，需要配合spring-cloud-starter-bootstrap或者手动触发refresh。

更常见的坑是：ConfigMap挂载到目录时，会覆盖目录下所有文件。如果你挂载到/app/config，而jar包里也有/app/config目录，里面的文件会被覆盖。解决办法是挂载到不同的目录，或者用subPath只挂载单个文件。

4.4 内存溢出：OOM Killer的排查

Pod被OOM Kill，状态显示OOMKilled。排查思路：

1. 看Pod的resources.limits.memory是否太小。
2. 看JVM的堆设置是否超过了容器限制。
3. 用kubectl top pod看实际内存用量。
4. 如果堆内存正常但容器内存超了，可能是Metaspace或直接内存泄漏。

我处理过一次，应用堆内存只用了400Mi，但容器内存到了1.5Gi。最后发现是Netty的直接内存没释放，加-XX:MaxDirectMemorySize=256m解决了。

4.5 常见问题速查表

4.6 独家避坑技巧

技巧一：用initContainer做数据库迁移。如果应用启动时需要执行Flyway或Liquibase迁移，不要放在主容器里，用initContainer。这样迁移失败时主容器不会启动，问题更清晰。

技巧二：给Pod加preStop钩子。应用收到SIGTERM后需要时间处理完正在进行的请求。加一个preStop让Pod等几秒再退出：

lifecycle: preStop: exec: command: ["sh", "-c", "sleep 10"]

配合Spring Boot的graceful shutdown（server.shutdown=graceful），可以做到零中断更新。

技巧三：用PodDisruptionBudget保护可用性。在节点维护时，PDB能保证至少有N个Pod可用：

apiVersion: policy/v1 kind: PodDisruptionBudget metadata: name: java-app-pdb spec: minAvailable: 2 selector: matchLabels: app: java-app

技巧四：镜像tag用Git commit hash。这样每次部署都能追溯到具体的代码版本，回滚也方便。

技巧五：本地调试用kubectl port-forward。不用改Service类型，直接kubectl port-forward pod/<pod-name> 8080:8080就能在本地访问。

我在实际部署中最大的体会是：K8s的配置项很多，但核心就那么几个——资源限制、健康检查、配置管理。把这三点做扎实，80%的问题都不会出现。剩下的20%需要根据具体应用的特点来调整，比如有的应用启动慢，有的应用内存波动大，有的应用需要特殊的网络配置。多部署几次，多踩几个坑，自然就熟了。