如何在IntelliJ中远程调试Kubernetes内的Spring Boot Native Image？

问题概述 #

无法通过IntelliJ远程调试由spring-boot-maven-plugin生成、运行在Kubernetes中的Spring Boot Native Image。已使用-g构建选项添加调试信息，且在插件中配置了JVM调试参数，但连接远程调试器时出现端口连接拒绝错误，不过端口转发8080可正常工作。

错误信息 #

执行端口转发命令后出现如下错误：

k port-forward my-service-65fb694c9b-swzqz 5005
Forwarding from 127.0.0.1:5005 -> 5005
Forwarding from [::1]:5005 -> 5005
Handling connection for 5005
E0612 11:25:35.287370  675301 portforward.go:413] an error occurred forwarding 5005 -> 5005: error forwarding port 5005 to pod 5e8effc4007042dadd57666ae576b3649edc116ec0192e5c34b371a45a5e5832, uid : failed to execute portforward in network namespace "/var/run/netns/cni-eab6b185-a501-d62e-b4a5-a4b3065153cb": failed to connect to localhost:5005 inside namespace "5e8effc4007042dadd57666ae576b3649edc116ec0192e5c34b371a45a5e5832", IPv4: dial tcp4 127.0.0.1:5005: connect: connection refused IPv6 dial tcp6: address localhost: no suitable address found 

当前POM配置 #

[...]
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

[...]

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>${maven-compiler-plugin.version}</version>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>${org.mapstruct.version}</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
                <version>0.2.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <configuration>
        <debug>true</debug>
        <verbose>true</verbose>
    </configuration>
</plugin>

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <jvmArguments>-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005</jvmArguments>

        <image>
            <env>
                <BP_NATIVE_IMAGE_BUILD_ARGUMENTS>-J-Xmx8g --parallelism=2 -g</BP_NATIVE_IMAGE_BUILD_ARGUMENTS>
            </env>

            <publish>true</publish>
            <pullPolicy>IF_NOT_PRESENT</pullPolicy>
            <tags>
                <tag>${docker.repository.external.url}/repository/docker/${project.name}:${project.version}
                </tag>
            </tags>
            <name>${docker.repository.external.url}/repository/docker/${project.name}</name>
        </image>

        <excludes>
            <exclude>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
</plugin>

补充信息 #

现有命令行方式调试Spring Native镜像的流程复杂耗时，部分IDE（如Eclipse）已支持将底层调试器操作转化为Java风格调试UI，但IntelliJ相关插件缺乏文档，Quarkus已有成熟的Native远程调试方案可参考。

解决办法 #

核心问题说明 #

Spring Boot Native Image是编译后的二进制可执行文件，不是JVM进程，因此你配置的-Xdebug/-Xrunjdwp这类JVM调试参数完全无效，这是导致端口连接失败的根本原因。

正确调试步骤 #

1. 确认构建产物包含调试信息
   你的POM配置已经满足：native-maven-plugin的<debug>true</debug>会自动添加-g参数，同时BP_NATIVE_IMAGE_BUILD_ARGUMENTS也显式指定了-g，确保Native镜像包含调试符号，这部分无需修改。

2. 配置容器启动参数与K8s端口
   GraalVM Native Image支持通过--debug=<port>参数开启调试监听，需要修改容器启动命令：

   • 如果使用Spring Boot插件构建镜像，可在<image>配置中添加启动参数，或者修改Deployment的command字段，在启动命令末尾追加--debug=5005
   • 确保K8s Deployment的ports字段包含containerPort: 5005，暴露调试端口

3. IntelliJ配置Native调试

   • 安装GraalVM Native Debugger插件
   • 创建Native Debug类型的运行配置：
     • 设置Host为localhost，Port为5005
     • 指定本地构建生成的Native可执行文件路径（需与容器内二进制完全一致，必须是同一次构建产物）
   • 先执行端口转发：kubectl port-forward <你的Pod名称> 5005:5005
   • 启动IntelliJ的Native Debug配置，即可连接调试

4. 备选方案：GDB远程调试
   如果IDE插件无法正常工作，可使用GDB命令行调试：

   • 本地安装与容器兼容版本的GDB
   • 端口转发后，执行gdb <本地Native可执行文件路径>，在GDB交互界面输入target remote localhost:5005即可连接远程进程

注意事项 #

• 执行kubectl exec <Pod名称> -- ps aux查看进程命令行，确认容器内Native程序已添加--debug=5005参数
• 本地Native可执行文件必须与容器内完全一致，否则调试时会出现符号不匹配，无法正确映射代码
• 若使用Buildpack构建镜像，可通过设置环境变量或修改启动脚本确保调试参数生效

内容的提问来源于stack exchange，提问作者Daniele