排障
按症状查:先看判断依据,再动手。每一节都来自交付中真实遇到的问题。
← 文档索引
以下是我们在交付过程中真实遇到过的几个卡点。先看这里,再来找我们。
istioctl / kubectl 连不上集群(microk8s)
microk8s 的凭据不在 ~/.kube/config。手动安装的工具会读默认路径,于是报连不上:
mkdir -p ~/.kube
sudo microk8s config > ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
microk8s kubectl 不受影响——它直连 snap 内的凭据。
确认实际运行的 Istio 版本
手动装 Istio 时,istioctl version 可能因为命名空间或 revision 不同而"看不见"。
最可靠的办法是直接看镜像标签:
kubectl get pods -A -l app=istiod \
-o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'
多版本共存时,还要确认默认注入用的是哪个 revision:
istioctl tag list
登录成功后无限跳回登录页
现象是地址栏在控制台与身份服务之间反复跳转,看起来像"登录没成功",实际登录已经成功。
原因在控制台的处理逻辑:网关返回任何以 Access Denied: 开头的 GraphQL 错误,前端都会当成
"未登录"重新发起登录;而身份服务那边的 SSO 会话还在,跳转是静默的,于是一圈接一圈。
判断只看一处:DevTools → Network → POST /graphql → Response 里的 errors[0].message。
| 错误文本 | 含义 | 处理 |
|---|---|---|
Access Denied: Authentication required |
请求没带 Authorization 头 |
查 POST /api/auth/token 是否返回 200;401 说明会话 cookie 没种下或解不开,见「多副本必须同值」 |
Access Denied: <jwt 报错>(invalid signature / invalid algorithm / malformed) |
网关公钥不是身份服务当前那把 | 换成当前签名公钥并重启网关,见 tethys-gateway 一节 |
Access Denied: Malformed token claims |
token 里缺 id 或 roles |
身份服务的 token 结构与网关预期不一致 |
Access Denied: ADMIN role required |
账号没有 ADMIN 角色 |
不会循环,界面提示后停下;给账号补角色后重新登录 |
顺带一个区分办法:如果循环是偶尔能进、刷几次才循环,更像 web 多副本的密钥不一致; 如果每次都必然循环,更像网关公钥不对。
浏览器报 CORS 错误,或同一域名下 /graphql 是 404
先在同一个域名下对比两条路径:/api/v1/namespaces 这类 REST 路径能返回数据、/graphql
却是 404,且预检(OPTIONS)返回 204 但没有 Access-Control-Allow-Origin——这不是 CORS
配置问题,而是这个主机名绑定到了错误的微服务。
排查顺序:
- 确认
gateway.titanides.com只绑定在tethys-gateway上。控制台里同一主机名如果还挂在别的 微服务(例如tethys-shipping)上,后绑定的会生效。 - 解绑重复项后,
/livez应返回{"status":"ok"}。 - 再查网关的
CORS是否包含控制台 Origin(注意协议和端口都要对)。 - 改完重启网关:
CORS只在进程启动时读取。
不要用响应里的
Server头判断上游是谁——边缘 nginx 会给所有响应都加上自己的Server, 健康的 Next 服务也会有。看响应体与x-envoy-upstream-service-time更可靠。
实时列表不刷新,控制台报 WebSocket 错误
WebSocket 走的是网关的独立代理配置,和 GraphQL 不是同一条链路:
SHIPPINGWS_ENDPOINT的 host 填 Shipping 的 Service 名,不要加basePath——/watch、/xterminal挂在 Shipping 的根路径。WS_PROXIES要把每个 watch 路径逐条列出。匹配是整条 pathname 精确比对,没有前缀匹配; 少一条就只有那一路断,其他功能正常。- 浏览器侧
wsEndpoint.BASEPATH必须等于网关公共路径的前缀(默认shippingws),即最终 地址形如wss://console.titanides.com/shippingws/watch/api/v1/namespaces。
改完 WS_PROXIES 同样要重启网关。
Bundle apply 成功但没有任何 Pod
operator 没起来,或 CRD 没装。见「底座安装」里的「安装 PackingTable operator」。
排障速查
| 现象 | 先看哪里 |
|---|---|
Pod ImagePullBackOff |
镜像串是否符合 {registry}/{app}:{version};app 是否等于镜像仓库名;tag 是否存在;目标租户有没有拉取 Secret。可用 docker manifest inspect <repo>:<tag> 在不暴露凭据的前提下确认镜像 |
Pod Waiting / 一直不就绪 |
Deployment 已创建但容器没起来:看事件、镜像架构(Apple Silicon 构建需 --platform linux/amd64)、必填环境变量、挂载 Secret 是否存在 |
Bundle phase: Failed |
status.message 与 conditions;最常见是版本身份(releaseVersion,或从 tag 推断出的 vN)不大于当前版本、带点号,或者镜像不存在 |
Bundle 一直 Provisioning |
operator 是否在运行、CRD 是否已安装、operator 的 ServiceAccount 权限是否足够 |
CR 卡在 Terminating |
finalizer 名与 KubeOps 注册名是否一致(fewbox.com/<kind>finalizer) |
| 导入返回 413 | 网关 GRAPHQL_BODY_LIMIT 与边缘 nginx 的 client_max_body_size 两层都要调 |
| 登录成功但网关一直判未登录 | IDP_SESSION_SECRET 是否在 auth / gateway / payment 三处同值;JWT 公钥是否来自当前签名密钥 |
页面提示 Access Denied: invalid signature |
验签公钥与 auth 的签名私钥不是一对,或 kid 已轮换但公钥没更新 |
| agent 的 MCP 工具不可用 | *_ENDPOINT 是否带 /mcp 路径、指向正确的 Service 短名;对应 MCP Pod 是否健康 |
| 定时任务不执行 | schedule 是否为合法 cron 表达式;CronJob 是否因镜像/权限失败被挂起 |