okteto-debugging

Okteto 环境调试器

此技能用于排查故障的 Okteto 环境。当服务运行异常时，按以下排查算法逐步检查，应用匹配的操作手册，并输出结构化诊断。不要猜测——始终根据命令输出得出结论。

诊断操作均为只读：这里可以使用 kubectl get、kubectl describe、kubectl logs 和 kubectl get events。绝不要使用原始 kubectl/helm 修改集群——修复应通过 okteto build 和 okteto deploy 完成（生命周期操作、工作树隔离和拆除规则请参阅 okteto 技能）。

排查算法

按顺序执行以下步骤。找到故障后立即停止。

步骤 1：验证连接并确定命名空间

okteto context show

如果此命令失败，说明用户已与集群断开连接。停止排查，并先帮助用户重新连接（okteto context use <url>）。

JSON 输出中包含当前活动的 namespace。记录该值——以下所有命令都会通过 $ns 明确指定该命名空间：

ns=$(okteto context show | jq -r .namespace)

如果你正在隔离的工作树命名空间中工作（请参阅 okteto 技能），则使用该命名空间——要调试的环境位于该命名空间中，而非上下文的默认命名空间。

kubectl 必须指向与 Okteto 相同的集群和命名空间。 kubectl 使用自己的 kubeconfig，其指向的命名空间——甚至集群——可能与 Okteto 上下文不同，尤其是在同一台机器上有多个 Agent 或工作树处于活动状态时。运行 okteto kubeconfig，下载通过 okteto context 选定集群的凭据，并在每条 kubectl 命令中传入 -n "$ns"。如果 kubectl get pods -n "$ns" 报错，或显示的 Pod 与 okteto.yaml 中的服务不匹配，请先修正 kubeconfig，再采信任何诊断输出。

步骤 2：发现服务

cat okteto.yaml

解析 deploy 和 dev 部分，获取规范的服务名称。绝不要硬编码服务名称——始终从 okteto.yaml 中提取。

步骤 3：快照 Pod 状态

kubectl get pods -n "$ns"

这是排查的主要信号。将每个 Pod 对应到以下一种状态，并应用匹配的操作手册：

Pod 状态	操作手册
CrashLoopBackOff	崩溃循环
OOMKilled	OOM 终止
ImagePullBackOff / ErrImagePull	镜像拉取失败
Pending（> 60s）	无法调度
Running 但未提供服务 / 健康检查失败	运行时错误
不存在 Pod / 部署从未完成	部署失败
所有 Pod 均为 Running 且 Ready	同步 / 开发模式问题

如果用户指定了某个服务，仅筛选该服务的 Pod。如果未指定服务，则检查所有 Pod。

---

操作手册

崩溃循环（CrashLoopBackOff）

容器启动后崩溃，Kubernetes 会不断重启它。

# Get logs from the previous (crashed) container instance
kubectl logs <pod-name> --previous -n "$ns"

# If that fails (first crash, no previous), get current logs
kubectl logs <pod-name> -n "$ns"

# Check exit code and liveness/readiness probe config
kubectl describe pod <pod-name> -n "$ns"

检查以下内容：

• kubectl describe pod 中的退出代码——Exit Code: 1 表示应用错误；Exit Code: 137 表示 OOM（请参阅 OOM 操作手册）；Exit Code: 126/127 表示找不到入口点命令
• --previous 日志的末尾几行——崩溃前的最后一条错误通常就是根本原因
• kubectl describe pod 事件部分中的存活探针失败——健康检查路径或超时配置错误

常见根本原因：

• 缺少环境变量或环境变量错误（fatal: required env var FOO not set）
• 无法连接尚未就绪的依赖项（数据库、消息队列）
• 应用与探针配置的端口不匹配
• 找不到命令/入口点（基础镜像错误，或 okteto.yaml 中的 command 拼写错误）

OOM kill（OOMKilled）

容器超出内存限制，被 Kubernetes 终止。

kubectl describe pod <pod-name> -n "$ns"

查找：

• Last State 部分中的 OOMKilled
• Containers → Limits 下的 limits.memory 值
• 将限制值与服务实际需要的内存量进行比较

修复方式： 在服务的 Helm values 或 okteto.yaml 中提高内存限制。向用户显示当前的确切限制值，并建议合理提高（通常为 2 倍）。不要建议完全移除限制。

---

镜像拉取失败

Kubernetes 无法拉取容器镜像。

kubectl describe pod <pod-name> -n "$ns"

查找：

• Events 部分中的 Failed to pull image
• Kubernetes 尝试拉取的确切镜像引用（注册表、仓库、标签）
• ImagePullBackOff 和 ErrImagePull 的区别——两者含义相同，只是重试状态不同

常见根本原因：

• 镜像不存在（标签拼写错误，或从未为此服务运行过 okteto build）
• 镜像存在，但位于没有拉取凭据的私有注册表中
• 在一次错误的推送后，标签被删除或覆盖

修复方式： 如果镜像应由 Okteto 构建，请运行 okteto build <service>。如果镜像来自外部，请确认标签存在。如果问题出在凭据上，请帮助用户创建镜像拉取密钥。

---

Pending / 无法调度

Pod 已被 Kubernetes 接受，但尚未调度到节点上。

kubectl describe pod <pod-name> -n "$ns"

# Also check recent namespace events for quota / resource pressure
kubectl get events -n "$ns" --sort-by=.lastTimestamp | tail -20

在 kubectl describe pod → Events 中查找：

• Insufficient cpu 或 Insufficient memory——节点没有可用资源；检查资源请求
• 0/N nodes are available——没有节点符合调度约束
• node(s) had untolerated taint——Pod 需要容忍节点上的污点
• node(s) didn't match node affinity/selector——nodeSelector 或亲和性规则过于严格
• 超出资源配额——检查 kubectl describe resourcequota -n "$ns"

修复方式： 根据错误处理对应的约束。对于资源请求，降低请求值或请用户扩展节点池。对于污点或选择器，显示当前约束并建议将其移除或修正。

---

运行时错误（Running 但不健康）

Pod 处于 Running 状态，但服务没有响应、健康检查失败，或用户在请求中看到错误。

# Get recent application logs
okteto logs <service> --since 10m -n "$ns"

# If that's not enough context
okteto logs <service> --tail 200 -n "$ns"

查找：

• 堆栈跟踪或 panic: 行——记录源文件和行号
• 连接依赖项时出现拒绝连接或超时错误——服务已启动，但下游服务未启动
• 中间件或代理记录的 HTTP 5xx 错误
• “address already in use”——容器内端口冲突

修复方式： 引用堆栈跟踪或错误中最相关的 5–10 行。如果有源文件名称，请指出。建议具体修复方案，例如修改代码、补充缺失的环境变量，或启动依赖服务。

---

部署失败

Pod 从未出现——okteto deploy 在创建 Pod 之前就失败了。

# Check if the manifest is valid first
okteto validate

# Check deploy logs if validate passes
okteto logs --deploy -n "$ns"

查找：

• okteto validate 错误——YAML 语法、架构违规或缺少必需字段
• 部署日志中的 Helm 模板渲染错误
• 镜像构建失败（Dockerfile 错误、构建上下文过大）

修复方式： 如果是 okteto validate 检测到的问题，请显示确切错误和行号。如果是 Helm 错误，请显示模板路径。如果是构建错误，请显示失败的 Dockerfile 阶段。

---

同步／开发模式问题

所有 pod 都是 Running 和 Ready，但开发者的代码更改没有反映到开发容器中。

okteto status 会报告当前开发容器的文件同步状态。只有在 okteto up <service> 会话运行期间才能使用此命令——如果没有会话，就没有任何内容在同步；请告知用户启动会话。

okteto status -n "$ns"

# If the summary isn't enough, get syncthing troubleshooting links
okteto status --info -n "$ns"

请检查：

• Sync status: error 或 Sync status: paused
• 文件数量没有变化
• 同步输出中的路径与实际源目录不匹配

最有用的信息来自 okteto up 终端本身——同步错误和冲突警告会最先在那里显示，而你无法查看该会话。请让用户粘贴其输出。

修复方法： 检查 okteto.yaml 中的 sync 路径是否与实际目录结构一致。如果路径正确，尝试先运行 okteto down，再运行 okteto up <service>（用户必须以交互方式运行 okteto up——切勿自行运行）。如果同步卡住，okteto doctor 会生成诊断包。

---

输出格式

每个不健康的服务始终单独输出一个区块：

## Diagnosis: <service-name>
**Root cause:** <one sentence>
**Evidence:**
<relevant excerpt from logs or describe output — 5 to 20 lines, no more>
**Fix:**
<exact command to run or code change to make>
**Confidence:** High / Medium / Low

在以下情况下使用 Low 置信度：

• 容器只崩溃过一次（没有可用的 --previous 日志）
• 错误消息含糊不清或缺失
• 有多种可能的根本原因与现有证据相符

如果所有 pod 都健康，则报告：

All services are Running and Ready. No obvious failures detected.

If you're still seeing issues, run `okteto doctor` to generate a full diagnostic bundle.

---

常见注意事项

• kubectl 和 okteto 可能会给出不同结果 — kubectl 使用自己的 kubeconfig 上下文，该上下文可能指向与 Okteto 上下文不同的命名空间或集群。如果 kubectl 的输出与 okteto 命令报告的内容不一致，请运行 okteto kubeconfig，然后使用 -n "$ns" 重新检查，再得出任何结论。
• 首次崩溃时 kubectl logs --previous 会失败 — 容器必须至少重启过一次。请改用 kubectl logs（当前实例）或查看描述事件。
• 退出代码 137 = OOM，而非应用错误 — 如果在 CrashLoopBackOff 中看到 exit code: 137，请将其视为 OOM kill，而非崩溃循环。
• Pending pod 没有日志 — 完全跳过 kubectl logs，直接运行 kubectl describe pod + kubectl get events。
• okteto logs 与 kubectl logs — 查看应用输出时优先使用 okteto logs；需要 --previous 或需要 pod 名称来运行 describe 时，使用 kubectl logs。
• 调试时切勿运行 okteto destroy — 请先诊断。只有在环境无法恢复且用户明确提出要求时，才建议拆除环境。
• 切勿运行 okteto up — 该命令需要交互操作。如果修复需要重新进入开发模式，请告知用户在其终端中运行 okteto up <service>。