K8S dashboard 无法访问这个标题我太熟了。几乎每次有同事把集群搭好问我环境怎么连最后一句都会落到这上面浏览器一开要么转圈转半天要么直接 ERR_CONNECTION_REFUSED要么登录页出来了但手里的 Token 死活登不进去。这个问题的诡异之处在于它不是某一种原因而是从 Pod 到 Service 再到浏览器中间随便哪一环断了都会表现成“无法访问”。这篇文章不绕弯直接从我实际排查过的几个案例里把最常见的断点、排查命令和容易忽略的坑整理出来遇到类似情况可以照着走一遍。1. 先别急着动 YAML给“无法访问”分个类很多人一听说 dashboard 访问不了第一反应就是看 Service 的 YAML 是不是写错了或者重新装一遍。其实 90% 的问题不用重装先根据现象把故障类别定出来效率会高很多。我把“K8S dashboard 无法访问”分成三类常见现场现象大概率方向第一件事干什么页面完全打不开超时或拒绝连接网络链路没通Pod/Service/防火墙看 Pod 是否 RunningService 有没有 Endpoints登录页能打开但 Token 登不上Token 过期、ServiceAccount 权限不对、时钟偏差重新生成 Token检查 RBAC登录成功但页面一直加载出错浏览器到 Dashboard 之间协议不通、Metrics 没接、Ingress 路径没处理好看浏览器控制台的错误码用端口转发做对照测试这个分类不是随便写的。Dashboard 的架构是“浏览器 - 某种接入方式 - Service - Pod”每一层暴露的问题完全不同。如果一上来就乱翻 YAML反而会因为看到的都是正常配置而浪费时间。先问自己三个问题页面是压根没响应还是响应了但认证过不去还是认证过了但数据拿不到把问题归类再选一套对应的排查路径通常十分钟内能锁定根因。我自己的习惯是任何“访问不了”先不 SSH 到节点上乱敲命令而是找一个能稳定复现的最小场景。比如在同一台能访问集群的机器上执行kubectl proxy然后访问本地代理地址如果本地代理能打开那问题基本出在 Service 暴露方式或者外部网络上如果本地也打不开那就集中排查 Pod 和 Service 这一层。这个方法可以把“外部网络”和“集群内部服务”两个变量强行切开非常有效。2. 顺着网络链路一层层查Pod、Endpoints、Service、kube-proxy2.1 先确认 Deployment 和 Pod 是否真的 Ready网络链路排查要从最里面的 Pod 开始而不是从浏览器往下反查。先执行这几条命令kubectl get deployment -n kubernetes-dashboard kubectl get pods -n kubernetes-dashboard -o wide kubectl logs -n kubernetes-dashboard deployment/kubernetes-dashboard --tail50如果 Deployment 显示可用数为 0或者 Pod 状态是 CrashLoopBackOff、Pending、ImagePullBackOff那后面查多少层都没用。这时候kubectl describe pod pod-name -n kubernetes-dashboard的输出里会直接写清楚失败原因。我看过一个最典型的例子Pod 一直 Pending原因是节点资源不足而 dashboard 的 Deployment 没有设置tolerations集群里只有一个带污点的控制平面节点调度器自然无法把 Pod 放上去。先把kubectl describe node看一遍污点和可用资源比反复改 Service 有效率得多。Pod 正常之后还要顺手看一眼日志里有没有明显的http: TLS handshake error、权限拒绝之类的关键字。Dashboard 的日志通常不多但一旦有forbidden或者unauthorized基本可以跳到后面 RBAC 的部分去查不用在网络上继续浪费时间。2.2 Service 的 Endpoints 是否为空Pod 是 Running 不代表 Service 能转发。最常见的情况是 Deployment 的selector和 Service 的selector对不上或者 Pod 里根本没有声明对应的标签。这时候执行kubectl get svc -n kubernetes-dashboard kubectl get endpoints -n kubernetes-dashboard如果 Endpoints 列是空说明 Service 后面没有匹配到任何 Pod。去kubectl get pods -n kubernetes-dashboard --show-labels看一遍 Pod 标签再对照kubectl get svc kubernetes-dashboard -n kubernetes-dashboard -o yaml里的spec.selector。Dashboard 官方 YAML 里的标签是k8s-app: kubernetes-dashboard如果你手工改过 Deployment 名字或者加过其他标签标签一旦不一致Service 就找不到后端。Endpoints 有地址之后说明 Service 这一层没问题。接着确认端口Dashboard 默认服务是 443 到容器的 8443Service 的targetPort写成 8443 才是对的。如果targetPort写成了 80而容器实际监听 8443那浏览器就算能连到 Service后端也会立刻断开连接。2.3 在集群内部验证 Service 是否真的通到了这一步应该做一次“集群内部视角”的验证。最简单的方式是在能访问 API Server 的机器上临时开一个端口转发kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard 8443:443然后本机访问https://localhost:8443。注意这里访问的是svc而不是pod转发的是 Service 的 443 到本地 8443。如果这个地址能出登录页说明 Pod、Service、kube-proxy 这条链路完全正常问题几乎可以确定在外部访问方式如果这个地址也不通再去查 kube-proxy。kube-proxy 的问题不容易一眼看出来。可以先看kubectl get pods -n kube-system | grep kube-proxy确认所有节点的 kube-proxy 都在 Running。部分场景下kube-proxy 还在跑但iptables规则被其他网络组件覆盖这时候可以参考 Service 对应的iptables-save输出不过那已经是比较深的调试点。对绝大多数人来说先确认kubectl get svc -A能看到 Service再用端口转发验证后端已经能覆盖 80% 的情况。3. 不同访问方式对应不同的排查姿势“无法访问”这四个字在不同访问方式下的含义完全不同。我见过有人明明是用 NodePort 方式访问却拿localhost去连那当然打不开也有人是用 Ingress 方式但根本没配置 TLS 后端协议导致反复 502。所以要先说清楚自己用的是哪种访问方式再对号入座。3.1 kubectl proxy 方式URL 拼错是重灾区开发环境里我最常用的是kubectl proxy因为它不暴露任何节点端口也不用处理证书直接用本机代理访问。命令很简单kubectl proxy --port8001然后打开http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/这里有两个容易踩的细节。第一个是https:部分如果 Dashboard 的 Service name 是kubernetes-dashboardSVC 协议是 HTTPS那 URL 中间必须是https:kubernetes-dashboard:/proxy/注意端口是空的冒号后面直接跟 Slash。第二个是很多教程贴的是旧版本路径.../api/v1/namespaces/kube-system/services/kubernetes-dashboard/...namespace 写错就会出现 404。用kubectl -n kubernetes-dashboard get svc先确认准确的 service 名称和 namespace再拼 URL。如果访问这个代理地址还是 404把 API 路径里的namespaces换成实际的 namespace 再试。有时候 Dashboard 安装在自定义 namespace那路径里的kubernetes-dashboard也要跟着改。这个方式也能顺便验证“浏览器到集群 API”这一段是否通因为kubectl proxy走的是 kubeconfig 里的 API Server 地址如果这里都不通说明本机到集群的网络根本没有建立。3.2 port-forward 方式最直接的连通性对照kubectl proxy适合日常调试但它会经过一层 API 代理和直接访问 Service 的行为略有差异。想完全模拟真实访问用端口转发可以少绕一层kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard 8443:443然后浏览器打开https://localhost:8443。注意端口转发命令占着当前终端窗口一关就断。遇到页面打不开先看终端的输出常见的报错有Unable to listen on port 8443本机 8443 已经被占用换个本地端口。error: error upgrading connection通常是 kubelet 无法连接 Pod和集群节点网络有关。浏览器提示证书无效这是正常的Dashboard 默认用自签名证书点“继续前往”就行。这个方法我经常当作“判断问题属于外部网络还是集群内部”的标尺。如果端口转发能打开但 NodePort 不能打开那直接去检查节点安全组和宿主机防火墙如果端口转发也打不开那就回头继续查集群内部。3.3 NodePort 方式暴露端口时要同时看节点和防火墙NodePort 是把 Dashboard 的 Service 改成type: NodePort然后在宿主机上分配一个 30000-32767 之间的端口。改法很简单kubectl -n kubernetes-dashboard get svc kubectl -n kubernetes-dashboard edit svc kubernetes-dashboard把type: ClusterIP改成type: NodePort保存后执行kubectl get svc就能看到一个PORT(S)形如443:30443/TCP。然后在浏览器访问https://任意节点IP:30443。这个方式常见的“无法访问”原因有三个。第一你在浏览器访问的是localhost但localhost是当前电脑自己并不是集群节点第二宿主机防火墙或云安全组没有放行 30443 端口第三浏览器访问的是 443 而不是映射出来的 30443因为习惯性地只输入了节点 IP 没加端口。排除这三件事后NodePort 方式基本不会再出问题。要注意的是 NodePort 端口范围如果不在 30000-32767 内kube-apiserver 会直接拒绝 Service 创建这是另一个常见的“Service 一直没变”的坑。3.4 Ingress 方式证书和后端协议要一起处理生产环境更常用 Ingress。但 Dashboard 本身启用的是 HTTPS 端口 8443如果 Ingress 控制器默认以 HTTP 方式去连后端就会一直报 502 或者 504。这个问题的解决办法是在 Ingress 上声明后端协议为HTTPS。不同 Ingress 控制器的写法不一样但核心思路是告诉 Ingress 控制器“后端是一个 HTTPS 服务”而不是让它自动用 HTTP。此外Ingress 如果用域名暴露最好把证书忘掉浏览器会因为证书不匹配而直接拦死表现同样是“无法访问”。另外提醒一句如果使用常见的 Ingress 控制器做路径转发Dashboard 内部有很多回调地址是基于根路径/的。如果 Ingress 里配置的 path 是/dashboard/没有做 rewrite登录成功之后页面可能一直跳回根路径导致白屏。我的建议是生产上直接用独立域名指向 dashboard路径用/后端协议写成 HTTPS这样可以少踩一大堆重定向的坑。4. 登录问题先别赖前端Token 来源和 RBAC 才是主因如果页面能打开但登录时一直提示“Unauthorized”或者“token 无效”问题大概率不在浏览器而在 Token 本身。Dashboard 的登录方式有两种一是用 kubeconfig二是用 Token。大多数“无法访问”场景里用户都是拿 Token 登录的而 Token 无效通常可以拆成三种情况。4.1 Token 来自哪里决定了你能不能登录Dashboard 默认会创建一个名为kubernetes-dashboard的 ServiceAccount但那个账号权限非常有限。用它生成的 Token 登录后Dashboard 能显示页面却会在打开某个 namespace 时报权限错误。所以很多人“K8S dashboard 无法访问”其实不是访问不上而是点了半天之后发现什么都干不了。如果只是测试环境想快速拿到一个有完整权限的 Token可以按这个思路操作kubectl -n kubernetes-dashboard create serviceaccount admin-user kubectl -n kubernetes-dashboard create clusterrolebinding admin-user \ --clusterrolecluster-admin \ --serviceaccountkubernetes-dashboard:admin-user kubectl -n kubernetes-dashboard create token admin-user --duration24h这里需要说明两点。第一cluster-admin是集群最高权限生产环境不要这样配这只是定位问题时最快拿到可用 Token 的办法第二kubectl create token是较新版本 Kubernetes 的用法旧版本如果报“unknown command”需要改成从 Secret 里读取kubectl -n kubernetes-dashboard get secret $(kubectl -n kubernetes-dashboard get sa admin-user -o jsonpath{.secrets[0].name}) -o jsonpath{.data.token} | base64 -d这个命令在不同的 Kubernetes 版本里略有差异但逻辑是一样的找到该 ServiceAccount 绑定的 Secret解码里面的 token 字段。4.2 报“unauthorized”和“token expired”时的排查顺序拿到新 Token 后如果还是登不上先检查本机时间和集群节点时间是不是差太多。Token 的签发和校验依赖时间偏差超过几分钟就会出现验证失败表现就是登录页一直报错。这个坑我遇到过两次都是集群节点时钟漂移花在 RBAC 上的时间全白费。其次是 Token 本身是否已过期。kubectl create token默认生成的 Token 有效期比较短如果不带--duration参数有些环境可能几分钟后就失效。所以排查时先用一个新的、显式指定时长的 Token 再试一次把“过期”这个变量排除掉。kubectl config view也值得看一眼。如果你本机 kubeconfig 里配的集群地址和证书已经过期或对不上就算端口转发连上了API 请求也会被拒绝。用kubectl cluster-info确认当前 API Server 地址正常再检查kubectl config current-context指向的环境是不是你想连的那套集群。多集群环境下最容易犯的错误就是 context 切错了页面自然一直访问不到。4.3 权限不足时页面表现不只是“访问不了”还有一类情况登录成功了页面也能打开但左侧列表始终加载不出来或者每个 namespace 打开都是红色报错。这种“半无法访问”状态往往不是网络问题而是 RBAC 里没有授权。我的习惯是登录前先确认这个 ServiceAccount 到底有哪些权限。用命令对着看kubectl auth can-i get pods --assystem:serviceaccount:kubernetes-dashboard:admin-user -A kubectl auth can-i list deployments --assystem:serviceaccount:kubernetes-dashboard:admin-user -A如果结果全是 no那就不怪 Dashboard先回去把 ClusterRoleBinding 建好。创建工作本身只是一个 yaml但重点在于“绑定对象”要准确ClusterRoleBinding 的subjects里 namespace 要和 ServiceAccount 所在 namespace 一致否则绑定不会生效。我见过很多次明明建了绑定但因为 namespace 写错结果绑定到了另一个环境页面还是一堆 Forbidden。5. 和“无法访问”容易混淆的隐藏坑镜像、调度、证书有时候网络链路全通Service 也正常但页面还是有问题这时候要往那几个容易被当成“外部问题”的角落看。5.1 镜像拉不下来导致 Pod 永远 PendingDashboard 的 Pod 状态如果长时间ImagePullBackOff网页当然访问不了。多数情况下这是因为所在机器无法访问镜像仓库或者网络策略限制了拉取。用kubectl describe pod看一下 Events里面会直接写“Failed to pull image”和具体错误。如果确认是网络问题先把镜像推到内网仓库再把 Deployment 里的 image 地址改成内网地址。这个改完后通常是RollingUpdate等 Pod 变成 Running 再测页面。还有一个细节是 CPU 架构。老的 Dashboard 镜像在某些平台上是单架构的在 ARM 节点上会出现exec format error表现也是 CrashLoopBackOff但日志里根本不是网络问题。遇到这种换一个支持当前架构的镜像 tag 就行别在 YAML 上反复折腾。5.2 控制节点有污点Dashboard 没调度上去单机测试环境或小集群经常只有控制平面节点而控制节点默认带污点。Dashboard 的 Deployment 如果没有加容忍度调度器会把 Pod 一直放在 Pending 状态。这种情况和“镜像拉不下来”的修复方法完全不一样前者要改镜像地址后者要改调度配置。判断依据还是kubectl describe pod里面会写0/1 nodes are available然后列出被污点拒绝的原因。想快速确认是不是这个原因可以用一条命令看当前节点污点kubectl get nodes -o jsonpath{range .items[*]}{.metadata.name}{ }{.spec.taints}{\n}{end}如果不需要保留污点隔离给 Deployment 加上对应的容忍度再重新部署Pod 起来后访问就正常了。这个问题很容易被当成“Service 配置错误”处理但只要养成看kubectl describe pod的习惯其实一眼就能定位。5.3 浏览器证书拦截看起来像“无法访问”但不是Dashboard 使用自签名证书浏览器第一次访问时会拦一个大红页很多不熟悉的人看到ERR_CERT_INVALID或者您的连接不是私密连接就以为是服务挂了。其实绕过这个警告就能看到登录页。用端口转发方式访问时由于域名是localhost只要手动点“高级 - 继续前往”就行。如果是在 Ingress 后面访问建议把证书换成一个匹配域名的可信证书这样既能避免浏览器拦截也能避免后面 Cookie 因为域名不匹配而出现各种奇怪跳转。证书问题虽然简单但经常和 Token 问题混在一起导致两人一起排查半天最后发现只是浏览器页面没点“继续访问”。5.4 登录后一直跳转回登录页还有一类状况账号能验证但是提交 Token 后页面刷新一下又回到登录框。这个多半是 Cookie 和重定向配置的问题。Dashboard 默认会写入一个会话 Cookie如果访问地址的域名在每次请求中不一致比如第一次用 IP 打开刷新后变成了另一个域名或者 Ingress 把/重写到了/dashboard/Cookie 就会失效表现就是“看起来永远登录不进去”。最简单的对照方法还是用kubectl port-forward直接访问如果端口转发方式登录正常而 Ingress 方式不正常问题基本出在 Ingress 的路径重写和证书配置上。6. 一条更省事的排查路径把变量一步步拆开写到这里我想分享一个被我自己验证过很多次的排查顺序。以后遇到 K8S dashboard 无法访问不用先复制一堆 YAML按这个顺序走就行先确认 Pod 状态是 Running。不是的话看kubectl describe pod解决镜像、资源、污点这三类问题。再确认 Service 的 Endpoints 非空。空的话查 selector 和 service targetPort。用kubectl port-forward在本地做连通性测试。能开说明集群内部没问题不能开说明问题还在集群底层。判断当前访问方式是 NodePort 还是 Ingress。NodePort 查端口占用、宿主机防火墙和浏览器输入的地址Ingress 查后端协议和证书。登录失败时先生成一个新的、有效期明确的 Token再看 RBAC 权限最后检查时间同步。都不行就换个访问方式做个对照实验通常能立刻缩小范围。这套流程看起来朴素但能在最折腾的时候把人拉回来。尤其是“端口转发能开NodePort 不能开”这个对照结果几乎可以一刀切开“集群内部网络”和“外部防火墙”两个方向省掉很多无效操作。最后补一个建议访问 Dashboard 时尽量别把期望压在某个不变的 NodePort 或临时kubectl proxy上。临时环境里无所谓但长期使用时给 Dashboard 准备一个干净的域名前面挂好证书和认证后面做好 RBAC 权限收敛才是从根上避开“无法访问、登录不了、权限不够”这一连串问题的办法。上面这些命令够你在大多数场景下定位干净了如果真遇到某个组件版本太老导致的怪异报错记得把kubectl describe和日志里最上面那几行错误原样带到社区里问比笼统说“dashboard 无法访问”要快得多。
