企业官网建设流程全解析

1. kubectl top 报错 metrics not available 到底卡在哪一层

kubectl top nodes敲下去，终端回你一句error: Metrics API not available，或者error: metrics not available for pod xxx，这个场景我猜你正在经历。Metrics Server 是 Kubernetes 里给kubectl top、HPA（Horizontal Pod Autoscaler）、kubectl autoscale提供 CPU/内存实时数据的组件，它本身不存历史数据，只做「从每个节点的 Kubelet 拉一次、聚合、通过聚合层 API 暴露出去」这件事。适合谁？任何想让kubectl top出数、想让 HPA 按 CPU 自动扩缩容、想在 Dashboard 里看到资源曲线的集群管理员和运维开发。

问题在于，Metrics Server 不是装完就完事。它要经过一条完整的链路：Metrics Server Pod 启动 → 向 Kubelet 的 10250 端口发起请求 → Kubelet 返回 cAdvisor 指标 → Metrics Server 聚合 → 注册 APIServicev1beta1.metrics.k8s.io→ kube-apiserver 的聚合层把请求转发给 Metrics Server。这条链上任何一环断了，kubectl top都会报metrics not available，但报错信息几乎一样，所以排查起来容易抓瞎。

我实测下来，最常见的断点有三个：一是 APIService 注册了但后端 Service 没有可用 Endpoint，导致聚合层转发失败；二是 Kubelet 证书不被 Metrics Server 信任，请求被拒；三是国内网络拉不到registry.k8s.io的镜像，Pod 一直ImagePullBackOff，自然没有后端。这三个原因对应的报错细节不同，但表面症状都是metrics not available。

这篇会按「先定位断点、再给可复制 YAML、最后验证」的顺序走一遍，同时把集群里 AI 工具（比如跑在 Pod 里的 coding agent、内部 LLM 网关）的调用凭据统一到 TaoToken 的 Key/API 通道，避免每个工具各配一套 Key、配额散落各处。Metrics Server 解决的是「集群资源可观测」，TaoToken 解决的是「AI 调用凭据可管理」，两件事在同一个运维视角下其实是一类问题：把分散的、难排查的东西收敛到一个统一入口。

先明确一个判断：kubectl top报错不等于 Metrics Server 没装。你要先分清是「Pod 没起来」还是「Pod 起来了但聚合层不通」。这两类的排查路径完全不同，下面第二节先讲前置检查，把断点缩小到具体一层。

2. 装 Metrics Server 前的前置检查与 TaoToken Key 准备

在动手 apply YAML 之前，先把集群侧的前置条件过一遍，能省掉后面一半的排查时间。Metrics Server 对集群有几个硬性要求：Kubernetes 版本 1.8 以上（现在基本都满足）；API 聚合层必须启用，也就是 kube-apiserver 启动参数里要有--enable-aggregator-routing或者至少聚合层相关配置正常；Kubelet 要启用 Webhook 认证和授权；Kubelet 的证书要么由集群 CA 签名，要么你就得用--kubelet-insecure-tls跳过校验；容器运行时得实现容器指标 RPC 或支持 cAdvisor。

先确认聚合层是否正常。执行：

kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

如果返回NotFound，说明 Metrics Server 还没注册 APIService，属于「没装或没装成功」；如果返回了对象但status.conditions里有False，那就是「装了但后端不通」。这一步能把问题一刀切成两半。

再看节点和 Kubelet 端口是否可达。Metrics Server 默认走 Kubelet 的 10250 端口：

kubectl get nodes -o wide kubectl describe node <节点名> | grep -A3 "Addresses"

确认节点 InternalIP 正常，且安全组/防火墙没有拦 10250。很多自建集群（kubeadm 之外的方式）会在这里翻车。

然后是镜像问题。官方 YAML 用的是registry.k8s.io/metrics-server/metrics-server:v0.7.2，国内环境经常拉不动。你可以提前在节点上试拉：

crictl pull registry.k8s.io/metrics-server/metrics-server:v0.7.2

拉不动就换成可用的镜像地址，比如华为云 SWR 的镜像仓库地址，后面 YAML 里我会标出来替换位置。

接着说 TaoToken 这部分。为什么装 Metrics Server 要提 TaoToken？因为很多集群里跑着 AI 相关的工具——比如内部的代码助手、跑在 Pod 里的 agent、CI 里调模型的脚本。这些工具各自持有不同的 API Key，散落在各个 Secret 和配置文件里，配额和凭据管理很乱。TaoToken 提供统一的 Key/API 通道，把这些调用收敛到一个入口，集中管理凭据和配额。

你需要先去 TaoToken 控制台拿一个 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制保存。这个 Key 后面会用在集群内的 Secret 里。TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，是纯 API 端点。

如果你还没注册，可以先从官网入口进：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。注册后在控制台能看到 Key 管理、配额查看、模型列表这些页面。

把 Key 存成集群 Secret，这样 Pod 里引用时不用明文写：

kubectl create secret generic taotoken-credentials \ --from-literal=TAOTOKEN_API_KEY='sk-你的Key' \ -n default

注意 Secret 的 namespace 要和用它的 Pod 一致，跨 namespace 引用要单独创建。这一步做完，集群侧的凭据入口就统一了，后面 AI 工具只需要读这个 Secret，不用各自维护 Key。

前置检查清单过完，确认聚合层、Kubelet 端口、镜像、Key 都就绪，再进第三节的 YAML 配置。

3. 可复制的 Metrics Server YAML 与 TaoToken 配置片段

这一节给两份可直接用的配置：一份是 Metrics Server 的部署 YAML（含国内镜像替换和关键参数），一份是集群内 AI 工具接入 TaoToken 的配置片段。

先看 Metrics Server。下面这份是单副本精简版，去掉了高可用里的一些冗余，适合先跑通再考虑扩容。关键参数我加了注释：

apiVersion: v1 kind: ServiceAccount metadata: labels: k8s-app: metrics-server name: metrics-server namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: k8s-app: metrics-server rbac.authorization.k8s.io/aggregate-to-admin: "true" rbac.authorization.k8s.io/aggregate-to-edit: "true" rbac.authorization.k8s.io/aggregate-to-view: "true" name: system:aggregated-metrics-reader rules: - apiGroups: - metrics.k8s.io resources: - pods - nodes verbs: - get - list - watch --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: labels: k8s-app: metrics-server name: system:metrics-server rules: - apiGroups: - "" resources: - nodes/metrics verbs: - get - apiGroups: - "" resources: - pods - nodes verbs: - get - list - watch --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: labels: k8s-app: metrics-server name: metrics-server-auth-reader namespace: kube-system roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: extension-apiserver-authentication-reader subjects: - kind: ServiceAccount name: metrics-server namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: labels: k8s-app: metrics-server name: metrics-server:system:auth-delegator roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: system:auth-delegator subjects: - kind: ServiceAccount name: metrics-server namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: labels: k8s-app: metrics-server name: system:metrics-server roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: system:metrics-server subjects: - kind: ServiceAccount name: metrics-server namespace: kube-system --- apiVersion: v1 kind: Service metadata: labels: k8s-app: metrics-server name: metrics-server namespace: kube-system spec: ports: - name: https port: 443 protocol: TCP targetPort: https selector: k8s-app: metrics-server --- apiVersion: apps/v1 kind: Deployment metadata: labels: k8s-app: metrics-server name: metrics-server namespace: kube-system spec: selector: matchLabels: k8s-app: metrics-server strategy: rollingUpdate: maxUnavailable: 1 template: metadata: labels: k8s-app: metrics-server spec: containers: - args: - --kubelet-insecure-tls - --cert-dir=/tmp - --secure-port=10250 - --kubelet-preferred-address-types=InternalIP,Hostname,InternalDNS,ExternalDNS,ExternalIP - --kubelet-use-node-status-port - --metric-resolution=15s image: registry.k8s.io/metrics-server/metrics-server:v0.7.2 imagePullPolicy: IfNotPresent livenessProbe: failureThreshold: 3 httpGet: path: /livez port: https scheme: HTTPS periodSeconds: 10 name: metrics-server ports: - containerPort: 10250 name: https protocol: TCP readinessProbe: failureThreshold: 3 httpGet: path: /readyz port: https scheme: HTTPS initialDelaySeconds: 20 periodSeconds: 10 resources: requests: cpu: 100m memory: 200Mi securityContext: allowPrivilegeEscalation: false capabilities: drop: - ALL readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 1000 seccompProfile: type: RuntimeDefault volumeMounts: - mountPath: /tmp name: tmp-dir nodeSelector: kubernetes.io/os: linux priorityClassName: system-cluster-critical serviceAccountName: metrics-server volumes: - emptyDir: {} name: tmp-dir --- apiVersion: apiregistration.k8s.io/v1 kind: APIService metadata: labels: k8s-app: metrics-server name: v1beta1.metrics.k8s.io spec: group: metrics.k8s.io groupPriorityMinimum: 100 insecureSkipTLSVerify: true service: name: metrics-server namespace: kube-system version: v1beta1 versionPriority: 100

几个必须注意的点。第一，--kubelet-insecure-tls是跳过 Kubelet 证书校验的开关，自建集群 Kubelet 证书没被集群 CA 签名时必加，否则 Metrics Server 连不上 Kubelet，日志里会刷x509: certificate signed by unknown authority。生产环境如果 Kubelet 证书规范，可以去掉这个参数更安全。第二，--kubelet-preferred-address-types指定了连接 Kubelet 时的地址优先级，InternalIP放最前，避免 DNS 解析问题。第三，镜像地址registry.k8s.io/metrics-server/metrics-server:v0.7.2国内拉不动的话，替换成swr.cn-north-4.myhuaweicloud.com/ddn-k8s/registry.k8s.io/metrics-server/metrics-server:v0.7.2这类可用地址。

APIService 里的insecureSkipTLSVerify: true配合--kubelet-insecure-tls使用，让聚合层转发时不校验后端证书。如果你的集群证书体系完整，这两个都可以收紧。

apply 之前先 dry-run 看一眼：

kubectl apply -f metrics-server.yaml --dry-run=server

没问题再正式 apply：

kubectl apply -f metrics-server.yaml

接着是 TaoToken 的配置片段。集群内 AI 工具接入时，推荐用环境变量从 Secret 注入，而不是把 Key 写死在镜像或 ConfigMap 里。下面是一个 Deployment 的片段，展示怎么把前面创建的 Secret 挂进去：

apiVersion: apps/v1 kind: Deployment metadata: name: ai-agent-demo namespace: default spec: replicas: 1 selector: matchLabels: app: ai-agent-demo template: metadata: labels: app: ai-agent-demo spec: containers: - name: agent image: your-agent-image:latest env: - name: TAOTOKEN_API_KEY valueFrom: secretKeyRef: name: taotoken-credentials key: TAOTOKEN_API_KEY - name: TAOTOKEN_BASE_URL value: "https://taotoken.net/api" - name: TAOTOKEN_MODEL value: "claude-sonnet-4-5"

这里三件套齐了：Base URL 是https://taotoken.net/api，Key 从 Secret 注入，Model ID 用环境变量指定。工具代码里读这三个变量就能发起调用，不用在代码里硬编码。Model ID 具体填什么，去 TaoToken 的模型列表页看当前可用的模型名，控制台里有。

如果你用的是 Claude Code 这类工具，它的配置方式不太一样，需要单独设置。Claude Code 的接入文档在 https://taotoken.net/doc ，里面有针对不同工具的配置说明。Cline、Codex 这类工具的auth.json或 MCP 配置，也是同样的三件套逻辑：Base URL 指向 TaoToken 的 API 地址，Key 用你的 Key，Model ID 填对应模型。

配置片段给完，下一节验证请求是否真的通了。

4. 验证 kubectl top 与 TaoToken 调用是否成功

配置 apply 完，先别急着敲kubectl top，按顺序验证，能快速定位是哪一层的问题。

第一步，看 Metrics Server Pod 状态：

kubectl get pods -n kube-system | grep metrics-server

期望是Running且READY 1/1。如果是ImagePullBackOff，回去换镜像地址；如果是CrashLoopBackOff，看日志：

kubectl logs -n kube-system deploy/metrics-server --tail=50

日志里如果出现unable to fully scrape metrics或x509相关，就是 Kubelet 证书问题，确认--kubelet-insecure-tls加了没。

第二步，看 APIService 状态：

kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

重点看status.conditions，期望是：

conditions: - lastTransitionTime: "..." message: "all checks passed" reason: "Passed" status: "True" type: "Available"

如果status是False，message会告诉你原因，常见的是failing or missing response from ...或no endpoints available。no endpoints available说明 Service 没有匹配到 Pod，检查 Deployment 的 label 和 Service 的 selector 是否一致。

第三步，直接查聚合 API：

kubectl get --raw "/apis/metrics.k8s.io/v1beta1/nodes" | head -c 500

这条命令绕过kubectl top，直接打聚合层。如果返回 JSON 数据，说明链路通了；如果返回Error from server (ServiceUnavailable)，说明聚合层转发失败，回到第二步看 APIService。

第四步，才是kubectl top：

kubectl top nodes kubectl top pods -A

期望输出类似：

NAME CPU(cores) CPU% MEMORY(bytes) MEMORY% master-1 250m 12% 1800Mi 45% node-1 180m 9% 1200Mi 30%

注意 Metrics Server 默认--metric-resolution=15s，刚启动时数据可能还没聚合完，等 30 秒再敲。如果kubectl top nodes报error: Metrics API not available，但第三步的 raw 请求能返回数据，那多半是 kubectl 客户端版本和 API 版本不匹配，检查 kubectl 版本。

TaoToken 侧的验证，在集群里起一个临时 Pod 测一下：

kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- \ sh -c 'curl -s -X POST https://taotoken.net/api/v1/messages \ -H "x-api-key: $TAOTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":50,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"'

注意这个临时 Pod 没有挂 Secret，$TAOTOKEN_API_KEY是空的，实际测试时要么把 Key 直接写进去（仅测试用），要么用挂了 Secret 的 Pod 来测。返回里如果有content字段和文本，说明 Key 和通道都正常。如果返回 401，检查 Key 是否正确、有没有多余空格；如果返回 404，检查 Base URL 路径。

验证通过后，kubectl top能出数、AI 工具能调通，两件事都落地了。下一节把常见的报错对照着排一遍。

5. 常见报错对照排查：401、local proxy failed、reading choices、OAuth

这一节把实际会撞到的报错按「报错原文 → 原因 → 处理」列出来，方便你直接对号入座。

报错一：error: Metrics API not available

这是最笼统的报错，可能对应三种情况。先跑kubectl get apiservice v1beta1.metrics.k8s.io，如果 NotFound，说明 APIService 没注册，YAML 里的 APIService 段没 apply 成功；如果 Available 是 False，看 message；如果 Available 是 True 但kubectl top还报错，检查 kubectl 版本和 kubeconfig 指向的集群对不对。

报错二：failing or missing response from https://10.x.x.x:10250

Metrics Server 连不上 Kubelet。原因通常是 Kubelet 证书不被信任，或者 10250 端口不通。处理：确认--kubelet-insecure-tls已加；在 Metrics Server Pod 里curl -k https://<节点IP>:10250/metrics测连通性；检查节点防火墙。

报错三：no endpoints available for service "metrics-server"

Service 没有后端。检查 Deployment 的 Pod 是否 Running，label 是否和 Service selector 匹配：

kubectl get endpoints -n kube-system metrics-server

如果 ENDPOINTS 是<none>，就是 selector 不匹配或 Pod 没起来。

报错四：TaoToken 调用返回401 Unauthorized

Key 不对。检查 Secret 里的 Key 有没有多余空格、换行；确认请求头字段名正确（Anthropic 风格是x-api-key，OpenAI 风格是Authorization: Bearer）；确认 Key 没有过期或被禁用。去 https://taotoken.net/api-keys 重新核对。

报错五：local proxy failed或连接超时

集群内 Pod 访问外部 API 时的网络问题。检查 Pod 所在节点的出网策略、NetworkPolicy 是否拦了出站流量；确认 DNS 能解析taotoken.net：

kubectl run dns-test --rm -it --image=busybox --restart=Never -- nslookup taotoken.net

如果 DNS 解析失败，检查 CoreDNS 配置；如果解析成功但连不上，检查节点出网和 NetworkPolicy。

报错六：reading choices或响应解析失败

这类报错通常出现在客户端 SDK 解析响应时，说明返回的 JSON 结构不符合预期。常见原因是 Base URL 配错了，比如把https://taotoken.net/api写成了https://taotoken.net（少了/api），或者用了 OpenAI 兼容格式去调 Anthropic 格式的端点。确认 Base URL 和请求格式匹配，Anthropic 格式走/v1/messages，OpenAI 格式走/v1/chat/completions。

报错七：OAuth 相关报错

如果你用的是 Claude Code 这类带 OAuth 流程的工具，报 OAuth 错误通常是认证方式没切对。Claude Code 接入第三方通道时，需要按文档配置，不能走默认的 OAuth 登录流程。具体配置看 https://taotoken.net/doc 里的 Claude Code 章节，里面有 Base URL、Key、Model ID 三件套的完整设置。

报错八：x509: certificate signed by unknown authority

Metrics Server 连 Kubelet 时的证书校验失败。加--kubelet-insecure-tls即可。如果不想跳过校验，需要把 Kubelet 证书的 CA 挂进 Metrics Server 容器，这个配置复杂一些，自建集群一般直接用 insecure 参数。

排查时记住一个原则：先看 Pod 状态，再看 APIService 状态，最后看 raw API。这三步能把问题范围缩到最小。TaoToken 侧的报错，先确认 Key 和 Base URL，再看网络和格式。

6. 把集群 AI 调用统一到 TaoToken 的长期做法

Metrics Server 装完、kubectl top出数之后，回到那个更长期的问题：集群里越来越多的 AI 工具，凭据怎么管。我试过在每个工具的配置里各写一份 Key，结果是轮换 Key 的时候要改十几个地方，配额超了也不知道是哪个工具用的。后来把这些调用统一到 TaoToken 的通道，Key 只维护一份，配额在控制台集中看，省事很多。

具体做法是：所有需要调模型的 Pod，都从同一个 Secret 读 Key，Base URL 统一指向https://taotoken.net/api。新工具接入时，只需要挂这个 Secret、设好 Model ID，不用再去申请新 Key。轮换 Key 时，更新一次 Secret，滚动重启相关 Deployment 就行。

如果你跑的是长期编码任务或者 Agent 类工作负载，可以考虑用 Coding Plan，配额和计费方式更适合持续调用。控制台在 https://taotoken.net/console ，能看到用量和配额。模型对话的调试入口在 https://taotoken.net/models ，想快速验证某个模型能不能用，直接在那里试。

集群侧的 Secret 管理，建议配合 RBAC 限制读取权限，只有需要调模型的 ServiceAccount 能读这个 Secret。这样即使某个 Pod 被攻破，也不会泄露 Key 到其他命名空间。

最后给一个实用技巧：把 Metrics Server 的--metric-resolution和你的监控采集周期对齐。默认 15s，如果你用 Prometheus 采集间隔是 30s，那 Metrics Server 采 15s 有一半数据是浪费的，改成 30s 能省点资源。这个参数在 YAML 的 args 里，改完重新 apply 即可。

整套流程走下来，kubectl top报错到出数，AI 调用从散落 Key 到统一通道，两件事都收敛了。后面再遇到metrics not available，按第二节的前置检查和第五节的报错对照走一遍，基本能定位。