远程调试原理

理解其工作原理非常重要，远程调试的本质是 在本地启动一个调试服务器，让远程应用的 JVM 以“客户端”的身份连接到这个服务器。

整个过程可以想象成一个反向的 TCP 连接：

1. 调试会话启动：你在本地的 Eclipse 中启动一个“调试”配置，Eclipse 会启动一个调试服务器，这个服务器在指定的端口上监听连接请求（5005）。
2. 远程应用启动：你需要在远程服务器上，以特殊参数启动你的 Java 应用，这些参数会告诉应用的 JVM：
   • -Xdebug: 启用调试模式。
   • -Xrunjdwp: 加载 JDWP (Java Debug Wire Protocol) 代理，这是调试器与 JVM 之间通信的协议。
   • transport=dt_socket: 使用套接字进行通信。
   • server=y/n: y 表示 JVM 作为服务器，等待调试器连接；n 表示 JVM 作为客户端，主动连接调试器，远程调试通常用 y。
   • suspend=y/n: y 表示 JVM 启动后立即挂起，等待调试器连接上之后再继续执行代码，这对于在 main 方法第一行就打断点非常有用。n 表示 JVM 启动后立即运行，如果调试器未连接，它会继续执行,断点不会生效。
   • address=<port>: 指定监听的端口号（5005），必须和 Eclipse 中配置的端口一致。
   • quiet=y: 减少调试模式的冗余输出。

关键流程图：

+-------------------------+                          +------------------------+
|      Eclipse (本地)     |                          |   远程服务器 (Linux/...) |
|                         |                          |                        |
|  +-------------------+   |                          |  +------------------+   |
|  |  Debug Server    |<--(监听端口 5005)-------------->|  |  JVM (你的应用)   |   |
|  |  (JDWP Agent)     |   |                          |  |                  |   |
|  +-------------------+   |                          |  +------------------+   |
|                         |                          |                        |
+-------------------------+                          +------------------------+
       (调试器)                                         (被调试的客户端)

详细步骤

假设场景：我们想调试一个部署在远程 Linux 服务器上的 Spring Boot 应用（JAR 包）。

第 1 步：在远程服务器上以调试模式启动应用

这是最关键的一步，你需要找到启动你应用的命令，并在其前面加上 JVM 调试参数。

假设你的应用启动脚本如下：

java -jar my-spring-boot-app.jar

修改后的启动命令（调试模式）：

# 挂起，等待调试器连接，监听端口 5005
java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005 -jar my-spring-boot-app.jar

参数解释：

• -Xdebug: 启用调试功能。
• -Xrunjdwp:...: 加载 JDWP 代理。
• transport=dt_socket: 使用 TCP 套接字通信。
• server=y: JVM 作为服务器，等待 Eclipse 连接。
• suspend=y: JVM 启动后立即暂停，直到调试器连接,这让你可以在应用初始化阶段就设置断点。
• address=5005: 监听端口，请确保这个端口在远程服务器上是开放的,并且没有被占用。

如何执行？

1. 直接在命令行运行：如果应用是前台运行的,直接执行上述命令即可。

2. 通过脚本（如 nohup）后台运行：如果需要后台运行，可以使用 nohup 或 systemd。

   # 使用 nohup 后台运行，并输出日志到 nohup.out
   nohup java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005 -jar my-spring-boot-app.jar > nohup.out 2>&1 &

3. 对于 Tomcat 等服务器：你需要修改 CATALINA_OPTS 环境变量。

   # 在 catalina.sh 或 setenv.sh 中添加
   export CATALINA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
   # 然后启动 Tomcat
   ./startup.sh

执行后，你的远程应用会启动，但会卡住，打印出类似 Listening for transport dt_socket at address: 5005 的信息,等待你的连接。

第 2 步：在 Eclipse 中创建远程调试配置

1. 打开 Debug Configurations：

   • 点击菜单栏的 Run -> Debug Configurations...。
   • 或者使用快捷键 Alt + Shift + D + R。

2. 新建远程 Java 应用：

   • 在左侧的 Debug Configurations 窗口中，右键点击 Remote Java Application -> New。
   • 你会看到一个配置界面。

3. 配置参数：

   • Name: 给这个配置起一个容易识别的名字，Debug MyApp on Remote Server。
   • Project: 选择你的 Java 项目，Eclipse 需要知道源代码的位置,以便在断点处显示正确的代码。
   • Connection Type: 通常保持默认的 Standard (Socket Attach)。
   • Host: 填写远程服务器的 IP 地址或域名。
   • Port: 填写你在远程服务器上指定的端口号（5005）。

   

4. 应用并关闭：

   • 点击 Apply 和 Close 保存配置。

第 3 步：设置断点并启动调试

1. 设置断点：

   • 在你的 Eclipse 项目中，找到你想调试的 Java 文件。
   • 在代码行号左侧的灰色区域双击，会出现一个蓝色的圆点,这就是断点。

2. 启动调试会话：

   • 确保远程服务器上的应用已经以调试模式启动并正在等待连接。
   • 在 Eclipse 的右上角，切换到 Debug 视图（如果不在的话）。
   • 在下拉菜单中选择你刚刚创建的配置（Debug MyApp on Remote Server）。
   • 点击旁边的 "Debug" 按钮（虫子图标）。

3. 连接成功：

   • 如果一切顺利，Eclipse 会成功连接到远程的 JVM。
   • 远程服务器上的应用会从 suspend=y 的状态恢复,开始执行代码。
   • 当执行到你设置的断点时，远程应用会暂停，Eclipse 会切换到 Debug 视图，高亮显示断点所在的代码行,并显示所有变量的值。

高级技巧与常见问题

suspend=n 的使用场景

有时你不希望应用在启动时就挂起，调试一个已经在线上运行的服务，你可以将 suspend 设为 n。

远程启动命令：

java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 -jar my-spring-boot-app.jar

这样应用会立即启动并运行，你可以在任何时候通过 Eclipse 连接，连接成功后，你之前设置的断点才会生效,这对于在不重启服务的情况下进行热调试非常有用。

防火墙问题

连接失败最常见的原因是防火墙。

• 在远程服务器上：确保 5005 端口（你配置的端口）对 Eclipse 所在的机器开放。

  # 检查端口是否被占用
  netstat -tlnp | grep 5005
  # 如果使用 iptables，开放端口
  iptables -I INPUT -p tcp --dport 5005 -j ACCEPT
  # 如果使用 firewalld (CentOS 7+)
  firewall-cmd --permanent --add-port=5005/tcp
  firewall-cmd --reload

• 在企业网络中：可能需要网络管理员在防火墙上开放从你的开发机到远程服务器的指定端口。

address 端口冲突

如果远程服务器上 5005 端口已经被占用，JVM 会启动失败，请更换一个未被占用的端口，8000，并确保 Eclipse 和远程服务器的配置都使用这个新端口。

源码不匹配

如果远程服务器上运行的 JAR 包中的 .class 文件与你 Eclipse 项目中编译出的版本不一致（你修改了本地代码但没有重新打包部署），那么断点将无法正确命中，Eclipse 可能会提示 Source not found。

解决方案：

• 确保远程部署的是最新的代码版本。
• 如果无法重新部署，可以配置 Eclipse 的 "Source Lookup"，但这比较复杂,通常不推荐。

调试 Tomcat 时的 CATALINA_OPTS

对于 Tomcat，最佳实践是创建一个 setenv.sh 文件（在 CATALINA_BASE/bin/ 目录下），而不是直接修改 catalina.sh，这样可以避免升级 Tomcat 时覆盖你的修改。

setenv.sh 内容示例：

#!/bin/sh
export CATALINA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005 -Xms512m -Xmx2048m"

使用 Maven/Gradle 插件（可选）

对于现代项目，你也可以使用构建工具插件来简化启动流程，Spring Boot Maven 插件就内置了调试功能。

在 pom.xml 中添加：

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

然后你就可以通过 mvn spring-boot:run 来启动一个可调试的应用。

Eclipse 远程调试是一个分两步走的过程：

1. 远程端：用 java -Xdebug ... 参数启动应用,让它成为一个等待连接的调试服务器。
2. 本地端：在 Eclipse 中配置一个 Remote Java Application，指定服务器的 IP 和端口,然后启动调试器进行连接。

掌握这个流程后，你就能轻松调试任何远程的 Java 应用,极大地提高开发和排错效率。