★ FEATURED ARTICLE 凌晨三点的告警电话我接过太多次了但每一次还是让人瞬间清醒。业务同学在群里说“某某服务超时率飙升赶紧看看”我打开监控面板翻了半天Pod 全是 RunningCPU、内存曲线平得像一条直线连日志都没有报错。可服务就是访问不通。当时的第一反应是检查网络插件、防火墙、安全组折腾了一大圈最后才发现问题出在一个不起眼的地方——Invalid Container Port。这个场景在 Kubernetes 里非常典型资源都正常、Pod 也活着、网络看起来也没问题但流量就是到不了应用。这篇排障手记我就把“端口不通但资源都正常”这一类问题的完整排查思路、根因分析和实操步骤整理出来尤其适合正在做 Kubernetes 运维、DevOps 或者后端开发的朋友遇到同类故障时可以直接照着抄。1. 症状与初始定位明明一切正常为什么就是连不上1.1 这类问题最容易让人误判的三个方向先说说我那次踩坑的经历。业务服务通过 Service 对外暴露监控显示异常之后我先后怀疑过三件事。第一个怀疑的是 CNI 网络插件。因为 Kubernetes 的 Pod 网络是靠 Calico、Flannel、Cilium 这类组件来维护的一旦网络插件出问题最常见的表象就是端口不通。我当时先看了网络插件的 Pod 状态全部正常又看了节点上的网络策略也没有异常。这一轮排查纯属浪费时间。第二个怀疑的是云平台的安全组和防火墙。因为在云环境里安全组规则确实会影响 NodePort 和 LoadBalancer 类型的访问。我把安全组规则翻了又翻发现规则都是对的放行的端口也没问题。后来证明这个方向也是错的。第三个怀疑的是 Service 的 selector 没有匹配上 Pod。这个方向对了一半——问题确实和 Service 有关但我当时只看了一眼 selector发现标签能匹配上 Pod就以为 Service 配置没问题。实际上问题出在更隐蔽的 targetPort 上。现在回头看这类问题之所以容易绕弯路是因为它的外在表现太像“网络不通”但资源指标又太像“一切正常”。Pod 没重启、内存没飙升、CPU 也没打满任何人第一反应都不会是配置问题。但恰恰是这种“看着一切正常”的表象最容易让人忽略最基础的配置检查。1.2 先理清流量路径再动手吃了一次亏之后我养成了一个习惯遇到端口不通先不碰网络插件也不碰防火墙而是先理清楚流量走的哪条路径。Kubernetes 里访问一个应用的路径通常有几种直接访问 Pod IP这个路径最底层绕过了 Service、kube-proxy、DNS 转发直接打到容器网卡。通过 ClusterIP 访问 Service这是最常用的路径流量经过 kube-proxy 转发的 iptables 或 IPVS 规则再到达后端 Pod。通过 NodePort 或 LoadBalancer 访问在 ClusterIP 的基础上多了一层节点端口映射。通过 Ingress 访问多一层七层转发。排查的时候要一步一步收缩范围。我的做法是先用kubectl run临时起一个调试 Pod里面放 curl 或 wget分别测试这几条路径kubectl run debug --imagenicolaka/netshoot --rm -it --restartNever -- /bin/bash进去之后先直连 Pod IPcurl http://Pod-IP:port如果直连 Pod IP 能通说明容器里的进程本身在监听、端口没问题那问题就出在 Service 层。如果直连都不通问题大概率在容器内部比如进程没监听、监听地址绑错了、或者协议不匹配。这个顺序至关重要。先确认底层通不通再往上层查效率至少提高一倍。我见过不少同事一上来就去翻 kube-proxy 日志或 iptables 规则翻了半天才发现容器里监听的端口跟 Service 配的 targetPort 根本不是同一个数。基础层没确认上层查得再深都是白搭。2. Invalid Container Port 到底是谁在“判定无效”2.1 containerPort 只是“说明书”不是“开关”Kubernetes 里有个非常容易被误解的概念Pod 的containerPort字段。很多新手以为写了这个字段Kubernetes 就会帮你在容器里打开某个端口。实际上完全不是这么回事。containerPort不是一个“开关”K8s 不会去监听这个端口也管不了容器进程到底有没有在这个端口上做监听。它只是一份“说明书”把信息写在 Pod 的定义里告诉别人“这个容器预期会使用这样的端口”。真正把端口打开并监听的是容器里的业务进程本身。我习惯用一个生活化的比喻来解释这件事containerPort相当于你家门口贴的门牌号写的是“302室”。Kubernetes 的 Service 就像快递员按照门牌号去送包裹。但如果 302 房间里面根本没有人在听门铃——也就是说容器进程根本没有监听这个端口——快递员按了半天门铃没人开门包裹就只能被退回。此时快递员会报告“这个门铃无效”这就是我们看到的 Invalid Container Port 现象。理解了这一点你就明白为什么“资源都正常”却“端口不通”了容器里的进程确实在跑内存、CPU 都正常但它要么没有监听 Service 指向的那个端口要么监听地址不对要么 Service 引用了一个根本不存在于 Pod 定义里的端口名。Pod 本身活着但流量没人接。2.2 五种常见成因逐个拆解根据我处理过的真实故障Invalid Container Port 这类问题可以归纳成下面五种典型成因。第一种也是最常见的一种targetPort使用了命名端口但在 Pod 里找不到同名的containerPort或者大小写不一致。Kubernetes 的targetPort支持两种写法数字端口和命名端口。当targetPort写的是数字时控制面会直接把流量转发到 Pod IP 的对应数字端口这个场景下即使containerPort没有声明也能通。但当targetPort写成命名端口时控制面就必须去 Pod 的 spec 里找名字完全一致的containerPort。注意名字是完全区分大小写的HTTP和http是两个完全不同的名字。我踩过最经典的一个坑是Service 里写的是targetPort: HTTPPod 里声明的是containerPort: 80, name: http。服务控制面找不到HTTP这个名字于是把 endpoint 置空表现就是端口完全不通但 Pod 一切正常。第二种targetPort配的数字端口跟容器进程实际监听的端口不是同一个。这种情况不需要命名端口匹配endpoints 也是能生成出来的Service 的底层规则也正常但流量到容器门口时容器里没有进程在对应端口监听。比如业务进程监听的是 8080Service 的targetPort写成 80结果就是访问超时或连接拒绝。问题的根源在于K8s 不会因为你说了 80 就去调用进程切换端口它只是原样把流量送过去。第三种多容器场景下端口名定义在了错误的容器上。一个 Pod 里可能跑多个容器比如业务容器加 sidecar 容器。如果targetPort的命名端口匹配到了 sidecar 容器而业务进程实际在另一个容器里监听就会发生“端口声明有但实际没人处理业务流量”的情况。这种问题检查起来特别费劲因为名字对得上、endpoints 也正常就是不通。第四种协议不匹配。Service 定义端口的时候可以指定protocol默认是 TCP。如果容器里业务进程实际监听的是通过 UDP 通信的服务而 Service 定义的protocol: TCP同样会出现端口不通。反过来也是同样的问题。这种问题在日志里最不明显因为 TCP 和 UDP 都是同一个端口号肉眼很难发现。第五种业务进程监听的地址不对。这不是 Kubernetes 的配置问题但很容易被误认为 K8s 问题。比如很多 Node 应用默认只在127.0.0.1上监听这个地址在容器里只有自己能看到外部流量从 eth0 进来自然连不上。查看监听状态时一定要确认监听地址是0.0.0.0或至少是 Pod 的网卡地址。2.3 事件日志里的有效线索遇到这类问题一定要会看事件日志。kubectl describe svc的输出里会直接告诉我们关键线索。kubectl describe svc demo-svc正常情况下输出里会显示Endpoints字段带有实际的 Pod IP如果端口声明有问题Endpoints会显示none。与此同时Service 的TargetPort字段会显示你配置的值比如HTTP/TCP这时候你去对 Pod 里的containerPort一眼就能发现大小写不一致的问题。在比较新的 Kubernetes 版本里EndpointSlice Controller 还会在事件里输出类似 “invalid container port” 的警告信息直接告诉你目标端口在 Pod 里找不到对应项。不同版本的具体文案可能不一样但排查思路完全一致事件里只要提到invalid container port或failed to build model for service十有八九就是targetPort引用出了问题。3. 完整排查流程从 Pod 命令到抓包验证下面这段是我现在遇到“端口不通但资源都正常”类问题时实际执行的标准流程每一步都有对应的命令和判断逻辑你可以直接拿来当模板用。3.1 第一步确认端口是“假活”还是“真活”第一个动作永远不是查网络插件而是进到 Pod 里看进程到底监听了什么。这一步的目的是回答最基础的问题容器里到底有没有进程在监听对应的端口kubectl exec -it pod-name -n namespace -- netstat -tulpn如果 Pod 里有多个容器记得加-c container-name指定容器kubectl exec -it pod-name -n namespace -c container-name -- netstat -tulpn有些基础镜像里没有netstat可以用ss命令kubectl exec -it pod-name -n namespace -- ss -tlnp判断逻辑很简单如果看到目标端口有进程在监听而且监听地址是0.0.0.0或::那容器这一层没问题。如果端口根本没有监听记录说明业务进程没起来或者起来了但监听的不是这个端口。这时候去容器里看进程列表确认进程是否活着。如果监听了但监听地址是127.0.0.1那流量从外部进不来需要改应用的监听配置让它监听0.0.0.0。这个步骤能快速把问题缩小到“应用问题”还是“Kubernetes 配置问题”。我在这一步至少救回过三次误判都是因为先入为主觉得资源正常进程就一定健康结果发现业务进程其实已经悄然退出了容器靠 init 进程活着看着是 Running 但业务早已不服务。3.2 第二步Service 与 Endpoints 的关联排查如果容器里监听正常下一步就看 Service 层。先看 Service 配置kubectl get svc service-name -n namespace -o yaml重点看三个字段selector、ports[].port、ports[].targetPort。然后把 selector 选中的 Pod 标签对比一下确认匹配关系kubectl get pod -n namespace --show-labels再查看 endpoinds。老版本里这个对象叫 Endpoints新版本切到了 EndpointSlice但kubectl get endpoints依然能看到聚合结果排查思路是一样的kubectl get endpoints service-name -n namespace这里会出现三种结果第一Endpoints显示none说明后端的地址列表没有生成。此时有两种可能selector 没匹配到任何 Pod或者targetPort引用的命名端口在 Pod 里找不到。区分方法很简单看kubectl describe svc的输出如果 selector 匹配了 Pod但Endpoints还是空那几乎可以断定是targetPort的问题。第二Endpoints显示了 Pod IP用kubectl get endpoints能看到类似10.244.1.5:8080这样的记录。这说明 Service 层正常endpoint 已经生成。如果这时候再从集群内访问 ClusterIP 不通问题就出在 kube-proxy 转发这一层。第三Endpoints显示 Pod IP 和端口但端口号跟你预期的不一样。这通常也是targetPort的问题——你写成命名端口匹配到了 Pod 里另一个容器的端口。这一步是最关键的一步。一个空 Endpoints 直接说明问题在 Service 引用上不用再去翻网络插件。3.3 第三步kube-proxy 规则层面的验证如果前两步都正常Service 和 endpoints 都有内容但通过 ClusterIP 访问还是不通这时候再来看节点上的转发规则。先确认 kube-proxy 使用的模式。现在大多数集群默认 IPVS 模式有些还是 iptables。可以用下面的命令确认kubectl logs -n kube-system kube-proxy-pod | grep Using如果是 iptables 模式在 Service 对应的节点上查一下 nat 表规则iptables -t nat -S | grep service-name如果是 IPVS 模式ipvsadm -L -n | grep ClusterIP要特别提醒的是这一步不要放在排查的第一步去做。原因很简单iptables 和 IPVS 规则非常多在没确认 endpoints 正常之前去看规则等于大海捞针。而且 kube-proxy 的规则本身就是根据 endpoints 生成的endpoints 是空的规则自然也是空的endpoints 正常规则大多也正常。在这一步你还可以做一个快速的连通性测试。找一个集群节点直接 curl Service 的 ClusterIPcurl http://ClusterIP:port如果这个都不通而直连 Pod IP 又是通的再考虑是不是 kube-proxy 的问题。有一种比较少见但真实存在的情况endpoints 变化后kube-proxy 规则刷新有延迟或者卡住了。这时候解决办法通常是删除并重建一个 Pod强制触发 endpoint 刷新极端情况下重启 kube-proxy 也能解决。3.4 修复操作两种典型场景的改法定位到根因之后修改通常很简单但操作过程中有一些细节需要注意。场景一命名端口大小写不一致。Service 里写的是spec: ports: - port: 8080 targetPort: HTTP而 Pod 里声明的是ports: - containerPort: 80 name: http解决办法是把 Service 的targetPort改成http或者把 Pod 里的端口名改成HTTP。修改 Service 是动态生效的改完之后 endpoint 会立刻重建不用重启任何 Pod。场景二targetPort 写的是数字端口但和容器实际监听端口不一致。Service 里spec: ports: - port: 8080 targetPort: 8080容器实际监听的是 80 端口ports: - containerPort: 80这种情况要改 Service 的targetPort为 80或者改容器监听的端口为 8080取决于业务约定。如果改 Pod 配置记得是修改 Deployment 的模板然后滚动更新而不是直接改运行中的 Pod否则 Pod 重建后配置就没了。我个人的一个建议是能用数字端口就用数字端口简单直接不依赖containerPort的声明如果团队规范要求解耦就必须使用命名端口并且把命名规则写进规范避免“HTTP”和“http”这种低级问题反复出现。4. 常见问题速查表与避坑经验4.1 症状-根因-解法速查表实战里遇到的情况多种多样我整理了一张速查表做二次排障的时候对着看一眼能省不少时间。症状最可能根因快速确认方法解法资源正常SVC访问不通Endpoints为空targetPort是命名端口但Pod里无同名端口或大小写不一致describe svc对比TargetPort与Pod端口名修正端口名或改用数字端口Endpoints有IP但访问不通直连PodIP也不通容器进程没监听对应端口或监听地址为127.0.0.1exec进Pod执行netstat/ss改应用监听0.0.0.0改containerPort声明Endpoints有IP直连PodIP通ClusterIP不通kube-proxy规则刷新异常或延迟节点上curl ClusterIP检查iptables/ipvs删掉重建Pod触发endpoint刷新必要时重启kube-proxy只有NodePort不通ClusterIP正常节点端口被占用或安全组未放行检查nodePort占用检查安全组调整nodePort端口配置安全组放行headless Service访问不通绕过了kube-proxy直接走Pod IPdig解析域名直连解析出的Pod IP按Pod IP不通的方向排查多容器场景下命名端口声明在错误容器targetPort匹配到了sidecar容器端口查看Pod内多个容器端口名将containerPort声明调整到正确的容器Service的protocol和业务实际协议不一致TCP/UDP不匹配确认业务实际使用的协议修改Service的protocol字段4.2 让这类问题少发生的几条工程习惯排查是事了但反复踩同一个坑就是工程管理的问题了。我归纳了几条实际操作中验证过的经验。第一严格约定端口命名规则。如果团队决定使用命名端口就一定要在小写、短横线分隔的规范上达成一致。写 Service 的人、改 Pod 模板的人、负责评审的人都要清楚targetPort是大小写敏感的。这个问题在 CI/CD 流程里很容易被忽视因为 YAML 校验通常只检查语法不检查端口名是否真的存在。第二区分“Pod 状态正常”和“应用可用”是两码事。Kubernetes 里的 Running 只说明容器起来了不代表业务就绪。排查端口不通问题时先看kubectl get pod输出的 READY 列确认前面的数字和容器数一致。如果Running 但 0/1 Ready说明探针没通过endpoint 也不会挂到 Service 上这同样会表现为“资源正常但端口不通”。第三做好端口连通性监控。Kubernetes 平台自己有健康检查还不够最好在集群外部加一层黑盒监控比如定时从测试机去拨测 Service 的端口或者用 Prometheus Blackbox Exporter 做 TCP 探测。只有业务视角的监控才能在你睡觉的时候帮你从“Pod 还活着但服务挂了”的假象里醒过来。第四排障顺序固化下来。我现在遇到端口不通心里默认走的流程是先看 READY 列再 exec 到 Pod 里确认监听再查 Endpoints再查 Service 的 targetPort最后才考虑 kube-proxy 和网络插件。这套顺序能把 90% 的“端口不通但资源正常”问题在十分钟内定位。4.3 一个容易被忽略的“假端口”陷阱最后单独提一个小众但真实发生过的场景有些业务进程监听的端口是 IPv6 地址比如监听在[::]:8080而 Kubernetes 的网络路径走的是 IPv4。从 IPv4 角度看去这个端口是“不存在”的因为 netstat 里可能看到tcp6而不是tcp。某些语言或框架默认绑定到 IPv6 时会同时支持 v4-mapped 地址但并非所有框架都会这样做。真遇到这种情况去容器里执行cat /proc/net/tcp /proc/net/tcp6对比 IPv4 和 IPv6 的监听情况很快能找到答案。解决办法是改应用的监听配置明确绑定到0.0.0.0。我个人在实际操作中的体会是这类“端口不通但资源都正常”的问题最大的困难从来不是技术本身而是心理上的“它看起来没事”带来的迷惑感。资源指标正常、Pod 没崩、日志干净太容易让人把注意力引向网络层。但只要耐住性子按“Pod 内监听 → Endpoints → Service targetPort → kube-proxy 转发”的顺序一步步排除几乎都能在十分钟内把根因揪出来。最后再分享一个小技巧我写 Service 时习惯在targetPort上直接使用命名端口并且把 Pod 的containerPort名字写进注释里。这个习惯看起来不起眼但配合代码评审能从源头拦住一大批大小写不一致、端口名对不上的问题。如果你现在正被端口不通的问题折磨先别急着重启 Pod花两分钟看一眼kubectl get endpoints很多时候答案就摆在那里。
阅读完成 · 觉得有帮助？
