排查 Jenkins 动态 Agent 报错，先别急着改配置。先确认问题发生在构建启动阶段还是 Agent 注册阶段，否则很容易把网络问题当成插件问题，改完一轮配置后报错还在。

先别急着改配置

排查时先判断问题出在 Jenkins 与 Kubernetes 的连通性，还是出在 Agent Pod 启动后的注册环节。可以在 Jenkins 的“系统管理 > 系统日志”中搜索 `KubernetesCloud` 或 `Kubernetes Launcher` 关键字，看有没有 `Connection refused`、`Failed to connect`、`Handshake` 等异常。同时用 `kubectl cluster-info` 确认集群本身正常，再用 `kubectl get endpoints` 检查 Jenkins 在集群内的访问地址是否可达。如果日志中反复出现 401 或 403，优先检查 ServiceAccount 的权限和 token 有效期。

这一步能帮您把问题拆成两类：一类是 Jenkins 到 API Server 的连接、认证出问题；另一类是 Agent Pod 能启动但 JNLP 回连失败。两类问题的排查方向不同，前者侧重 kubeconfig 和 RBAC，后者侧重 Pod 网络、端口和 JNLP 地址配置。

从构建日志和 Pod 事件对照着看

打开 Jenkins 对应构建的“控制台输出”，展开到 Agent 注册阶段，记录当前 Pod 的 IP 和 JNLP 地址，随后在 Kubernetes 集群里用 `kubectl describe pod ` 查看事件。常见情况是 Pod 一直处于 `Pending`，说明资源不足或没有合适的节点；如果停在 `Init:Error`，则要检查 Init Container 的启动命令。手动用 `kubectl run` 启动一个同镜像 Pod 进行联动测试，至少可以确认镜像拉取是否正常，以及 JNLP 服务是否能监听端口。

这里有个容易忽略的动作：先记录控制台输出里的 JNLP 地址，再去 describe Pod。很多人在 Pod 日志里看不到明显错误，其实是因为 JNLP 地址用的域名在集群内解析不了。可以进入一个临时 Pod 用 `nslookup` 确认。另外，describe Pod 的事件如果显示 `FailedScheduling`，说明节点选择器或资源请求超出可用范围；如果是 `FailedMount`，则要查 PVC 和挂载权限。

Pod template 的标签和 YAML 冲突是常见坑

一个典型坑是 Pod template 中的 `labels` 与 Jenkins 全局配置的 `cloud` 不对应，导致动态 Agent 始终不匹配。另一个坑是在 Pod template 的 YAML 里同时写入了 `containers` 和 `volumes`，但 volume 挂载路径与 JNLP Agent 的 workspace 权限冲突，表现为启动后立刻退出或进入 CrashLoopBackOff。排查时先精简 Pod template 到最小的单容器、无持久卷状态，再逐步增加配置，通过二分法定位异常项。

具体操作建议：先保留一个包含 jnlp 容器的最小 template，暂时去掉 `volumes` 和额外 `containers`，确认能跑通后再加第一个 volume。每次加一项，都重新触发一个构建。注意修改 Pod template 后，旧配置可能在插件缓存里停留一段时间，需要等一会儿或重载配置，否则测试结果不代表当前状态。

证书和组件顺序要对上

对于 HTTPS 的 Kubernetes API Server，Jenkins 连接时常常因证书校验失败而报错。优先使用 kubeconfig 文件方式连接，确保 `certificate-authority-data` 和 `client-certificate-data` 对应同一个用户。用 `kubectl config view --raw` 导出内容时，注意粘贴到 Jenkins 中不要带多余换行。可以在 Jenkins 端用 `jq` 校验一下 JSON 格式。如果一直报 `PKIX path building failed`，先确认 Jenkins master 所在机器的时钟是否偏差，再检查 Kubernetes 集群证书是否在有效期。

除了 API Server 的证书，Agent 回连时也要确认 50000 端口和 JNLP 连接方式。如果 Agent 报错显示 `Remote call on X failed`，不要只盯着 Jenkins 插件配置。先检查该节点上的 Java 进程是否正常运行，再抓取线程转储或 GC 日志。如果看板显示 Agent 离线，但 Pod 状态为 `Running`，可以进入容器执行 `ps -ef` 和 `netstat -tlnp`，确认 JNLP agent 的 Java 进程有没有监听在 50000 端口。注意容器内可能没有 netstat，需要提前用 `yum/dpkg` 装工具，或者在 Pod template 中配套一个调试容器。

改完后看这几个信号

改完配置后，不只要看构建是否变绿。先确认三个信号：第一，Jenkins 系统日志里不再出现 `Connection refused` 或 `Handshake` 异常；第二，动态 Agent 的 Pod 在集群里处于 `Running` 状态，并且事件中没有 `FailedMount` 或 `FailedScheduling`；第三，构建控制台输出中能看到 Agent 成功注册的回执，比如 `Agent successfully connected`。

如果这三个信号都通过，再连续跑两次相同的构建，确认动态 Agent 能按预期回收。之后再把之前精简掉的 `volumes`、`containers` 逐项加回去，每次只加一项，直到问题复现。这样既能定位异常，也能保留一个可回滚的基线配置。