K8s 集群里 Maven 构建失败怎么排查

在 K8s 集群里跑 Maven 构建，报错通常不会直接告诉你原因。
你看到的是 Pod 处于 Error、CrashLoopBackOff 或构建日志中断，但真正的问题可能出在镜像、网络、依赖仓库、JVM 内存或存储卷上。
这篇文章按排查顺序，把每一步的命令和判断依据写清楚，零基础也能照着做。

先确认 Pod 到底卡在哪一步

不要急着看完整日志，先看 Pod 的状态和重启原因。
执行：

kubectl get pods -n ci -o wide
kubectl describe pod  -n ci

重点看三个位置：

• Status：Error、CrashLoopBackOff、OOMKilled、ImagePullBackOff 分别指向不同方向。
• Events：拉镜像失败、挂载卷失败、调度失败都会在这里出现。
• Last State：如果显示 OOMKilled，说明容器内存超限，不是 Maven 命令本身写错。

如果 Pod 能启动但构建中断，直接看日志：

kubectl logs  -n ci --tail=200

如果 Pod 已经重启过，加 --previous 看上一次日志：

kubectl logs  -n ci --previous --tail=200

依赖拉取失败：先分清是网络还是仓库配置

Maven 构建最常见的报错是 Could not resolve dependencies 或 Connection timed out。
在 K8s 里，这通常不是代码问题，而是容器网络或 settings.xml 配置问题。

先进入容器确认网络是否通：

kubectl exec -it  -n ci -- /bin/sh
curl -I https://repo.maven.apache.org/maven2/

如果 curl 超时，检查集群出口网络和代理。
如果公司内网要求走代理，需要在 settings.xml 里配置：

  
    http-proxy
    true
    http
    proxy.example.internal
    8080
    localhost|127.0.0.1
  

注意 settings.xml 要放在容器内 Maven 实际读取的位置，常见路径是 /root/.m2/settings.xml 或 $MAVEN_CONFIG/settings.xml。
可以用下面命令确认：

kubectl exec -it  -n ci -- mvn help:effective-settings

如果依赖仓库是私服，还要确认 mirror 的 url 在集群内可访问，而不是只在你本地电脑上能打开。

内存和资源限制：Maven 构建容易被 OOMKilled

Maven 构建本身会启动 JVM，如果 Pod 的 resources.limits.memory 设得太小，容器会在编译阶段被系统杀掉。
表现是日志没有任何 Java 异常，直接中断，describe pod 显示 OOMKilled。

先看当前限制：

kubectl get pod  -n ci -o jsonpath='{.spec.containers[*].resources}'

如果限制是 512Mi 或 1Gi，而项目模块多、依赖多，建议先临时调大验证：

resources:
  requests:
    memory: "1Gi"
  limits:
    memory: "2Gi"

同时给 Maven 的 JVM 设置合理堆内存，避免它按容器总内存去申请：

export MAVEN_OPTS="-Xmx1024m -Xms256m"
mvn clean package -DskipTests

如果使用 JDK 10 及以上，JVM 一般能识别容器内存限制，但显式设置 -Xmx 更稳妥。
调整后重新提交任务，观察 kubectl top pod -n ci 的内存曲线。

挂载卷和缓存：依赖下载慢或权限报错

CI 环境常把本地 Maven 仓库挂载到 PVC 或 hostPath，用来缓存依赖。
如果挂载路径不对，Maven 会反复下载，甚至因为权限不足报 Permission denied。

检查挂载点：

kubectl describe pod  -n ci | grep -A5 Mounts

确认容器内 /root/.m2 或自定义的 localRepository 路径确实指向了持久卷。
如果 PVC 是 ReadWriteOnce，多个 Pod 同时写同一个卷也可能冲突。

权限方面，容器内用户和卷的属主不一致时，可以这样验证：

kubectl exec -it  -n ci -- ls -ld /root/.m2
kubectl exec -it  -n ci -- id

如果目录属主是 root，而容器以非 root 用户运行，需要调整 securityContext 或初始化卷权限。

怎么确认问题已经解决

修复后不要只看一次构建成功。
建议按下面顺序复查：

1. kubectl get pods -n ci 确认 Pod 没有反复重启。
2. kubectl logs -n ci --tail=50 看到 BUILD SUCCESS。
3. kubectl describe pod -n ci 的 Last State 不再出现 OOMKilled。
4. 如果依赖来自私服，确认构建日志里没有 Retrying 或 Downloading 反复出现。

如果问题只在高并发构建时出现，优先检查集群节点资源、PVC 读写能力和私服并发限制，而不是继续改 Maven 参数。

几个容易踩的坑

• 只在本地能构建成功：本地有 ~/.m2 缓存和代理配置，容器里没有，先对比两边 settings.xml。
• 把 OOMKilled 当成代码错误：日志没有异常不代表没问题，先看 Pod 的退出原因。
• 忽略集群 DNS：私服地址如果用了内部域名，确认 Pod 的 resolv.conf 和集群 DNS 能解析。
• 直接改生产配置：调整资源限制或挂载前，先在测试命名空间验证，避免影响其他任务。

常见疑问

为什么本地 mvn package 正常，放到 K8s 就失败？

本地和容器的差异主要在三点：网络出口、settings.xml 路径、JVM 内存限制。
先逐项对比，不要直接怀疑代码。

ImagePullBackOff 和 Maven 构建有关系吗？

有关系。
如果构建镜像本身拉不下来，Maven 根本没机会执行。
先解决镜像仓库认证和网络问题，再看构建日志。

要不要在容器里长期保留 .m2 缓存？

看构建频率。
频繁构建建议用 PVC 或镜像层缓存，但要处理好并发写入和权限问题；
低频构建可以每次重新下载，减少卷依赖。

排查 K8s 集群里的 Maven 问题，核心是先分清故障在调度、网络、资源还是配置层。
按上面顺序逐项验证，大部分报错都能定位到具体原因，而不是靠反复重试碰运气。