# 在 Kubernetes 中进行调试

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

IntelliJ IDEA 支持以下 Kubernetes 调试流程：使用临时容器对 Pod 进行即时故障排除以及使用 Telepresence 进行远程调试，因此您无需离开您的 IDE 即可诊断各种问题。

Procedure: 启用 Kubernetes 插件

此功能依赖于 [Kubernetes](https://plugins.jetbrains.com/plugin/10485-kubernetes) 插件，该插件默认在 IntelliJ IDEA 中捆绑并启用。 如果相关功能不可用，请确保您没有禁用插件。

> **Note:**
> 在未订阅 Ultimate 版的情况下，IntelliJ IDEA 中无法使用 Kubernetes 插件。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

2. 找到  Kubernetes  插件，然后点击   启用  。

## 临时容器

IntelliJ IDEA 支持将 [临时容器](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/) 附加到正在运行的 Pod，而无需重启。 这样，您可以检查实时的 Kubernetes 环境，运行诊断命令，并在正在运行的 Pod 内直接调查问题。

临时容器会为调试目的临时添加到现有 Pod 中，并与您的应用容器并行运行。 为此，IntelliJ IDEA 会在幕后运行  `kubectl debug`  命令。 您可以附加自定义调试容器，或使用轻量级的 BusyBox 镜像，其开箱即用地提供  `ping` 、  `netstat` 、  `wget`  和  `top`  等常用工具。

有关调试正在运行的 Pod 的更多详情，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/)。

Procedure: 将 BusyBox 附加到正在运行的 Pod

1. 打开 [服务](services-tool-window.html) 工具窗口：转到  `查看 | 工具窗口 | 服务`  或按 `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))。

2. 展开列出正在运行的 Pod 的节点，右键点击要调试的 Pod，然后在上下文菜单中选择  `临时调试容器 | 附加 Busybox` 。

或者，选择所需的 Pod，点击工具栏上的 ![临时容器图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png)，并在下拉列表中选择   附加 Busybox  。

![附加 BusyBox](https://resources.jetbrains.com.cn/help/img/idea/2026.3/kubernetes_attach_busybox_container.png)

Procedure: 将自定义容器附加到正在运行的 Pod

1. 打开 [服务](services-tool-window.html) 工具窗口：转到  `查看 | 工具窗口 | 服务`  或按 `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))。

2. 展开列出正在运行的 Pod 的节点，右键点击要调试的 Pod，然后在上下文菜单中选择  `临时调试容器 | 附加自定义` 。

或者，选择所需的 Pod，点击工具栏上的 ![临时容器图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png)，并在下拉列表中选择   自定义附加  。

3. 在   附加自定义调试容器   对话框中，使用以下字段自定义用于启动并附加临时容器的  `kubectl debug`  命令：

* Pod ：从下拉列表中选择您要调试的 Pod。

* 目标 ：指定所选 Pod 内的目标容器。

* 图像 ：开始键入用于调试的镜像名称，然后从建议列表中选择它。

* 可执行文件 ：指定在临时容器启动后在其中运行的 Shell 的绝对路径（例如，BusyBox 使用 `/bin/sh` ，或 Ubuntu 使用 `/bin/bash` ）。

* 选项 ：为调试容器提供其他配置参数。 示例请参阅 [Kubernetes 文档](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_debug/)。

![附加自定义调试容器对话框](https://resources.jetbrains.com.cn/help/img/idea/2026.3/kubernetes_attach_custom_container.png)

> **Tip:**
> 将鼠标悬停在 ![预览命令](https://resources.jetbrains.com.cn/help/img/idea/2026.3/clouds-kubernetes.icons.newui.consoleCommand.png) 图标上，可预览生成的  `kubectl debug`  命令。

4. 点击   附加到 Pod  。

当 IntelliJ IDEA 启动新的临时容器并成功将其附加到 Pod 时，会打开   控制台   选项卡，您可以在其中运行命令并检查该 Pod。

![调试控制台](https://resources.jetbrains.com.cn/help/img/idea/2026.3/kubernetes_busybox_container_console.png)

如果您 [附加 BusyBox](#attach-busybox-container-to-pod)，IntelliJ IDEA 会自动使用  `sh` 。 对于 [自定义镜像](#attach-custom-container-to-pod)， IDE 使用   可执行文件   字段中指定的 Shell。

当您删除其所附加的 Pod 时，该容器将被移除。

### 最近命令

通过   临时调试容器   菜单附加临时容器时，IntelliJ IDEA 会自动保存相应的  `kubectl debug`  命令。 稍后您可以在   最近   部分访问并重新运行它。

![最近命令](https://resources.jetbrains.com.cn/help/img/idea/2026.3/kubernetes_recent_commands.png)

Procedure: 使用最近命令启动临时容器

1. 打开 [服务](services-tool-window.html) 工具窗口：转到  `查看 | 工具窗口 | 服务`  或按 `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))。

2. 展开列出正在运行的 Pod 的节点，并右键点击要调试的 Pod。 在上下文菜单中选择   临时调试容器   以及所需的最近命令。

或者，选择所需的 Pod，点击工具栏上的 ![临时容器图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/clouds-kubernetes.icons.newui.ephemeralStoppedContainer.png)，并在下拉列表中选择该最近命令。

Procedure: 管理最近命令

1. 访问最近命令：

* 在 设置 对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，选择 `构建、执行、部署 | Kubernetes | 集群交互` 。

* 打开 服务 工具窗口 ( `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS)))。 右键点击任意正在运行的 Pod，并在上下文菜单中选择 `临时调试容器 | 编辑最近使用` 。

2. 导航到   临时调试容器   部分。

* 要添加可预先配置并快速启动新临时容器的新命令，请点击 ![加号图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg)。 在 添加调试形参 对话框中，您可以为 `kubectl debug` 命令指定镜像、可执行文件和选项。

* 要从最近中移除命令，请在表格中选择它并点击 ![减号图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.remove.svg)。

* 要编辑现有命令，请在表格中选择它并点击 ![编辑图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.edit.svg)。 在 添加调试形参 对话框中，更改 `kubectl debug` 命令的镜像、可执行文件和选项。

## Telepresence

[Telepresence](https://telepresence.io/docs/quick-start) 是一款工具，它让您访问 Kubernetes 集群中的服务，对其进行调试、进行更改并测试，就像这些服务在您的计算机上本地运行一样。

Telepresence   插件与   Kubernetes   插件协同工作，并允许执行以下操作：

* [连接至 Telepresence](#connect-to-telepresence) 以通过其 DNS 名称访问集群中的服务。

* [拦截服务](#intercept-traffic-from-cluster) 将集群的流量路由到您的本地环境。

Procedure: 安装 Telepresence 插件

此功能性依赖于 [Telepresence](https://plugins.jetbrains.com/plugin/34535-telepresence) 插件，需要安装并启用该插件。

> **Note:**
> 在未订阅 Ultimate 版的情况下，IntelliJ IDEA 中无法使用 Telepresence 插件。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

2. 找到  Telepresence  插件，然后点击   安装  。 如果出现提示，请重启 IDE。

Procedure: 连接 Telepresence

1. 打开 [服務](services-tool-window.html)工具窗口：选择  `查看 | 工具窗口 | 服务` 或按 `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))。

2. 右键点击 Kubernetes 集群并选择   连接 Telepresence  。 或者，点击工具栏中的 ![Telepresence 图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.actions.split.svg)。 当系统提示时，请输入用于启动 Telepresence 守护进程的管理员帐户密码。 在 Windows 上，允许执行  `telepresence.exe` 。

> **Tip:**
> 在 macOS 和 Linux 上，如果您的计算机上未安装 Telepresence，将会出现通知，提供安装选项。 Telepresence 将安装在  `/usr/local/bin` 。 同样，如果集群中未安装 [Traffic Manager](https://www.getambassador.io/docs/telepresence-oss/latest/install/manager)，IntelliJ IDEA 将提示您安装它。
>
>
>
> 在 Windows 上，请按照 [Telepresence 安装文档](https://www.getambassador.io/docs/telepresence/latest/install?os=windows)。

3. 安装 Telepresence 和 Traffic Manager 后，再次点击   连接 Telepresence  。

您现在可以通过 DNS 名称访问 Kubernetes 集群中的服务，就像集群在您的工作站上运行一样。 例如，如果您有一个应用程序接受  `hello-node:9001`  请求，可以通过其名称访问。

Procedure: 拦截来自集群的流量

拦截允许您将流向 Kubernetes 集群中服务的流量路由到本地服务。

1. 在工具栏上，点击 ![Telepresence 图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.actions.split.svg) (   创建新拦截  )，然后点击   创建新拦截  。

2. 在打开的窗口中，在   服务  列表中，选择要拦截的工作负载。 这可以是一个 Deployment、ReplicaSet 或 StatefulSet。

在   端口   字段中，指定您的服务的本地实例运行的端口。

如果成功拦截了该服务，您可以在本地访问它并使用 IDE 功能来尝试、调试和分析在集群中运行的应用程序。

Procedure: 退出 Telepresence

Telepresence 一次与一个集群交互，因此在连接到另一个集群之前，您可能需要停止它。 退出 Telepresence 将停止所有活动的拦截。

1. 打开 [服務](services-tool-window.html)工具窗口：选择  `查看 | 工具窗口 | 服务` 或按 `Alt+8` (Windows), `⌘ 8` (macOS), `⌘ 8` (IntelliJ IDEA Classic (macOS)), `⌘ 8` (macOS System Shortcuts), `Alt+8` (XWin), `Alt+8` (GNOME), `Alt+8` (KDE), `Alt+8` (Emacs), `Alt+8` (Sublime Text), `⌘ 8` (Sublime Text (macOS)), `Alt+8` (Visual Studio), `Alt+8` (Visual Studio (macOS)), `Alt+8` (NetBeans), `Alt+8` (Eclipse), `⌘ 8` (Eclipse (macOS))。

2. 右键点击 Kubernetes 集群并选择   退出 Telepresence  。 或者，点击工具栏中的 ![退出 Telepresence 图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.exit.svg)。

### 以拦截方式运行应用程序

在 IntelliJ IDEA 中，只需点击一次，即可运行本地应用程序，同时将发往 Kubernetes 集群中某个服务的流量重定向到此本地应用程序。

这是通过配置到您的 Kubernetes 集群的隧道（Telepresence 拦截）并 [将其作为

启动前任务
添加到您的运行配置中](#add-interception-in-your-run-configuration)来实现的。 每次您 [运行此运行配置](#run-application-and-intercept-service)时，IntelliJ IDEA 都会创建一个 Telepresence 拦截，使您能够像在本地运行一样调试远程应用程序。

> **Tip:**
> 此功能当前支持以下运行/调试配置：
>
>
>
> * 应用程序 （适用于 Java 应用程序）、 Kotlin 和 Spring Boot
>
> * Go Build
>
> * Python 、 Django 、 Flask 框架 和 FastAPI
>
> * Node.js 、 Bun 和 Deno
>
> * Cargo

Procedure: 将拦截器添加到您的运行配置中

1. 确保：

* 您的服务的原始实例已部署并在 Kubernetes 集群中运行，其本地实例的源代码已在您的编辑器中打开。

* 您的 IntelliJ IDEA 实例已 [连接到您的 Kubernetes 集群](kubernetes.html#add-cluster)。

2. 点击主类声明附近装订区域中的 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.gutter.run.svg)，然后选择   添加用于远程调试的隧道  。 如果在 IntelliJ IDEA 中至少连接了一个集群，则此操作可用。

或者，如果您的应用程序已经存在运行/调试配置，请在运行小部件中点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.moreVertical.svg) 并选择   添加用于远程调试的隧道  。

3. 在打开的   将 Kubernetes 隧道添加到运行配置   窗口中，选择集群和命名空间，然后点击   连接到集群  。 当系统提示时，请输入用于启动 Telepresence 守护进程的管理员帐户密码。

> **Tip:**
> 如果 Telepresence 未安装在您的计算机上，或者 [Traffic Manager](https://www.getambassador.io/docs/telepresence-oss/latest/install/manager) 未安装在您的集群中，将会出现相应的通知，IntelliJ IDEA 将帮助您安装它们。

4. 如果您已成功连接到集群，请配置拦截参数：

* 在 服务 列表中，选择要拦截的 workload

* 在 端口 字段中，指定您的服务的本地实例运行的端口。

* 可以选择为 `telepresence intercept` 命令指定附加选项。

如果您想查看 Telepresence 命令的输出，请展开   输出  部分。 如果您在连接 Telepresence 时遇到任何错误，此部分将自动展开。

5. 点击   保存配置  。 若要检查截取参数，IntelliJ IDEA 将创建一个拦截，然后离开它。

截距参数将以   添加调试隧道   的形式保存在新的运行配置中的启动任务之前。 为了将其与其他运行配置区分开来，此运行配置名称将包含   (Telepresence)  后缀，例如   MyApp (Telepresence)  。

您现在可以准备 [运行您的应用程序并拦截其远程版本](#run-application-and-intercept-service)。

Procedure: 以拦截方式运行应用程序

1. 在运行小组件中，选择带有   (Telepresence)  后缀的运行配置。

2. 点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.gutter.run.svg) 运行，或点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.run.debug.svg) 启动调试器会话。

这将运行您的本地应用程序，同时将使用上述指定的参数运行  `telepresence intercept`  命令。

Telepresence 现在会拦截所有进入集群中某个服务的流量，并将其路由到您的本地应用程序。 您可以在本地编写代码并调试您的 intercepted service。

服务   工具窗口将在   遥程拦截   节点下显示创建的拦截。 您的 Kubernetes 集群的根节点还将显示生成的 telepresence 命令以及相关日志。

当您停止此应用程序（通过点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.run.stop.svg)），IntelliJ IDEA也会停止拦截（  `telepresence leave` ）。

